Planning
A plan is one Markdown file that tells an implementer what to build and tells a
reviewer how to judge it. The main session owns the plan and coordinates the
work: it hands the plan to an implementer, has the result reviewed, and runs
the plan's verification commands itself. Write every plan for that division of
labour.
Before writing
- Inspect the repository first. Ask one short question only for intent the
code and conversation cannot answer.
- Choose the review standard. Use
SCIENTIFIC_ANALYSIS when the project's
agent instructions (AGENTS.md or CLAUDE.md) declare it or the user
selected a scientific workflow; ask when the work looks scientific but
carries no marker. Otherwise use GENERAL. For SCIENTIFIC_ANALYSIS, load
scientific-analysis and apply it throughout.
- Decide whether the work is one plan. Split it (see
Several plans) when it combines a scientific or domain
algorithm with dispatch, aggregation, provenance, receipt, or scheduler
machinery, unless the user explicitly approves one integrated plan.
Write one new lowercase-kebab-case Markdown file, normally one to three pages.
To change an existing plan, revise that file in place (see
Revising a plan); never rename or delete a plan.
Required sections
- Summary — the goal, the review standard, and the main risk.
- Scope — allowed and forbidden paths, non-goals, entrypoints, analogous
paths that must behave the same way, and the supported use and access.
- Contracts — a table with one row per contract, numbered
C-01,
C-02, … Columns: ID, Requirement (the required behaviour, stated
precisely), Positive check (the proof that establishes it), and
Negative check (the check that catches a plausible mistake that could
otherwise pass unnoticed, or — when there is none).
- Tests and verification — see below.
- Implementation steps — an ordered outline, not code.
- Forbidden patterns — shortcuts the implementer must not take, such as
stubs, shims, catch-and-warn, or a second source of truth.
- Complexity budget — see below.
- Acceptance checklist — a table with one row per item, numbered
AC-01, AC-02, … Columns: ID, Behaviour (naming the contracts it
proves, such as (C-01)), Paths, Proof, and Rules out (the shortcuts
it rules out). The implementer works through this list and the reviewer
checks it item by item, so every item must be independently checkable.
Keep each table cell to one or two sentences. When a contract or item needs
more, add a short paragraph under the table that starts with its ID.
Add illustrations where a picture explains the plan faster than prose: a
before-and-after diff, a call diagram, a data-flow graph, or a sketch of a
threshold or expected result. Read
references/illustrations.md before adding
one. Illustrations explain; the contracts decide. An illustration that
disagrees with a contract is a plan defect.
Tests and verification
The implementer writes the tests and may run IMPLEMENTATION_CHECKS at most
twice while implementing. The main session runs these commands after review,
following the run-checks skill.
RUNNER: <how commands run, per run-checks: e.g. `uv run` locally, or cbrun-uv on Crabbox>
REQUIRED_INPUTS: <data, credentials, or services the checks need, or none>
DEFERRED_INPUTS: <inputs deliberately left out of these checks, or none>
IMPLEMENTATION_CHECKS: <one exact command for the targeted selection: the tests covering the change, cheapest first>
FINAL_SUITE: <one exact command for the full suite>
RUN_BUDGET: <expected number of check invocations, with a one-line justification>
- Every command is exact and complete. Its coverage must be reviewable from the
plan alone, never left for whoever runs it to choose.
IMPLEMENTATION_CHECKS covers every acceptance item plus relevant
regressions, in one invocation, cheapest first. It names its tests by file,
test ID, or marker; when it runs the full suite instead, the plan states
which run-checks reason applies.
RUN_BUDGET counts the implementer's runs as well as the main session's.
FINAL_SUITE runs once the candidate is stable after review, for any change
to executable behaviour. Declare FINAL_SUITE: REUSE_IMPLEMENTATION_CHECK
only when IMPLEMENTATION_CHECKS itself runs the full suite.
- Static checks and source inspection cannot prove executable behaviour.
- Name the project's locked linter and formatter where they apply.
- Older plans may say
REMOTE_BUDGET and Remote validation; they mean
RUN_BUDGET and Validation.
Complexity budget
State expected sizes. The defaults are about 800 production additions, 1,200
test additions, 10 changed files, three feature surfaces, one validation path
per configuration path, and one authority per concept. Scientific SINGLE_USE
plans use the smaller figures in scientific-analysis.
These are estimates that invite scrutiny, not hard limits. Exceeding one is not
a defect on its own; only a limit the user or an external authority declares
hard is exact.
Precision rules
- A claim of "all", "every", or "complete" needs an inventory of what it
covers.
- New configuration maps each field to its consumer, or to an explicit
rejection.
- A change to a durable format inventories its producers, consumers,
constructors, fixtures, and existing stored shapes, and says how old data is
migrated or rejected.
- Name the independent source of truth for each check, the fields compared,
the differences allowed, and how failure is observed.
- Keep workflow mechanics out of the plan: no preflight steps, retry counts,
checkpoint timing, or receipt formats.
Scientific plans
Under SCIENTIFIC_ANALYSIS, also:
- declare
Delivery profile and Validation as defined in
scientific-analysis;
- tier every acceptance item
IMPLEMENTATION, INTERPRETATION, or
DEFERRED in a Tier column. Vague adequacy goals are INTERPRETATION
and stay out of failing checks. Never invent adequacy thresholds;
- mark every defensive contract
DIRECT (it protects correctness, fail-fast,
or scientific validity) or CONTINGENT (it guards against something that
might happen) in a Kind column. DIRECT requirements are always full
contracts. For SINGLE_USE, a CONTINGENT concern that is not both
plausibly reachable in supported use and serious goes in an advisory
section, not a contract;
- never weaken the scientific fail-fast policy.
Several plans
When work is too large or mixed for one plan, propose numbered vertical slices,
each independently useful, and get the user's approval before writing any file.
Then write one plan per approved slice, each meeting this whole format, with:
- non-overlapping ownership of paths;
- stated dependencies, and which plan owns any shared file;
- ordered, non-overwriting filenames, e.g.
feature-01-core.md,
feature-02-export.md;
- a coherent, working state after each plan lands.
If inspection shows the approved split no longer holds, stop and say why.
Revising a plan
When the user asks for a revision — usually after a review finds a plan gap —
edit the plan file itself, so there is always one current plan.
- Keep a
Revisions list directly under the title. Add one entry per
revision: its number, what changed, and why, citing the review finding IDs.
- Change only what the revision needs. Keep unaffected contracts, acceptance
IDs, and commands verbatim so earlier reviews stay traceable.
- IDs are permanent. Mark a removed item
Retired in revision N in place,
keep its ID, and give new items the next unused number.
- An operational correction — a command, argument, runner, input, or budget —
can be made as requested. A substantive one — scope, semantics, authority,
design, scientific policy, or a hard limit — needs the user's explicit
approval first.
- Removing a contract also removes proof and machinery needed only for it.
Never remove scientific correctness, validity, fail-fast, or required proof.
- Older plans may have
-v2 or -v3 siblings; the highest suffix is the
current plan. Revise that file in place.
After writing
Show the finished plans to the person as an HTML overview. From the project
root, run this in the background, with every plan path in reading order:
node ~/.agents/skills/plan-review/scripts/plan-overview.mjs <plan.md> [<plan.md> ...]
- It prints a
Local: address and, on a machine running Tailscale, a
Tailnet: address that the person's other devices can open. Give the person
both.
- Keep it running: give the command the longest background time limit your
tool allows. The page reloads itself when a plan file changes, so after a
revision, give the address of the overview that already shows that plan if
it is still running.
- Fix every
Warning: it prints; each one names a drawing the page cannot
show.
- If the person cannot open either address, run it again with
--file before
the plan paths, and give them the HTML file it prints.
- The
Tailnet: address opens the plan to the person's tailnet. If your
permissions ask for approval to run it, ask the person; use no other route.
- A subagent hands back its plan paths instead. The session that talks to the
person starts the overview.
Return the plan path, or paths, the overview addresses, and a one-paragraph
summary.
1---2name: planning3description: The shared format and rules for implementation plans. Use when writing, splitting, revising, or interpreting an implementation plan, including when implementing or reviewing work against one.4metadata:5 source: https://skillmd.com/skills/tobywise/planning6---78# Planning910A plan is one Markdown file that tells an implementer what to build and tells a11reviewer how to judge it. The main session owns the plan and coordinates the12work: it hands the plan to an implementer, has the result reviewed, and runs13the plan's verification commands itself. Write every plan for that division of14labour.1516## Before writing1718- Inspect the repository first. Ask one short question only for intent the19 code and conversation cannot answer.20- Choose the review standard. Use `SCIENTIFIC_ANALYSIS` when the project's21 agent instructions (`AGENTS.md` or `CLAUDE.md`) declare it or the user22 selected a scientific workflow; ask when the work looks scientific but23 carries no marker. Otherwise use `GENERAL`. For `SCIENTIFIC_ANALYSIS`, load24 `scientific-analysis` and apply it throughout.25- Decide whether the work is one plan. Split it (see26 [Several plans](#several-plans)) when it combines a scientific or domain27 algorithm with dispatch, aggregation, provenance, receipt, or scheduler28 machinery, unless the user explicitly approves one integrated plan.2930Write one new lowercase-kebab-case Markdown file, normally one to three pages.31To change an existing plan, revise that file in place (see32[Revising a plan](#revising-a-plan)); never rename or delete a plan.3334## Required sections35361. **Summary** — the goal, the review standard, and the main risk.372. **Scope** — allowed and forbidden paths, non-goals, entrypoints, analogous38 paths that must behave the same way, and the supported use and access.393. **Contracts** — a table with one row per contract, numbered `C-01`,40 `C-02`, … Columns: `ID`, `Requirement` (the required behaviour, stated41 precisely), `Positive check` (the proof that establishes it), and42 `Negative check` (the check that catches a plausible mistake that could43 otherwise pass unnoticed, or `—` when there is none).444. **Tests and verification** — see below.455. **Implementation steps** — an ordered outline, not code.466. **Forbidden patterns** — shortcuts the implementer must not take, such as47 stubs, shims, catch-and-warn, or a second source of truth.487. **Complexity budget** — see below.498. **Acceptance checklist** — a table with one row per item, numbered50 `AC-01`, `AC-02`, … Columns: `ID`, `Behaviour` (naming the contracts it51 proves, such as `(C-01)`), `Paths`, `Proof`, and `Rules out` (the shortcuts52 it rules out). The implementer works through this list and the reviewer53 checks it item by item, so every item must be independently checkable.5455Keep each table cell to one or two sentences. When a contract or item needs56more, add a short paragraph under the table that starts with its ID.5758Add illustrations where a picture explains the plan faster than prose: a59before-and-after `diff`, a call diagram, a data-flow graph, or a sketch of a60threshold or expected result. Read61[`references/illustrations.md`](references/illustrations.md) before adding62one. Illustrations explain; the contracts decide. An illustration that63disagrees with a contract is a plan defect.6465## Tests and verification6667The implementer writes the tests and may run `IMPLEMENTATION_CHECKS` at most68twice while implementing. The main session runs these commands after review,69following the `run-checks` skill.7071```text72RUNNER: <how commands run, per run-checks: e.g. `uv run` locally, or cbrun-uv on Crabbox>73REQUIRED_INPUTS: <data, credentials, or services the checks need, or none>74DEFERRED_INPUTS: <inputs deliberately left out of these checks, or none>75IMPLEMENTATION_CHECKS: <one exact command for the targeted selection: the tests covering the change, cheapest first>76FINAL_SUITE: <one exact command for the full suite>77RUN_BUDGET: <expected number of check invocations, with a one-line justification>78```7980- Every command is exact and complete. Its coverage must be reviewable from the81 plan alone, never left for whoever runs it to choose.82- `IMPLEMENTATION_CHECKS` covers every acceptance item plus relevant83 regressions, in one invocation, cheapest first. It names its tests by file,84 test ID, or marker; when it runs the full suite instead, the plan states85 which `run-checks` reason applies.86- `RUN_BUDGET` counts the implementer's runs as well as the main session's.87- `FINAL_SUITE` runs once the candidate is stable after review, for any change88 to executable behaviour. Declare `FINAL_SUITE: REUSE_IMPLEMENTATION_CHECK`89 only when `IMPLEMENTATION_CHECKS` itself runs the full suite.90- Static checks and source inspection cannot prove executable behaviour.91- Name the project's locked linter and formatter where they apply.92- Older plans may say `REMOTE_BUDGET` and `Remote validation`; they mean93 `RUN_BUDGET` and `Validation`.9495## Complexity budget9697State expected sizes. The defaults are about 800 production additions, 1,20098test additions, 10 changed files, three feature surfaces, one validation path99per configuration path, and one authority per concept. Scientific `SINGLE_USE`100plans use the smaller figures in `scientific-analysis`.101102These are estimates that invite scrutiny, not hard limits. Exceeding one is not103a defect on its own; only a limit the user or an external authority declares104hard is exact.105106## Precision rules107108- A claim of "all", "every", or "complete" needs an inventory of what it109 covers.110- New configuration maps each field to its consumer, or to an explicit111 rejection.112- A change to a durable format inventories its producers, consumers,113 constructors, fixtures, and existing stored shapes, and says how old data is114 migrated or rejected.115- Name the independent source of truth for each check, the fields compared,116 the differences allowed, and how failure is observed.117- Keep workflow mechanics out of the plan: no preflight steps, retry counts,118 checkpoint timing, or receipt formats.119120## Scientific plans121122Under `SCIENTIFIC_ANALYSIS`, also:123124- declare `Delivery profile` and `Validation` as defined in125 `scientific-analysis`;126- tier every acceptance item `IMPLEMENTATION`, `INTERPRETATION`, or127 `DEFERRED` in a `Tier` column. Vague adequacy goals are `INTERPRETATION`128 and stay out of failing checks. Never invent adequacy thresholds;129- mark every defensive contract `DIRECT` (it protects correctness, fail-fast,130 or scientific validity) or `CONTINGENT` (it guards against something that131 might happen) in a `Kind` column. `DIRECT` requirements are always full132 contracts. For `SINGLE_USE`, a `CONTINGENT` concern that is not both133 plausibly reachable in supported use and serious goes in an advisory134 section, not a contract;135- never weaken the scientific fail-fast policy.136137## Several plans138139When work is too large or mixed for one plan, propose numbered vertical slices,140each independently useful, and get the user's approval before writing any file.141Then write one plan per approved slice, each meeting this whole format, with:142143- non-overlapping ownership of paths;144- stated dependencies, and which plan owns any shared file;145- ordered, non-overwriting filenames, e.g. `feature-01-core.md`,146 `feature-02-export.md`;147- a coherent, working state after each plan lands.148149If inspection shows the approved split no longer holds, stop and say why.150151## Revising a plan152153When the user asks for a revision — usually after a review finds a plan gap —154edit the plan file itself, so there is always one current plan.155156- Keep a `Revisions` list directly under the title. Add one entry per157 revision: its number, what changed, and why, citing the review finding IDs.158- Change only what the revision needs. Keep unaffected contracts, acceptance159 IDs, and commands verbatim so earlier reviews stay traceable.160- IDs are permanent. Mark a removed item `Retired in revision N` in place,161 keep its ID, and give new items the next unused number.162- An operational correction — a command, argument, runner, input, or budget —163 can be made as requested. A substantive one — scope, semantics, authority,164 design, scientific policy, or a hard limit — needs the user's explicit165 approval first.166- Removing a contract also removes proof and machinery needed only for it.167 Never remove scientific correctness, validity, fail-fast, or required proof.168- Older plans may have `-v2` or `-v3` siblings; the highest suffix is the169 current plan. Revise that file in place.170171## After writing172173Show the finished plans to the person as an HTML overview. From the project174root, run this in the background, with every plan path in reading order:175176```sh177node ~/.agents/skills/plan-review/scripts/plan-overview.mjs <plan.md> [<plan.md> ...]178```179180- It prints a `Local:` address and, on a machine running Tailscale, a181 `Tailnet:` address that the person's other devices can open. Give the person182 both.183- Keep it running: give the command the longest background time limit your184 tool allows. The page reloads itself when a plan file changes, so after a185 revision, give the address of the overview that already shows that plan if186 it is still running.187- Fix every `Warning:` it prints; each one names a drawing the page cannot188 show.189- If the person cannot open either address, run it again with `--file` before190 the plan paths, and give them the HTML file it prints.191- The `Tailnet:` address opens the plan to the person's tailnet. If your192 permissions ask for approval to run it, ask the person; use no other route.193- A subagent hands back its plan paths instead. The session that talks to the194 person starts the overview.195196Return the plan path, or paths, the overview addresses, and a one-paragraph197summary.