Raw view: Spec, Plan, Implement, Verify
No invisible, zero-width, or bidi-control characters detected.
# Spec, Plan, Implement, Verify
Use this for changes too large to do in one pass and too small for a design doc: a new endpoint, a CLI subcommand, a data model change with migration, a cross-cutting refactor. Each phase ends at a gate. Do not pass a gate without the artifact it requires.
<task>
{{TASK}}
</task>
<constraints>
{{CONSTRAINTS}}
</constraints>
Test command: `{{TEST_COMMAND}}`.
## Gate 1: Spec
1. Explore before writing. Read the parts of the codebase the task touches: entry points, existing similar features, tests, config. List the files you read. Do not propose changes to code you have not opened.
2. Write `SPEC.md` with: the goal in one sentence; numbered, testable acceptance criteria (each one a sentence you could turn into a test); explicit non-goals; interfaces that will change (signatures, schemas, endpoints) shown as code; and open questions.
3. Convert every vague requirement in <task> into a concrete criterion and mark it `[assumed]`. Check each criterion against <constraints>.
4. **STOP POINT.** Present `SPEC.md`. Wait for approval. Incorporate edits and re-present if the changes are material. Do not start planning until the spec is approved.
**Artifact:** `SPEC.md`, approved.
## Gate 2: Plan
5. Write `PLAN.md`: an ordered list of steps, each naming the files to create or change, the change in one or two sentences, and the acceptance criterion it serves. Each step should be independently verifiable and leave the codebase working (tests green, or red only for the new test the step adds).
6. Identify the riskiest step (interface change, migration, concurrency) and move it as early as dependencies allow, so failure is cheap.
7. For each step, note how it will be verified: a test to write, a command to run, a manual check.
8. Estimate the total diff size. If it exceeds roughly 400 lines, split the plan into two PRs and say where the seam is.
9. **STOP POINT.** Present `PLAN.md`. Wait for approval. If the plan reveals the spec was wrong, go back to Gate 1 rather than planning around it.
**Artifact:** `PLAN.md`, approved, with a checkbox per step.
## Gate 3: Implement
10. Work the plan in order. For each step: make the change; add or update the test named in the plan; run `{{TEST_COMMAND}}`; check the step off with a one-line note of what was verified.
11. Keep each step's diff reviewable. Commit (or snapshot) per step with a message that names the step.
12. **Check after each step:** suite green; lint and type checks pass; no files changed outside those the step named (if some were needed, add them to the plan with a note).
13. **STOP POINT** if any of these occur: a step requires changing something `SPEC.md` listed as a non-goal; a step's diff is more than double its estimate; a test can only pass by changing an unrelated test; an external dependency must be added. Report and wait.
14. Do not optimize, generalize, or refactor beyond what the plan says. Note ideas in `FOLLOWUPS.md` instead.
**Artifact:** commits per step; `PLAN.md` fully checked; `FOLLOWUPS.md` if any.
## Gate 4: Verify
15. Walk `SPEC.md` criterion by criterion. For each, name the test or command that demonstrates it and run it. Record pass/fail. A criterion with no demonstrable check is not done.
16. Run the full test suite, lint, type checks, and build from a clean state.
17. Review the complete diff once, as a reviewer: every hunk maps to a plan step; no debug output, no commented-out code, no TODOs without an owner.
18. Re-read <constraints> and confirm each is honored.
19. Write `VERIFICATION.md`: the criterion-to-evidence table, the commands run and their results, deviations from the plan and why, and the contents of `FOLLOWUPS.md` as proposed next issues.
20. **STOP POINT.** Present `VERIFICATION.md` and the diff summary. Declare done only when every criterion shows evidence.
**Final artifact:** `VERIFICATION.md`; the branch or PR ready for review.
## Rules throughout
- Approval at a gate covers only that gate's artifact. New information reopens the earlier gate.
- When uncertain between two reasonable interpretations and the difference is small, pick one, record it in the artifact as `[assumed]`, and continue; when the difference is large, stop and ask.
- Keep the artifacts short. A spec a reviewer will not read is not a gate.