Spec driven development

📐 Skill: spec-driven-development

Purpose

Prevent wasted implementation work by making the shared understanding explicit before any code is written. A spec surfaces assumptions, resolves ambiguity, and gives both the developer and the agent a stable reference point throughout the work. Retrofitting clarity after implementation costs 5–10× more than establishing it upfront.

Trigger phrases

• "write a spec for this"
• "spec this out"
• "spec-driven"
• "define this before we build"
• "what should I build"
• "I need a spec"

When to use

Use spec-driven	Skip (proceed directly)
New feature or module	Single-line typo fix
Ambiguous or verbal requirements	Self-evident single-file change
Change touches more than one file	Direct user instruction with no ambiguity
Estimated work > 30 minutes	Reversible experiment / spike
Multiple engineers will be involved

---

Steps

1. Surface assumptions before writing anything

Before drafting the spec, explicitly list what you are assuming:

Assumptions I'm making:
- [ ] The user wants X, not Y
- [ ] This will use the existing auth system
- [ ] No DB schema changes are needed

Ask the user to confirm or correct before continuing.

2. Write the spec

A complete spec has six sections:

## Objective
What this change achieves. State it as a testable success criterion:
"A user can reset their password via email. The flow completes in under 3 steps."

## Commands
Build, test, and run commands for this project:
- Install: `npm install`
- Dev: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`

## Scope
Files and modules this change will touch.
Files and modules this change must NOT touch.

## Design
How it will be built — data flow, key functions, API shape, schema changes.
Keep it concrete: name the functions, files, and interfaces.

## Testing strategy
- Unit tests: what and where
- Integration tests: which flows
- Manual verification steps

## Boundaries
| Always do | Ask first | Never do |
|-----------|-----------|----------|
| ... | ... | ... |

3. Gate: human review before implementation

Present the spec and stop. Do not start coding until the user explicitly approves it or requests changes.

If the spec reveals the requirements are unclear, surface that as an open question — do not resolve ambiguity silently.

4. Implement against the spec

• Reference the spec as you work. If the implementation diverges from the spec, flag it and update the spec first.
• Keep the spec as a living document — update it when scope changes, not after.

5. Reference the spec in your PR

In the PR description, link or quote the relevant spec sections. Reviewers should be able to map every diff line back to a spec requirement.

---

Output

A markdown spec block covering all six sections above, ready to be saved as docs/specs/<feature-name>.md or pasted into a GitHub issue.

Guardrails

• Never start implementation without spec approval when the scope qualifies.
• Never resolve ambiguous requirements by guessing — surface them as questions.
• Never let the spec become out of date — update it before changing course, not after.
• A spec is not a design document for its own sake. If it can't be implemented, it's not done.