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: >-4 Turns an approved spec into a numbered task list where every task names one file, one5 check that fails, and how to undo it. When the spec adds anything deployable, the plan6 must carry a CI/CD task and an observability task; they are not optional. Trigger for7 "break this down", "what tasks do we need", "let's start implementing", "the scope8 changed, re-plan". Not for exploring the problem — use /ai-spec. Not for writing the9 code — say go once this is approved. Not for judging what was built — use /ai-review.10license: Apache-2.011compatibility: needs git; an approved spec under specs/12disable-model-invocation: true13metadata:14 source: https://skillmd.com/skills/arcasilesgroup/ai-plan15---1617# Turn the spec into tasks1819## What it produces2021`specs/NNN-slug/plan.md`, beside the spec it implements.2223## Steps24251. Read the spec, and only the specs it names — the one it supersedes, the ones it depends26 on. Nothing else. A hundred specs cost the index plus the ones you were told about.272. Write tasks small enough that each one is a commit, each one numbered and each one28 opening with an empty box: `1. [ ] **Title** —`. For every task, four things:29 **file** (the one it touches), **check** (the command that fails today and passes30 after), **rollback** (how to undo it), **done when** (in one sentence, testable).31 Never write `[x]`. The box is filled by `ai-eng spec show <id> --task <n> --tick`,32 which runs the check and seals what it measured; an empty box means no command has33 run over these bytes yet, which is not the same as "not done".343. A check is a command, never a judgement. "Looks right" is not a check. If a task's35 check reads "the agent decides X", say in one line why a script cannot do it — and if36 you cannot say why, write the script instead. That is rule 12, and it applies here37 first because here is where the cost is decided.384. If the spec adds anything that gets a URL, two tasks are mandatory and named:39 - a **CI/CD** task: build, lint, test and security analysis on every push, deploy from40 the default branch, zero manual steps;41 - an **observability** task covering the eight signals the spec lists, each passing with42 a command.43 Without them the plan is not finished, whatever else is in it.445. Order the tasks so that the first failing check appears as early as possible. A plan45 whose first six tasks cannot fail is a plan that finds out too late.466. Say what you are not doing, and why. The deliberate omissions are the part reviewers47 most often need and least often get.4849## Done when5051- Every task has a file, a check, a rollback and a "done when".52- The deployable tasks exist if the spec is deployable, and are absent if it is not.53- The person has approved it, recorded as an ADR at the spec and plan digests. That record is the gate: no code before it.54- The reviewer got `ai-eng report view --spec <NNN>`'s `file://` link beside the Markdown;55 the ADR at the two digests stays the gate, and the page is how it is read.5657## What this is not5859Not an estimate, not a schedule, and not a place to redesign. If planning uncovers that60the spec is wrong, stop and go back to `/ai-spec`. Re-planning around a wrong spec is the61most expensive mistake available here.6263- "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.