START HERE
What you will learn
- Write observable acceptance criteria.
- Separate requirements, implementation choices and unknowns.
- Keep a specification aligned with the change it governs.
Before you start: For stakeholders, independent builders and technology leaders. Bring one workflow or software change you can describe.
What is the specification responsible for?
It explains whose problem is being solved, what should happen and what must remain unchanged. Include normal behaviour, failure behaviour and the authority needed to perform the work. A specification can be short when the change is small. A complex migration needs deeper investigation and staged decisions.
“Make search better” leaves the worker to invent the goal. “An authorised user can filter active records by postcode; invalid input produces a clear error; existing pagination remains available” offers behaviour that can be checked. It still needs decisions about matching rules and expected response times before those can become acceptance conditions.
From intent to implementation without losing the decision
A specification states the intended behaviour. A plan explains a proposed technical approach. Tasks divide that approach into bounded units. Tests produce evidence about selected expectations. Keep those artifacts related, but do not treat them as interchangeable.
GitHub Spec Kit is one example of tooling for carrying specifications into development. The broader practice does not require that toolkit, a particular model or a project-management product. Use a format your stakeholders can review and your pipeline can reference.
Handle unknowns and change explicitly
Do not ask an agent to silently decide unresolved business policy. Mark questions as open, assign a decision owner and block consequential implementation until an answer exists. If implementation reveals a contradiction, change the specification through review rather than quietly rewriting the acceptance criteria to fit the code.
A written requirement can still be wrong. Discuss examples with affected people and preserve a route for feedback. Tests verify selected behaviour; they cannot prove that the original product decision was worthwhile.
Technical examples
A bounded acceptance specification
Illustrative project-owned format, not a toolkit schema. A runner must explicitly interpret and enforce its rules; this file alone grants or restricts no access.
id: REPORT-01
owner: product-owner
objective: Allow a customer to download their own report
acceptance:
- id: AC-01
expect: Owner can download an available report
- id: AC-02
expect: Another customer cannot retrieve it through any endpoint
non_goals:
- Change billing or customer identity
permissions:
production_deployment: forbidden
open_decisions: []Step-by-step process
Describe the user outcome
Name the user, trigger, expected result and existing behaviour that must be preserved.
Resolve examples and exclusions
Write normal, invalid, unauthorised and unavailable-system examples. State what the task will not change.
Assign requirement identifiers
Give important expectations stable IDs and link each to checks and review evidence. Identify which require human judgement.
Review specification and implementation together
Check that code, tests and requirements changed consistently. Require explicit approval for scope or policy changes.
FOLLOW ONE EXAMPLE
Worked scenario
A stakeholder defining a report-download feature
A fictional business owner wants customers to download their own reports, while an agent handles implementation.
- The specification names report ownership, expiry behaviour and the error shown when a report is unavailable.
- A separate test account attempts to retrieve another customer’s report.
- The reviewer rejects a proposed shortcut that hides the download button but leaves the underlying URL accessible.
What this shows: Observable requirements expose the difference between interface behaviour and actual authorisation.
The process at a glance
Read Mermaid diagram source
flowchart LR
A[Human need] --> B[Examples and open questions]
B --> C[Reviewed specification]
C --> D[Implementation plan]
D --> E[Bounded tasks]
E --> F[Tests and human review]
F --> G{Meets the agreed need}
G -->|No| BWhat you should have at the end
- A reviewed specification with open decisions made explicit.
- A requirement-to-test map with a named acceptance owner.
Common mistakes and how to avoid them
Writing implementation details before agreeing behaviour
A list of components does not explain the user outcome. Establish the behaviour first.
Letting the agent relax its own acceptance criteria
Changes to requirements need the same review discipline as the original specification.
APPLY THE IDEA
Try it yourself
Your task: Specify a report-download workflow without prescribing a frontend framework.
What to produce: Five acceptance criteria covering ownership, missing reports, expired links, ordinary use and preserved behaviour.
Check your understanding: Could two reviewers independently decide whether the same implementation satisfies each criterion?
Key terms in plain English
- Specification
- An agreed description of intended behaviour and constraints.
- Acceptance criterion
- An expectation used to accept or reject a result.
- Non-goal
- A boundary identifying work intentionally outside the task.