Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Also use when a session-start warning indicated no spec was found for the current branch, when working on AI-generated code that needs a comprehension anchor, or any time you hear "write a spec", "spec this out", "define requirements", "what are we building", or "let's plan this first". Do not skip this skill because the task seems simple — even a two-line spec is better than none, and the spec-as-eval step it adds is what connects Layer 1 (specification) to Layer 3 (comprehension gate).
Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Also use when a session-start warning indicated no spec was found for the current branch, when working on AI-generated code that needs a comprehension anchor, or any time you hear "write a spec", "spec this out", "define requirements", "what are we building", or "let's plan this first". Do not skip this skill because the task seems simple — even a two-line spec is better than none, and the spec-as-eval step it adds is what connects Layer 1 (specification) to Layer 3 (comprehension gate).
Spec-Driven Development
Overview
Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.
In the dark code context, the spec serves a second function: it becomes the eval harness. Acceptance criteria written before implementation can be directly tested against the AI's output. This is the difference between "the tests pass" and "the implementation satisfies the stated intent."
When to Use
Starting a new project or feature
Requirements are ambiguous or incomplete
The change touches multiple files or modules
You're about to make an architectural decision
The task would take more than 30 minutes to implement
A session-start warning surfaced that no spec exists for the current branch
When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.
The Gated Workflow
Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.
SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT ──→ GATE
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
Human Human Human Human Human
reviews reviews reviews reviews reviews
artifact
Phase 1: Specify
Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.
Surface assumptions immediately. Before writing any spec content, list what you're assuming:
ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.
Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.
Write a spec document covering these six core areas:
Objective — What are we building and why? Who is the user? What does success look like?
Commands — Full executable commands with flags, not just tool names.
Build: npm run build
Test: npm test -- --coverage
Lint: npm run lint --fix
Dev: npm run dev
Project Structure — Where source code lives, where tests go, where docs belong.
Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.
Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.
Boundaries — Three-tier system:
Always do: Run tests before commits, follow naming conventions, validate inputs
Ask first: Database schema changes, adding dependencies, changing CI config
Never do: Commit secrets, edit vendor directories, remove failing tests without approval
Spec template:
# Spec: [Project/Feature Name]## Objective
[What we're building and why. User stories or acceptance criteria.]
## Tech Stack
[Framework, language, key dependencies with versions]
## Commands
[Build, test, lint, dev — full commands]
## Project Structure
[Directory layout with descriptions]
## Code Style
[Example snippet + key conventions]
## Testing Strategy
[Framework, test locations, coverage requirements, test levels]
## Boundaries- Always: [...]
- Ask first: [...]
- Never: [...]
## Success Criteria
[How we'll know this is done — specific, testable conditions]
## Eval Assertions
[Testable restatements of each success criterion — see below]
## Open Questions
[Anything unresolved that needs human input]
Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions:
REQUIREMENT: "Make the dashboard faster"
REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?
Write eval assertions for every success criterion.
After success criteria are agreed, rewrite each one as a testable assertion the implementing AI can verify before opening a PR. This is the spec-as-eval step — it converts the spec from a description of intent into a harness the AI actively tests against.
Format:
Success criterion: "The billing endpoint correctly handles failed payments"
Eval assertion: "When Stripe returns a 402, the endpoint:
(a) returns HTTP 402 with body { error: 'payment_failed' }
(b) does NOT create a billing_transactions database row
(c) does NOT emit a billing_charged event
(d) logs the failure with the Stripe error code and customer_id"
Each assertion must be:
Specific — names the exact input, output, and side effects
Falsifiable — could fail if the implementation is wrong
Complete — covers both the happy path and the side effects that must NOT happen
The eval assertions are written into the spec's ## Eval Assertions section. During implementation (Phase 4), the AI tests against each assertion before considering a task complete. The comprehension gate (Phase 5) checks whether the implementation was verified against named assertions.
Phase 2: Plan
With the validated spec, generate a technical implementation plan:
Identify the major components and their dependencies
Determine the implementation order (what must be built first)
Note risks and mitigation strategies
Identify what can be built in parallel vs. what must be sequential
Define verification checkpoints between phases
The plan should be reviewable: the human should be able to read it and say "yes, that's the right approach" or "no, change X."
Phase 3: Tasks
Break the plan into discrete, implementable tasks:
Each task should be completable in a single focused session
Each task has explicit acceptance criteria
Each task includes a verification step (test, build, manual check)
Tasks are ordered by dependency, not by perceived importance
No task should require changing more than ~5 files
Task template:
- [ ] Task: [Description]
- Acceptance: [What must be true when done]
- Verify: [How to confirm — test command, build, manual check]
- Eval assertions: [Which spec eval assertions this task satisfies]
- Files: [Which files will be touched]
Note the Eval assertions field — each task should map back to specific assertions from the spec. A task without a mapped assertion is either untestable or out of scope.
Phase 4: Implement
Execute tasks one at a time following incremental-implementation and test-driven-development skills. Use context-engineering to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.
During implementation: before marking any task complete, verify it against its mapped eval assertions. If an assertion fails or cannot be verified, the task is not done.
Phase 5: Comprehension Gate (closing step)
Before marking the spec complete, run /comprehension-gate on the implementation.
The comprehension gate is the evidence that the change was understood at the system level, not just functionally correct. A spec can be satisfied — all assertions pass — and the implementation can still have a blast radius that extends across three services.
The spec is not complete until:
/comprehension-gate has been run
COMPREHENSION_ARTIFACT.md verdict is CLEAR or REVIEW REQUIRED with all questions answered
The artifact is committed alongside the implementation
This closes the loop: Layer 1 (spec defined what to build) → Layer 3 (gate verified the implementation was understood).
Keeping the Spec Alive
The spec is a living document, not a one-time artifact:
Update when decisions change — If you discover the data model needs to change, update the spec first, then implement.
Update when scope changes — Features added or cut should be reflected in the spec.
Commit the spec — The spec belongs in version control alongside the code.
Reference the spec in PRs — Link back to the spec section that each PR implements.
Update eval assertions when behavior changes — If an assertion becomes invalid during implementation, update it in the spec and document why.
Common Rationalizations
Rationalization
Reality
"This is simple, I don't need a spec"
Simple tasks don't need long specs, but they still need acceptance criteria. A two-line spec is fine.
"I'll write the spec after I code it"
That's documentation, not specification. The spec's value is in forcing clarity before code.
"The spec will slow us down"
A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours.
"Requirements will change anyway"
That's why the spec is a living document. An outdated spec is still better than no spec.
"The user knows what they want"
Even clear requests have implicit assumptions. The spec surfaces those assumptions.
"The AI code passes tests, so it must be correct"
Tests verify that the code does what the author thought it should do. They do not verify that the author understood what the code would do to the surrounding system. A change can pass every test and still have a blast radius spanning three services. Tests are necessary; they are not sufficient. Run the comprehension gate.
Red Flags
Starting to write code without any written requirements
Asking "should I just start building?" before clarifying what "done" means
Implementing features not mentioned in any spec or task list
Making architectural decisions without documenting them
Skipping the spec because "it's obvious what to build"
Accepting AI-generated code because the tests pass, without running /comprehension-gate
Verification
Before proceeding to implementation, confirm:
The spec covers all six core areas
The human has reviewed and approved the spec
Success criteria are specific and testable
Eval assertions are written for every success criterion
Boundaries (Always/Ask First/Never) are defined
The spec is saved to a file in the repository
Before closing the spec as complete:
All eval assertions were verified during implementation
/comprehension-gate has been run on the implementation
COMPREHENSION_ARTIFACT.md verdict is CLEAR or REVIEW REQUIRED (questions answered)
Comprehension artifact is committed to the repository
