f5ed5657bd
Adds a docs page for every promoted skill that lacked one, following .agents/writing-docs.md and using docs/engineering/to-prd.md as the worked exemplar. Covers all of engineering/ (bar to-prd, already done), productivity/, and misc/. Each page states its load-bearing constraint, its invocation mode and trigger boundary, surfaces the skill's leading word, and routes back to ask-matt so the set forms a connected router with no dead ends. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3.3 KiB
Quickstart:
npx skills add mattpocock/skills --skill=tdd
npx skills update tdd
What it does
tdd builds a feature or fixes a bug test-first, one behaviour at a time, driving the code out through a red-green loop.
The load-bearing constraint: it will not write all the tests up front. Batching the tests first ("horizontal slicing") produces tests of imagined behaviour — they check the shape of things and go numb to real changes. tdd instead takes vertical slices: one test, then just enough code to pass it, then the next test, each cycle informed by what the last one taught you. Tests target public interfaces only, so the implementation underneath can change without the tests moving.
When to reach for it
Type /tdd, or the agent reaches for it automatically when a task fits — building a feature or fixing a bug test-first, or when you say "red-green-refactor".
Reach for it when there's a concrete behaviour to build and you want tests that survive a refactor. If the behaviour isn't pinned down yet, settle the spec first — for that, use to-prd. When the work is really about the shape of the interface rather than the tests, use codebase-design; tdd calls into it for the deep-module vocabulary during planning.
Red-green, one slice at a time
The leading idea is the red-green loop: write one failing test (red), add just enough code to pass it (green), then repeat for the next behaviour — each cycle informed by what the last one taught you. The very first cycle is a tracer bullet: one test that proves a single path works end-to-end, before you build outward from it. Because you just wrote the code, you know exactly which behaviour matters and how to verify it — you never outrun your headlights by committing to test structure you don't yet understand.
Two rules keep the tests honest. A good test reads like a specification ("user can checkout with valid cart") and exercises real code paths through the public API, so renaming an internal function never breaks it. And expected values come from an independent source of truth — a known-good literal, a worked example, the spec — never recomputed the way the code computes them, which is how a tautological test passes by construction and tells you nothing.
Refactoring only happens once the suite is green; never while red.
It's working if
- It writes one test, gets it passing, and only then writes the next — not a batch of tests followed by a batch of code.
- The tests name behaviours, not internals, and would survive an internal rename.
- Expected values are literals from the spec, not figures derived the same way the code derives them.
Where it fits
tdd is the final step of the main build chain:
grill-with-docs → to-prd → to-issues → tdd
It implements the tickets the earlier steps produced. Its key neighbours are to-issues, which hands it an independently-grabbable issue to build, and codebase-design, which it leans on to find deep-module seams worth testing at. When you're unsure which skill or flow fits, ask-matt routes you.