SPEC.md
Feature specification
Turn an intended outcome into testable behavior, requirements, constraints, non-goals, edge cases, and acceptance evidence before selecting implementation details or decomposing the work.
Fillable structure
Replace prompts with project evidence.
Remove any field that does not apply. A smaller maintained file is more useful than generic documentation that agents and reviewers cannot trust.
- 01
Problem and outcome
Define the user-visible change and the evidence that it matters.
Problem: Describe the current workflow, pain, and affected user
Desired outcome: State the observable behavior or state change
Success measures: List product, quality, safety, and operational measures
- 02
Requirements and scenarios
Write behavior precisely enough that each scenario can become an objective acceptance test.
Primary scenarios: List trigger, inputs, expected behavior, and output for each core path
Edge scenarios: Cover missing, malformed, conflicting, unauthorized, canceled, and repeated actions
Data: Define required fields, provenance, retention, correction, and deletion
- 03
Constraints and non-goals
Prevent the implementation from silently expanding or violating a hard boundary.
Constraints: State security, privacy, compatibility, latency, cost, and compliance limits
Non-goals: List plausible adjacent work explicitly excluded
Open questions: Record unresolved ambiguity, owner, and deadline for each answer
- 04
Acceptance and traceability
Connect each requirement to evidence and later implementation work.
Acceptance checks: Write objective checks for every required behavior and important failure path
Approval: Name the product, design, security, legal, or operations reviewers required
Traceability: Link plan decisions, tasks, tests, eval cases, telemetry, and release evidence
Related field guides
Next template
PLAN.md · Implementation plan