/bug-reproducer

name: bug-reproducer
description: Find likely software bugs in a codebase, rank concrete bug candidates, and prove or reject them with focused regression tests before proposing a fix. Also turn bug reports, stack traces, screenshots, failing behavior, support tickets, and regressions into minimal reproducible cases with red-to-green evidence. Use when Codex needs to hunt for unknown bugs, audit code for correctness defects, test suspicious edge cases, reproduce a reported failure, isolate root cause, or verify that an approved fix works without regressions. Honor explicit user authority for the requested fix; use approval gates only for authority that the request did not already grant or when scope materially changes. Do NOT use for ordinary implementation where no bug investigation or reproduction is needed.

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