Feature spec
The full-lifecycle template — the one you'll reach for most. Problem, scope, acceptance criteria, plan, and task breakdown in a single document that goes from blank page to build-ready.
Any new capability where being wrong is expensive: user-facing features, new integrations, new services, significant UX changes. If the work takes more than a day or involves more than one person (or agent), start here. For interfaces others build against, pair it with the API spec.
Section-by-section, annotated
§1 Header & revision block
Title, owner, status, and the revision block. The owner is the single person accountable for the spec's accuracy; the revision block is the document's memory. Good looks like: every change dated, described in one line, with the author's name.
§2 Problem statement
The problem in the user's terms, with evidence — quotes, metrics, support tickets. No solutions here; a spec that starts with the answer skips the thinking. Good looks like: a reader who knows nothing about the project can explain why this matters.
§3 Goals & non-goals
Goals are the outcomes this work achieves; non-goals are the plausible things it explicitly does not. Non-goals are the cheapest scope control in the industry. Good looks like: at least three non-goals, each naming something someone will inevitably ask for.
§4 Requirements
Functional and non-functional requirements, numbered (FR-1, NFR-1) so plans and tasks can reference them. Each requirement is one testable statement. Good looks like: no requirement contains the word "should" without a number attached to it.
§5 Acceptance criteria
The contract. Every criterion is verifiable true-or-false, ideally executable as a test. This is the section the review gate checks at the end. Good looks like: a stranger could run the criteria and pronounce the work done or not done.
§6 Implementation plan
Architecture, components, data flows, sequencing, dependencies, risks. Derived from the spec — every requirement must have a planned home. Good looks like: a reviewer can trace each requirement to a plan element.
§7 Task breakdown
Small, ordered, independently verifiable tasks, each referencing its requirement numbers. Ordered by risk: the most uncertain work first. Good looks like: no task takes more than half a day; each has its own done-condition.
§8 Open questions
What you don't know yet, with an owner and a date for each. Explicit unknowns beat implicit ones every time. Good looks like: no question older than the spec's last review.
Copy it, fill it, build from it
# Feature Spec: [Feature name] | Field | Value | |---------|--------------------| | Owner | [Name] | | Status | Draft / In review / Approved / Building / Done | | Created | [YYYY-MM-DD] | ## Revision block | Rev | Date | Author | Description | |-----|------------|--------|------------------------| | 0.1 | [YYYY-MM-DD] | [Name] | Initial draft | ## 1. Problem statement [Describe the problem in the user's terms. Include evidence: quotes, metrics, tickets, data. No solutions in this section.] ## 2. Goals and non-goals ### Goals - [G-1] [Outcome this work achieves] - [G-2] [Outcome this work achieves] ### Non-goals - [NG-1] [Plausible request explicitly excluded] - [NG-2] [Plausible request explicitly excluded] ## 3. Requirements ### Functional - [FR-1] [One testable statement] - [FR-2] [One testable statement] ### Non-functional - [NFR-1] [Performance, security, accessibility, reliability...] - [NFR-2] [One testable statement] ## 4. User stories (optional) - As a [role], I want [capability] so that [benefit]. Acceptance: [how we verify this story] ## 5. Acceptance criteria - [ ] [AC-1] [Verifiable, true-or-false statement covering FR-1] - [ ] [AC-2] [Verifiable, true-or-false statement covering FR-2] - [ ] [AC-3] [Edge case or error-state criterion] - [ ] [AC-4] [Non-functional criterion with a number in it] ## 6. Implementation plan ### 6.1 Architecture [Components, how they fit together, key design decisions.] ### 6.2 Data flow [How data moves through the feature, end to end.] ### 6.3 Sequencing and dependencies 1. [First thing, and what it unblocks] 2. [Second thing, and what it depends on] ### 6.4 Risks and mitigations | Risk | Likelihood | Impact | Mitigation | |------|-----------|--------|------------| | [Risk] | [H/M/L] | [H/M/L] | [Mitigation] | ## 7. Task breakdown | # | Task | Reqs | Done when | Size | |---|------|------|-----------|------| | T-1 | [Smallest verifiable unit] | FR-1 | [Its done-condition] | [S/M] | | T-2 | [Smallest verifiable unit] | FR-2 | [Its done-condition] | [S/M] | _Order tasks riskiest-first. No task larger than half a day._ ## 8. Open questions - [ ] [Q-1] [Question] — Owner: [name], due [date] - [ ] [Q-2] [Question] — Owner: [name], due [date] ## 9. Rollout and verification - [Rollout steps: flags, migration, comms] - [How the review gate will verify each acceptance criterion]
| Rev | Date | Description |
|---|---|---|
| 1.0 | 2026-09-20 | Initial publication. |