Repro First

When to use

• A bug report, failing CI job, or user-reported incorrect behavior needs a fix.
• The user asks to "fix", "debug", or "investigate" without a confirmed repro.
• You are tempted to patch code based on a stack trace alone.

When not to use

• The failing test or minimal repro already exists and reliably fails.
• Pure documentation, rename, or formatting changes with no behavioral claim.
• Exploratory spikes where the goal is understanding APIs, not fixing a defect.

Assumptions

• Shell access to run the project's test runner, build, or app entrypoint.
• Ability to capture logs, exit codes, and (when relevant) screenshots or HTTP traces.
• Do not delete databases, wipe volumes, or reset shared environments without explicit confirmation.
• Prefer read-only inspection first; mutating fixtures or seed data requires confirmation if shared.

Workflow

1. Restate the observed vs expected behavior in one sentence each.
2. Locate or create the smallest input that triggers the failure.
3. Run that case and record the exact failure (message, exit code, artifact).
4. Only then change code — keep the repro as the verification oracle.
5. Confirm the same case passes after the fix; note any remaining related failures.

Steps

1. Capture symptoms — Quote the error, failing assertion, or incorrect output. Note version/branch/commit if known.
2. Bisect the surface — Prefer a unit/integration test over a full UI path. Strip unrelated setup until the failure still occurs.
3. Automate the repro — Add or update a test (or a script under scripts/) that fails for the right reason. Avoid flaky timing; use deterministic inputs.
4. Hypothesis lock — Write one sentence naming the suspected cause. Do not implement until the failing case is green to reproduce (red bar).
5. Minimal fix — Change only what the failing case requires. No drive-by refactors.
6. Verify — Re-run the repro (now green) plus the nearest existing suite for the same module.

Success criteria

• A minimal failing case existed (or was created) before production code changed.
• The failure reason matches the reported bug, not a different incidental error.
• After the fix, the same case passes with the same commands.
• No speculative cleanup landed in the same change unless required for the fix.
• Destructive environment resets were confirmed or avoided.

Out of scope

• Performance tuning without a correctness failure (use perf-measure-first).
• Broad rewrite of the module under investigation.
• Triaging flaky tests that pass on retry (use flaky-test-triage).