Job Specifications

A job specification must clearly communicate why the work exists and how it should be approached. A job is not a task until the problem and the proposed solution are understood.

This document is completed before development begins.

1. Problem Definition

Describe the real-world issue that needs addressing. This defines the context, not the implementation.

Business Problem

What pain or inefficiency does the client or user currently experience?

Example: Customers cannot update their delivery address after placing an order, resulting in support calls and manual database edits.

User Job To Be Done

What is the user trying to achieve?

Phrase this from the user's point of view.

Example: As a customer, I want to change my delivery address so my order goes to the right place without waiting for support.

Trigger / Catalyst

Why are we solving this now?

• A process change?
• A support burden?
• A new requirement?
• Something blocking another feature?

Evidence / Data (if applicable)

Any supporting facts, examples, screenshots, or logs that prove the problem exists.

2. Proposed Solution

Describe how Neon intends to solve the problem. This is the directional plan—not a step-by-step coding guide.

Solution Overview

What is the conceptual approach?

Example: Add an “Edit Address” action on the Order detail page, allowing changes until the order reaches the “Dispatched” status.

Scope of Work

What is included, and what is explicitly not included?

• Included:

  • UI to update delivery address
  • Validation on address fields
  • Audit log of changes

• Out of Scope:

  • Changing shipping method
  • Editing line items

Clarity here avoids assumptions.

UX Considerations

How should this feel from the user's perspective?

• Where does the action live?
• What happens on success or error?
• Is progress visible?

If mockups exist, link them here.

Acceptance Criteria

The behaviour that must be true for this job to be complete.

Example:

• A user can edit their delivery address before dispatch
• Validation prevents incomplete or invalid address data
• A confirmation message appears after saving
• Updated address is visible on the order summary

Each criterion should be testable and objective.

Technical Notes (Optional)

Constraints or decisions already made:

• Existing tables or models to update
• Events, jobs, or APIs involved
• Caveats, gotchas, dependencies

This is high-level guidance—not code.

3. Success Metrics

How do we know this job was worth doing?

Examples:

• Reduce support tickets related to address changes by 80%
• Customers successfully update addresses without staff intervention
• No failed deliveries caused by incorrect addresses

If no measurable outcome exists, the job is suspect.

4. Rollout / Risks (Optional)

• Any migration steps?
• Feature flags needed?
• Potential side effects?

This prevents surprises during deployment.

Definition of Ready

A job is ready for development when:

• The real-world problem is understood
• The proposed solution is agreed
• Acceptance criteria are clear
• No unanswered questions remain

If any of these are missing, the job returns to refinement.