planning

Files (2)

• SKILL.md
• illustrations.md · references/

SKILL.md (first lines)

# 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](#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](#revising-a-plan)); never rename or delete a plan.

## Required sections

1. **Summary** — the goal, the review standard, and the main risk.
2. **Scope** — allowed and forbidden paths, non-goals, entrypoints, analogous
   paths that must behave the same way, and the supported use and access.
3. **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).
4. **Tests and verification** — see below.
5. **Implementation steps** — an ordered outline, not code.
6. **Forbidden patterns** — shortcuts the implementer must not take, such as
   stubs, shims, catch-and-warn, or a second source of truth.
7. **Complexity budget** — see below.
8. **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`](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.

```text
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

From tobywise/agent-skills, MIT.

More from tobywise/agent-skills