Turn the spec into tasks
What it produces
specs/NNN-slug/plan.md, beside the spec it implements.
Steps
- Read the spec, and only the specs it names — the one it supersedes, the ones it depends
on. Nothing else. A hundred specs cost the index plus the ones you were told about.
- Write tasks small enough that each one is a commit, each one numbered and each one
opening with an empty box:
1. [ ] **Title** —. For every task, four things:
file (the one it touches), check (the command that fails today and passes
after), rollback (how to undo it), done when (in one sentence, testable).
Never write [x]. The box is filled by ai-eng spec show <id> --task <n> --tick,
which runs the check and seals what it measured; an empty box means no command has
run over these bytes yet, which is not the same as "not done".
- A check is a command, never a judgement. "Looks right" is not a check. If a task's
check reads "the agent decides X", say in one line why a script cannot do it — and if
you cannot say why, write the script instead. That is rule 12, and it applies here
first because here is where the cost is decided.
- If the spec adds anything that gets a URL, two tasks are mandatory and named:
- a CI/CD task: build, lint, test and security analysis on every push, deploy from
the default branch, zero manual steps;
- an observability task covering the eight signals the spec lists, each passing with
a command.
Without them the plan is not finished, whatever else is in it.
- Order the tasks so that the first failing check appears as early as possible. A plan
whose first six tasks cannot fail is a plan that finds out too late.
- Say what you are not doing, and why. The deliberate omissions are the part reviewers
most often need and least often get.
Done when
- Every task has a file, a check, a rollback and a "done when".
- The deployable tasks exist if the spec is deployable, and are absent if it is not.
- The person has approved it, recorded as an ADR at the spec and plan digests. That record is the gate: no code before it.
- The reviewer got
ai-eng report view --spec <NNN>'s file:// link beside the Markdown;
the ADR at the two digests stays the gate, and the page is how it is read.
What this is not
Not an estimate, not a schedule, and not a place to redesign. If planning uncovers that
the spec is wrong, stop and go back to /ai-spec. Re-planning around a wrong spec is the
most expensive mistake available here.
- "A check that reads 'the agent decides X' is honest for this task" — a check is a command, never a judgement: if you cannot say why a script cannot decide it, write the script instead.
1---2name: ai-plan3description: Turns an approved spec into a numbered task list where every task names one file, one check that fails, and how to undo it. When the spec adds anything deployable, the plan must carry a CI/CD task and an observability task; they are not optional. Trigger for "break this down", "what tasks do we need", "let's start implementing", "the scope changed, re-plan". Not for exploring the problem — use /ai-spec. Not for writing the code — say go once this is approved. Not for judging what was built — use /ai-review.4license: Apache-2.05---67# Turn the spec into tasks89## What it produces1011`specs/NNN-slug/plan.md`, beside the spec it implements.1213## Steps14151. Read the spec, and only the specs it names — the one it supersedes, the ones it depends16 on. Nothing else. A hundred specs cost the index plus the ones you were told about.172. Write tasks small enough that each one is a commit, each one numbered and each one18 opening with an empty box: `1. [ ] **Title** —`. For every task, four things:19 **file** (the one it touches), **check** (the command that fails today and passes20 after), **rollback** (how to undo it), **done when** (in one sentence, testable).21 Never write `[x]`. The box is filled by `ai-eng spec show <id> --task <n> --tick`,22 which runs the check and seals what it measured; an empty box means no command has23 run over these bytes yet, which is not the same as "not done".243. A check is a command, never a judgement. "Looks right" is not a check. If a task's25 check reads "the agent decides X", say in one line why a script cannot do it — and if26 you cannot say why, write the script instead. That is rule 12, and it applies here27 first because here is where the cost is decided.284. If the spec adds anything that gets a URL, two tasks are mandatory and named:29 - a **CI/CD** task: build, lint, test and security analysis on every push, deploy from30 the default branch, zero manual steps;31 - an **observability** task covering the eight signals the spec lists, each passing with32 a command.33 Without them the plan is not finished, whatever else is in it.345. Order the tasks so that the first failing check appears as early as possible. A plan35 whose first six tasks cannot fail is a plan that finds out too late.366. Say what you are not doing, and why. The deliberate omissions are the part reviewers37 most often need and least often get.3839## Done when4041- Every task has a file, a check, a rollback and a "done when".42- The deployable tasks exist if the spec is deployable, and are absent if it is not.43- The person has approved it, recorded as an ADR at the spec and plan digests. That record is the gate: no code before it.44- The reviewer got `ai-eng report view --spec <NNN>`'s `file://` link beside the Markdown;45 the ADR at the two digests stays the gate, and the page is how it is read.4647## What this is not4849Not an estimate, not a schedule, and not a place to redesign. If planning uncovers that50the spec is wrong, stop and go back to `/ai-spec`. Re-planning around a wrong spec is the51most expensive mistake available here.5253- "A check that reads 'the agent decides X' is honest for this task" — a check is a command, never a judgement: if you cannot say why a script cannot decide it, write the script instead.
arcasilesgroup