SPEC WRITINGTEMPLATE

Milestone Build Prompt

The implementer gets the task, not the whole conversation. That sounds like a handicap and it is the reverse. A fresh context has no accumulated confusion to inherit: no half-abandoned approach from two hours ago, no correction it is still quietly routing around, no summary of a summary of what you decided this morning. It reads the standing rules, reads one section of the spec, does the one thing, and stops.

This is the prompt you paste at the top of that session, filled in from one row of your milestone plan. It is boring on purpose. The parts that look like bureaucracy, the exact test path and the exact commands and the exact commit message, are the parts doing the work, because each one removes a small decision the agent would otherwise make on your behalf and never mention.

Prerequisites

  • A `SPEC.md` with numbered sections, so this prompt can point at exactly one of them.
  • A `CLAUDE.md` carrying your standing conventions and verification gates, so they do not have to be repeated here.
  • A milestone plan, so the task has a known place in a known sequence.
markdown
# Task: [one sentence, imperative. "Add X to Y so that Z."]

## Read first

1. `CLAUDE.md`. Standing conventions apply to this task without being
   repeated below.
2. `SPEC.md` §[N], [section title]. That section is the source of truth for
   this task. If anything below contradicts it, the spec is right.
3. [any other file the task genuinely needs, e.g. `src/[module]/types.ts`]

Do not read the rest of the repo unless the task requires it. Do not
summarize what you read back to me.

## Where this sits

- Milestone: [Mn, from the milestone plan]
- Task [n] of [m] in that milestone
- Already built and working: [one line, so you do not rebuild it]
- Deliberately not built yet, and not part of this task: [one line, so you
  do not build it early]

## The task

[One sentence. If it takes two sentences, it is two tasks, and you should
close this file and split it.]

## Write the failing test first

- File: `[exact path, e.g. src/compiler/__tests__/period.test.ts]`
- It asserts: [the specific behavior, with the specific numbers from
  `SPEC.md` §[N]. Not "it works". "compile() returns period 253 for A4 at
  the NES timer rate".]
- Run the test and show me it failing, with the real output, before you
  write any implementation. A test that passes before the code exists is
  testing nothing.

## Then write the code

Files you may create or modify:

- `[exact path]`
- `[exact path]`

Anything not on that list is out of scope for this task.

## Do not

- Do not touch `[paths that are off limits, e.g. generated/, vendor/, the
  worklet]`.
- Do not add a dependency. If you think the task needs one, stop and ask.
- Do not reformat, rename, or refactor files you were not asked to change.
- Do not "improve" something adjacent while you are in there. Write it down
  and I will decide.

## Green gate

Run these, in this order, and paste the actual output:

```bash
[test command]
[build command]
```

Both must pass. "Should pass" is not passing, and neither is "passes
locally" without the output.

## Commit

One commit, this message exactly:

```
[type(scope): short imperative summary]
```

## If the spec and this task disagree, stop and say so

Do not reconcile them yourself and do not pick the one that is easier to
build. Quote both, say which you think is correct and why, and wait.

Adaptation notes:

  • A fresh context is worth it when the task is well defined and the current session is long, muddled, or carrying a failed approach. Continue the existing session when you are mid-debug and the accumulated evidence is the valuable part. The tell is whether you would have to explain the last hour to a newcomer or could just hand over the brief.
  • If you cannot write the task in one sentence, it is too big. This is the same rule as milestone sizing, one level down, and it fails the same way when you ignore it: the diff arrives too large to review and you approve it out of fatigue.
  • The exact test path matters more than it looks. Naming the file removes a choice, and a named file is one you can open and read yourself in ten seconds without hunting for where the agent decided tests live this week.
  • Keep the "Do not" list short and real. A list of twenty prohibitions gets skimmed. Three that each prevented a specific past disaster get followed.
  • Paste the commit message rather than describing it. Commit messages an agent invents are the ones that say "update files".

Contribute an improvement →