Bug Reproducer

Bug Reproducer

Turn a codebase or bug report into evidence. When no bug is supplied, discover concrete candidates from the code and its contracts, then try to prove the strongest candidates with focused tests. Never present a suspicion as a confirmed bug.

Honor existing authority, then apply missing gates

Invocation alone to hunt for unknown bugs is inspection-only. A direct request to fix or implement a reported bug, or to find and fix bugs in a named repository, authorizes the normal reversible reproduction tests and causal production edits inside that stated task. A direct request to reproduce a reported bug or create its regression test likewise authorizes the normal reversible reproduction files and commands, but not a production repair. Record the matching task scope and proceed without stopping for duplicate confirmation, even when the exact responsible file is learned during diagnosis. Do not ask the user to approve the same scope twice.

If the user asked only to inspect, audit, find, or isolate, do not infer permission to create reproduction files or change production code. A direct reproduction or regression-test request authorizes only the normal reversible reproduction work described above; it does not authorize a production repair. Before a gate that has not been satisfied, do not create or edit project files, install dependencies, run formatters or migrations, modify configuration, generate reports, create worktrees, or execute commands likely to mutate project state. Read source, configuration, documentation, existing tests, user-supplied logs, and Git history. Run an existing targeted test only when it is clearly safe and does not require project changes.

Gate 1 — test the candidate

When the current request has not explicitly authorized creating and running a reproducer, present and stop at:

## Bug candidates

| # | Candidate | Contract evidence | Trigger | Location | Confidence |
|---|---|---|---|---|---|
| 1 | ... | ... | ... | file:line | high/medium |

## Proposed bug test

- Candidate(s) to test:
- Why each could be a real bug:
- Exact files to create or edit:
- Minimal fixture/input:
- Test or harness command:
- Signal that will confirm each bug:
- Main risk or uncertainty:

No project files have been modified. Do you want me to create and run these tests?

List only candidates backed by a reachable code path, a defensible expected behavior, and a specific triggering input or state. Approval covers only the displayed reproduction files and commands. A direct request to reproduce a supplied symptom or write its regression test already satisfies this gate: record that scope and continue without requiring file names that diagnosis has not yet established. Test one strong candidate by default; batch at most three only when their files and commands are all explicit.

Gate 2 — fix a proven bug

When the current request has not already authorized a causal production repair, present and stop at:

## Proposed fix

- Reproduction status: REPRODUCED
- Proven bug:
- Root cause:
- Exact production files to change:
- Proposed transformation:
- Behavior that must remain identical:
- Regression and broader test plan:
- Main risk:

The bug is proven by a failing test, but no production fix has been applied. Do you want me to apply this exact fix?

Continue when the current request already covers the causal repair or after explicit approval. If the file list, dependencies, public behavior, risk tier, or approach materially changes beyond that authority, request fresh approval. Never bundle unrelated cleanup or another fix into the approved patch.

Choose the workflow

• hunt-and-prove — Default when no specific bug is supplied. Discover, rank, and test likely correctness bugs.
• reproduce-only — Stop after a minimal failing case is proven. Use when the user asks only to find, reproduce, isolate, or write regression tests.
• prove-fix — Use for a reported bug or after a discovered candidate is proven and the user wants it fixed. Apply only gates not already satisfied by the current request, then prove red to green.
• flaky — Reproduce timing, ordering, seed, isolation, or concurrency-dependent failures across repeated controlled runs. Do not label one intermittent failure as reproduced.

Run hunt-and-prove

1. Map the project read-only

• Identify runtime, entry points, public interfaces, data boundaries, test framework, existing commands, and high-change or high-risk modules.
• Derive intended behavior from tests, types, schemas, documentation, callers, UI copy, API contracts, and invariants. Prefer explicit contracts over personal style preferences.
• Inspect recent changes only when repository history is available; do not assume old code is correct.
• Read references/bug-discovery-playbook.md before ranking candidates.

2. Generate concrete candidates

• Trace user-controlled or boundary inputs through real reachable paths.
• Look for falsifiable defects: off-by-one boundaries, inverted conditions, missing empty/null handling, unsafe state transitions, ordering or deduplication errors, stale cache keys, permission gaps, precision/time-zone mistakes, async races, inconsistent validation, and error paths that violate the surrounding contract.
• For every candidate, identify the exact path, triggering input/state, expected result, likely actual result, and evidence for the expectation.
• Reject vague possibilities such as “this could be null” unless the codebase permits null and the path mishandles it.
• Do not call security posture, performance, formatting, maintainability, or missing features a bug unless they violate a concrete product contract.

3. Rank before testing

Rank candidates using:

1. Contract strength — Is expected behavior explicit in tests, types, docs, schemas, callers, or consistent nearby behavior?
2. Reachability — Can a real caller or valid input reach the path?
3. Reproducibility — Can a small deterministic test distinguish correct from incorrect behavior?
4. Impact — Does it affect outputs, data, permissions, crashes, or a user-visible workflow?

Show no more than five candidates and label confidence high, medium, or low. Do not propose testing low-confidence candidates while a stronger one exists. If no candidate survives this filter, return NO_BUG_PROVEN and identify the next useful evidence instead of inventing a bug.

4. Resolve Gate 1 authority

• If the request explicitly asked to reproduce a supplied symptom, create a regression test, or otherwise authorized reproduction work, record the matching task scope and continue. Do not require exact file names before diagnosis establishes them.
• Otherwise show the ranked shortlist and exact test plan for the strongest one to three candidates.
• Name every file and command that approval would cover.
• State that no project files have been modified, then stop and wait.

5. Test approved candidates

• Create only the approved test or harness.
• Use deterministic inputs and the smallest fixture that reaches the real production path.
• Assert the intended contract, not the current implementation.
• Capture the narrow command with scripts/capture_command.py when appropriate:

python3 scripts/capture_command.py --label reproduced --output reproduced.json -- npm test -- path/to/regression.test.ts

• Confirm that a failure matches the predicted behavior and cause. Syntax errors, missing dependencies, invalid fixtures, unrelated failures, and assertions built on an unsupported assumption reject or invalidate the candidate.
• Return REPRODUCED, NOT_REPRODUCED, or INCONCLUSIVE for each tested candidate. Clearly separate rejected speculative tests by default. Delete them only with explicit user authority.
• Stop after evidence when the user requested discovery or reproduction only. Do not slide into production changes.

6. Isolate and resolve Gate 2 authority

• Trace a reproduced failure to the smallest responsible condition and distinguish root cause from the line where it surfaces.
• If the current request already authorized the causal fix, record how the patch remains inside it and continue.
• Otherwise show Gate 2 with exact production files, transformation, preserved behavior, checks, and risk, then stop and wait for separate approval.

7. Apply only the approved fix

• Preserve the regression test unless the user explicitly requests a temporary harness.
• Change only the approved production files and necessary test expectations.
• Prefer the smallest causal fix over symptom suppression.
• Do not weaken assertions, catch and ignore errors, add arbitrary retries, disable tests, or broaden tolerances merely to turn the test green.