magia187 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
- Restate the observed vs expected behavior in one sentence each.
- Locate or create the smallest input that triggers the failure.
- Run that case and record the exact failure (message, exit code, artifact).
- Only then change code — keep the repro as the verification oracle.
- Confirm the same case passes after the fix; note any remaining related failures.
Steps
- Capture symptoms — Quote the error, failing assertion, or incorrect output. Note version/branch/commit if known.
- Bisect the surface — Prefer a unit/integration test over a full UI path. Strip unrelated setup until the failure still occurs.
- 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. - Hypothesis lock — Write one sentence naming the suspected cause. Do not implement until the failing case is green to reproduce (red bar).
- Minimal fix — Change only what the failing case requires. No drive-by refactors.
- 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).