Codex Read-Only Repo Investigation for a Bug Report

Runs a read-only Codex investigation that maps the relevant code paths, test commands, and likely root causes for a bug report. It ends with a ranked hypothesis table and a go/no-go recommendation before any edits.

You get: Summary, code map table and hypotheses table

More like this

The prompt

codex-read-only-repo-investigation-for-a-bug-report.md
Role: You are Codex running non-interactively in a read-only sandbox as a senior engineer investigating a bug in an unfamiliar repository.

Context: Repository at {repo_path}. Bug report: {bug_report}. Known environment: {environment_details}. The decision this supports: whether to approve a fix, which files an implementer should touch, and how risky the change is.

Task: Investigate and report. Do NOT modify files, install dependencies, or access the network.

Inputs (confirm each, list missing ones under Assumptions):
- {repo_path}, {bug_report}, {expected_behavior}, {actual_behavior}, {reproduction_steps}, {suspected_area} (optional)
- Repo guidance: read AGENTS.md, README, CONTRIBUTING, and package/build manifests first if present.

Workflow:
1. Read repo guidance files and record the language, framework, build tool, and documented test commands.
2. Locate entry points and code paths related to the bug using file search and grep. Record file:line evidence for each claim.
3. Trace data flow from input to the observed failure. Note where behavior diverges from {expected_behavior}.
4. Find existing tests covering this area and identify the coverage gaps.
5. Form 2-4 root-cause hypotheses and rank them by confidence, citing evidence for and against each.
6. Propose a minimal fix plan and a verification plan (exact commands to run later, not run now).

Constraints:
- Read-only commands only (ls, cat, rg, git log, git blame, git diff).
- Never state that a command passed unless you ran it. Label all untested claims as hypotheses.
- No secrets or credentials in the output; redact any you encounter.

Output format:
1. Summary (max 5 lines)
2. Assumptions and missing information
3. Code map table: | File:line | Role | Relevance to bug |
4. Hypotheses table: | Rank | Hypothesis | Evidence for | Evidence against | Confidence |
5. Proposed fix plan: ordered steps with target files
6. Verification plan: exact commands and expected results
7. Risks and blast radius
8. Recommendation: GO / NEEDS-INFO / NO-GO, plus next actions

Acceptance criteria:
- Every hypothesis cites at least one file:line reference.
- The fix plan names specific files and functions.
- Verification commands match those found in the repo, not guessed.
- No files were changed (confirm with git status output).

Quality checks:
- Re-open each cited file:line and confirm it supports the claim.
- Separate facts, inferences, and assumptions.
- Run git status at the end and report the result.

Example output

AI-written example
# Investigation: Discounted invoice totals off by $0.01 (repo: /workspace/billing-service)

## 1. Summary
- Node 20 / TypeScript / Jest repo; documented test command is `npm test` (README.md:42).
- Fact: `calcTotal` rounds each line item before applying the percentage discount (src/billing/totals.ts:58-71).
- Inference: this causes the 1-cent drift on multi-line invoices with `PCT_*` codes.
- No files were modified. Nothing was executed except read-only commands.

## 2. Assumptions and missing information
- Assumed {suspected_area} = src/billing/ (stated in the bug report).
- Missing: production invoice IDs, so I could not confirm exact figures.
- Assumed the environment is Node 20.11 per .nvmrc:1.

## 3. Code map
| File:line | Role | Relevance |
|---|---|---|
| src/api/invoices.ts:34 | POST handler | Calls `calcTotal(items, code)` |
| src/billing/totals.ts:58-71 | `calcTotal` | Rounds per line, then discounts |
| src/billing/discounts.ts:22 | `applyDiscount` | Rounds again after the percentage |
| src/billing/money.ts:9 | `roundCents` | Uses `Math.round`, which is float-sensitive |
| test/billing/totals.test.ts:15-60 | Unit tests | Only single-line invoices |

## 4. Hypotheses
| Rank | Hypothesis | Evidence for | Evidence against | Confidence |
|---|---|---|---|---|
| 1 | Double rounding (per line, then after discount) | totals.ts:62 and discounts.ts:27 both call `roundCents` | None found | High |
| 2 | Float math in `roundCents` (e.g. 1.005 * 100) | money.ts:11 | Would not explain multi-line-only drift | Medium |
| 3 | Tax applied before discount in the API layer | invoices.ts:41 | Order matches the spec in docs/billing.md:18 | Low |

## 5. Proposed fix plan
1. In `calcTotal` (totals.ts), sum unrounded line amounts, apply the discount once, then round once.
2. Remove the redundant `roundCents` call in `applyDiscount` (discounts.ts:27).
3. Optional, separate PR: change `roundCents` (money.ts) to integer-cent arithmetic.
4. Add multi-line discount cases to totals.test.ts.

## 6. Verification plan (not run)
- `npm test -- test/billing` — expect the new multi-line cases to pass.
- `npm run lint` (package.json:12) — expect no errors.
- `npm test` — expect the full suite to stay green.

## 7. Risks and blast radius
- `applyDiscount` is also imported by src/reports/monthly.ts:80, so report totals may shift by cents.
- Historical invoices are unaffected unless they are recalculated (src/jobs/recalc.ts:14).
- Overall risk: low to medium.

## 8. Recommendation
**GO** for steps 1, 2 and 4. Defer step 3.
Next actions:
- Confirm the expected rounding policy with Finance.
- Check the monthly report consumer.

Re-opened all cited lines and confirmed they support the claims.
`git status` output: `nothing to commit, working tree clean`
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Run from the repo root, for example: codex exec --sandbox read-only "<prompt>". Flag names vary by Codex CLI version, so check codex exec --help. Fill every variable first; vague bug reports produce weaker hypotheses. Use the output as the input to an implementation run.

Questions about this prompt

More in Codex

Codex Characterization-Test-First Refactor with Verification Handoff

Runs a behavior-preserving refactor in Codex exec. It pins current behavior with characterization tests, refactors in small verified steps inside an allowed scope, and ends with an evidence-based handoff for the merge decision.

Codex CI Failure Triage: Reproduce, Classify, Fix or Hand Off

Guides Codex through reproducing a failing CI job locally, classifying the cause as code, test, environment, or flaky, applying a minimal fix when safe, and producing an evidence-based handoff for anything it cannot resolve.

Codex Exec CI Fixer: Diagnose, Minimal Fix, Rerun, Stop After 3 Attempts

Gives codex exec a non-interactive procedure to diagnose a failing CI output, apply a minimal fix, rerun the checks and stop after three attempts with a clear report.

Outcome-First Codex Task Writer for a Feature or Bug Request

Turns a raw feature or bug request into a paste-ready Codex task with a goal, constraints, files in scope, definition of done and exact verification commands.

Codex Pre-Merge Diff Review with Severity-Ranked Findings

Has Codex review a branch diff against a base ref in read-only mode. It checks correctness, tests, security, and maintainability, and returns evidence-backed findings with severity and a merge recommendation.

Codex Pull Request Review With Comments Ranked by Severity

Has Codex review a pull request and return comments sorted into blocking, should-fix and nit, each with the file and line, the risk, and a suggested change.

Codex Writes an AGENTS.md for This Repository From the Real Setup

Has Codex inspect your repository and write a short, accurate AGENTS.md with the real build, test and lint commands, conventions and boundaries, checked by actually running them.

Agent Run Pre-Mortem and Self-Correction Loop Designer

Designs verification checks, error handling, and a self-correction loop for an agent task before it runs, based on likely failure modes.

Cursor Agent Bug Triage: Reproduce, Root-Cause, Fix, and Regression Test

Guides Cursor Agent through reproducing a bug, isolating the root cause with evidence, applying a minimal diff, and adding a regression test, ending with a verification checklist and risks.

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.

Plan Before Edit: Cursor Plan-Mode Prompt for a Feature Request

Produces a read-only Cursor plan listing files in scope, ordered steps, specific risks and tests to run before any code is changed.

Cursor .mdc Rules to Portable AGENTS.md Converter

Converts your pasted Cursor .mdc rules into a single AGENTS.md that Codex, Copilot and Gemini CLI can read, plus a table of what does not carry over.