Reproduce first debug

Reproduce-First Debugging

Force a failing reproduction before any hypothesis, then keep that reproduction forever as a regression test.

Scope

Covers defect investigation from report to logged root cause: gathering trigger data, building a reproduction artifact, bisecting the broken layer boundary, and promoting the reproduction to a permanent test.

Does not cover: implementing features, reviewing diffs, performance profiling without a functional defect, or fixing a defect whose root cause is already confirmed and evidenced — in that case go straight to the fix.

Examples

/reproduce-first-debug Promotion code is ignored on the cart page for bundled products

/reproduce-first-debug ABC-1234

# Also triggers on a bare paste, with no question attached:
/reproduce-first-debug TypeError: Cannot read properties of undefined (reading 'total') at CartSummary.vue:42

Workflow

flowchart TD
    A[1. Collect trigger data] -->|complete| B[2. Build reproduction artifact]
    A -->|input missing| A1[Ask for the specific input. STOP.]
    B -->|artifact fails reproducibly| C[3. Bisect the layer boundary]
    B -->|cannot reproduce, input missing| A1
    B -->|cannot reproduce, inputs present, attempts < 3| B
    B -->|cannot reproduce after 3 attempts, inputs present| B1[Not reproducible locally. Record attempted vectors, hand back: instrumentation or prod trace. STOP.]
    C --> D[4. Promote to regression test, commit RED]
    D --> E[5. Minimal fix, show red to green]
    E --> F[6. Log to bug ledger]

Strict order. No step may be skipped, reordered, or run speculatively in parallel.

Preconditions

Checked once, before step 1 — the reproduction artifact built in step 2 makes the tree dirty by design, so these cannot be deferred to the commit in step 4:

• Working tree must be clean (git status --porcelain empty). Otherwise abort with the note "Please commit or stash first."
• The current branch is not main/master/develop (no commit on the default branch).

1. No hypothesis without data

Collect before considering any cause:

• The symptom, stated as observed behaviour, not as a suspected cause.
• The exact trigger inputs: URL, product ID, promo code, order number, command, payload.
• Observed vs. expected, both concrete.

Anything missing: ask for it specifically and stop. Do not guess, and do not start reading code to compensate for a missing input — naming the wrong root cause early costs more than one clarifying question.

2. Build the reproduction artifact

The cheapest form that genuinely hits the defect:

• Unit or jsdom test
• curl sequence (against local/dev hosts only — never a production endpoint)
• SQL against local fixtures
• Dev-only mock
• DOM-faithful HTML mockup

Use local fixtures. Never real ticket or production data.

Gate: continue only once the artifact reproducibly FAILS and the failing output is pasted. A reproduction that cannot be made to fail on demand is not a reproduction.

If the defect cannot be reproduced and an input is missing: stop and state precisely which input is needed. Do not propose fixes.

If all requested inputs are present and the defect still won't reproduce after 3 attempts: stop retrying. Declare "not reproducible locally", list every vector attempted (exact commands, fixtures, branch, environment), and hand back to the user with concrete options — add instrumentation/logging at the suspected boundary, or request a production trace for the specific window. This is a valid terminal state, not a failure to resolve before continuing; do not loop on asking for more input once inputs are confirmed present.

3. Bisect the layer boundary

For each layer boundary, prove which side is broken:

"Client sends the correct PUT; the backend handler is a no-op."

Declare nothing healthy without evidence. VERIFIED requires pasted output; anything else is HYPOTHESIS and must name the cheapest command that would settle it.

4. Reproduction becomes a regression test

Commit rules (the entry Preconditions above already established a clean tree and a non-default branch):

• Stage only the reproduction test. Unrelated files that appeared meanwhile are not swept in.
• Commit message follows the repo's conventional style (e.g. test(auth): add RED repro for ABC-1234).
• Never push. The user pushes when ready.

Promote the artifact to a permanent test in the suite:

• Named after the ticket
• Committed separately and RED, before the fix

A reproduction deleted after the fix guarantees the defect can return unnoticed.

5. Fix and verify

• Minimal fix — scope stays on the located cause, no neighbouring cleanup.
• New test plus all gates green; show the red-to-green transition with real output.
• Where a target system exists (dev shop, preview URL, live product page), verify the visible behaviour there too, not only in the test suite.

6. Log it

Append one row to docs/bug-ledger.md, creating the file with this header if absent — write only the header shown, no rows:

# Bug Ledger

| Date | Symptom | Root cause | Layer | Guarding test |
| ---- | ------- | ---------- | ----- | ------------- |

Example row, illustrating the schema only — this is a sample and must not be written into the created file:

| 2026-07-28 | Promo ignored on bundles | Bundle line items skip the discount collector | Backend service | `PromoBundleTest::testBundleGetsDiscount` |

Principles

• A reproduction is the entry ticket to debugging, not an optional first step.
• Evidence or silence: every claim is VERIFIED with pasted output, or explicitly labelled HYPOTHESIS.
• Never call a mitigation (masking, gate, retry, cooldown) a fix — state what it prevents and what it does not.
• Local fixtures over real data, always.

Related skills

• branch-review — reviewing a diff for defects, rather than investigating a reported one.
• session-handoff — capturing the investigation state when a defect outlives the session.