Reproduce First

Reproduce a reported bug as a failing test, then fix it

When to use this

The user has reported that something is broken. That includes the quiet forms: "it works except for…", "I have to do X twice", "it stopped doing Y", "is it supposed to…?".

Do NOT use it for: a request for a new feature, a question about how something works, or a bug you found yourself while already mid-task with a test already failing for that reason.

The order is the whole point

The first deliverable is a test that fails for the user's reason. Not a fix. Then fix it, and watch that same test pass.

Do not reverse the order, and do not skip to the fix because the cause looks obvious. A fix whose test was written afterwards tends to assert what the code now does rather than what the user asked for. "The cause is obvious" is the single most reliable predictor that it is not — see the case studies below, where two confident diagnoses were both wrong and only the control runs exposed it.

Process

1. Restate the symptom as the user sees it. At their altitude: a card that stays on screen, a tab that never appears, a name that reads wrong. Not "the registry entry is stale".

2. Find the test that already covers this surface, and EXTEND it. Bias order: extend an existing test > modify an existing test > write a new one. Only add a brand-new #[spec] id when no catalog entry covers the surface at all — search tests/CATALOG.md for the area before assuming there isn't one.

   Most follow-up reports are the SAME behaviour under a different configuration (a real agent instead of a stand-in, an orchestration instead of a single agent, a command the deck cannot infer an agent type from). That is a case for widening the existing test's coverage to the configuration that actually broke — not a parallel test duplicating 90% of the setup. A new spec id is justified when the mechanism genuinely differs, not when the inputs do.

   This matters more at L2 than anywhere else: every PTY test spawns real binaries, and a suite of near-duplicate e2e tests is slow for everyone and harder to diagnose than one test that names its cases.

3. Assert at the user's altitude. The user-visible outcome, not an adjacent artefact — a file on disk, a log line, or a registry entry can all be correct while the screen is wrong. If they said "no orchestration tab appeared", the assertion is a tab with live role cards.

4. Run it and confirm it fails FOR THEIR REASON. A test that fails for a setup error (a stub that broke an unrelated path, a form field that was pre-filled, an ellipsized card title) is not a reproduction. Read the failure message and check it describes their symptom. Fix the harness problem and re-run until the red is the right red.

5. Add a control that isolates the cause. The nearest thing that should still work — the same close on a card with no worktree, the same dispatch with a fast git — proves the failure is attributable to what you think it is. Without a control you cannot tell "this path is broken" from "this whole feature is broken".

6. Fix it.

7. Watch the same test go green, then prove each fix is load-bearing: revert one change at a time and confirm the test goes red again. If reverting a change leaves the test green, that change is not part of the fix — take it out or find what it is really doing.

8. Run the wider tier before reporting done: cargo xtask affected-checks --run (for a code change that is cargo fmt --check, rule 2's clippy command and cargo test-fast), plus the tests covering what you touched. There is no full-tier obligation before the PR — per CLAUDE.md rule 5, lane 1 runs in CI on every PR, so read that run rather than reproducing it. If your reproduction is an e2e test, run it and its module by filter (cargo test-e2e <filter>, or cargo test-e2e-live <filter> when the test reaches a real agent); do not run either alias unfiltered. A lane-2 test is worth running deliberately: nothing in CI runs one, so if you do not, nobody does.