Capstone: fix a reported bug, from plan to commit

01The setup

Use a repo with a bug you can state in two sentences. If you followed lesson 3’s link-checker arc, the classic remains: when linkcheck.json lists a folder that does not exist, the tool says every link resolves and exits with code 0. Reproduce it by hand first — make a folder outside the repo, save { "files": ["docs"] } as linkcheck.json in it, run the checker against it — because a bug you have not reproduced is a rumor, and you will need the repro to prove the fix. Or take a small, real, testable one from your own tracker. If you want the upstream practice template and its automated checks, Wesam’s repo ships exactly this capstone with a checker — link below.

1. 01A committed CLAUDE.md that names your test command (lesson 5 gives you one).
2. 02A clean working tree — commit or stash anything riding along.
3. 03The version noted: claude --version > version.txt. The session’s provenance is part of the record.

02The task

1. 01Plan mode before your first prompt. Have Claude read the bug report and plan the fix — and ask for the plan that adds the failing test first, runs it so you watch it fail, then fixes the code and runs it again. The official best-practices wording is exactly that: write a failing test that reproduces the issue, then fix it.
2. 02While the final plan is on screen: snapshot git status --porcelain (it should be empty) and the plan’s file list.
3. 03Approve — manually. Watch the new test fail, then pass. If you never saw it fail, you do not know it tests the bug.
4. 04Review the whole diff, the test file included (git add -N for new files). Ask for at least one correction that stays inside the plan’s files. Tests green.
5. 05Commit the fix and its test together, one commit. git show --stat HEAD shows both. Snapshot the commit hash; git status reads clean.
6. 06Steer the session as you go: /context when it feels long, /compact with a keep-instruction, /rewind if a turn went wrong.

Every box below ticked is the Beginner exit. Installment 2 — Intermediate: skills, hooks, subagents, MCP and plugins — picks up exactly here.