| name | tdd-plan |
| description | Use at the START of any new feature, product, bugfix, or change, before writing code, to decompose it into thin vertical slices (each the smallest end-to-end testable behaviour that delivers value) and write a markdown execution plan per slice into the plans/ folder. Phase 1 of the TDD harness. Trigger on 'slice this up', 'what is the smallest first step', 'plan this test-first', 'write a TDD plan', or any request to build something where the slices should be identified first. Each plan becomes the contract the red-green-refactor skill then executes. |
TDD Plan — Slice & Plan (Phase 1)
Turn a request into a set of thin vertical slices, each captured as a markdown execution plan in plans/. A good slice is the smallest change in system behaviour that is independently valuable and testable end-to-end. The plan you write here is the contract the red-green-refactor skill executes next, and that tdd-ci and safe-pr later read — so make it precise.
Slicing is the hardest and most valuable judgement in TDD. "Sequencing the tests properly is a skill — pick tests that drive you quickly to the salient points in the design." Take your time here.
For the full slicing toolkit — vertical-vs-horizontal, INVEST, the walking skeleton, and nine concrete splitting patterns with a worked example — read references/slicing-guide.md.
Procedure
-
Understand the request. Restate the feature/outcome in one or two sentences. Ask only the questions that change the slicing: who the user is, the externally observable behaviour, the boundary it goes through (web UI, HTTP API, CLI), and any hard constraints. Don't over-interrogate.
-
Detect the context. Is this a brand-new system or a change to an existing one? Look at the repo (build tooling, existing tests, frameworks). If there is no working build/test/deploy path yet, the first slice must be a walking skeleton: the thinnest end-to-end thread that builds, runs, and is tested through real infrastructure — it de-risks architecture and CI before any real feature content.
Also note where the app lives relative to the repo root — the project directory. It is . for a single app at the root, or a subfolder for a monorepo package / services/<x> / a sandbox/ smoke-test. Record it in every plan (see the template field): the later phases run install/test/build there and CI keys working-directory + cache-dependency-path off it. The git branch is always cut at the repo root regardless.
-
Slice vertically. Decompose into an ordered list of slices, each cutting through all the layers it needs (UI → logic → persistence) to deliver one observable behaviour. Never slice horizontally (a "build the DB layer" slice has no independent value and can't be tested end-to-end — reject it). Use the splitting patterns in the guide. Order slices so the earliest ones de-risk the most and each builds on the last.
-
Validate every slice against INVEST — Independent, Negotiable, Valuable, Estimable, Small, Testable. If a slice isn't Small and Testable, split it again. If it has no discernible value, drop it. Aim for slices a developer could finish in well under a day.
-
Write the plans. Create plans/<feature-slug>/:
- A
README.md index/status board from the Feature index template in assets/plan-template.md, listing all slices in order with status.
- One
<NN>-<slice-slug>.md execution plan per slice from the Slice plan template in the same file. <NN> is the zero-padded order (01, 02, …).
- Fill in every section. The crucial ones: the acceptance criterion written as a Given/When/Then that becomes the slice's failing outer e2e test, and the initial unit test list that seeds the inner loop. These don't have to be exhaustive — the test list is living and
red-green-refactor will add to it — but they must pin down "done".
-
Confirm and hand off. Show the user the slice list (titles + one-line goals + the proposed first slice). Get sign-off before any code is written. Then tell them the next step: run red-green-refactor on slice 01. If they're using the tdd-harness orchestrator, return control to it.
What makes a plan good
- One behaviour per slice. If you can't state the slice's value in a single sentence, it's too big.
- The acceptance criterion is concrete and observable from outside the system — it names the real endpoint (a URL, a CLI invocation, an API call), not an internal function.
- Out-of-scope is explicit. Listing what a slice deliberately defers is how you keep it thin and stop gold-plating.
- The plan is executable by someone else. The
red-green-refactor skill should be able to start solely from the plan file.
Output
Plans only. Do not write production or test code in this phase — that is red-green-refactor's job. The deliverable is plans/<feature-slug>/ populated with a README index and one plan per slice, plus a short summary to the user of the slices and the recommended first one.
