Act as a senior engineer investigating a reproducible software defect. Work from the evidence I provide; do not invent APIs, configuration, logs, dependencies, or a root cause. Expected behavior: [EXPECTED BEHAVIOR] Actual behavior and exact reproduction steps: [ACTUAL BEHAVIOR AND REPRO] Relevant code, including the smallest complete function or module and its callers if available: [RELEVANT CODE] Error output, stack trace, logs, test failure, or observed request/response: [EVIDENCE] Runtime details: language, version, framework, OS, dependency versions, input data, and recent changes: [ENVIRONMENT AND RECENT CHANGES] First restate the failure as a testable assertion and identify the narrowest boundary where expected and actual behavior diverge. Build a ranked hypothesis list with: hypothesis, evidence for or against, fastest discriminating check, and what result would rule it out. Do not jump to code changes before this diagnosis.
Then provide: 1. A minimal reproduction or focused failing test, using the project’s apparent test style. If details are missing, write pseudocode and label the exact unknowns. 2. The most likely root cause, with a line-by-line explanation of the execution path that causes it. Separate certainty from inference. 3. A minimal patch as a unified diff or clearly delimited replacement block. Preserve public interfaces unless a change is necessary; explain any behavioral change. 4. Regression tests for the reported case plus two meaningful edges relevant to this bug, such as null input, boundary values, concurrency, time zones, retries, encoding, or error handling. 5. A verification checklist: exact commands to run, expected results, and one production-safety check such as migration impact, backward compatibility, observability, or rollback. Self-check that the patch addresses the stated reproduction and that every new test would fail before the patch. Flag security, data-loss, race-condition, performance, and compatibility risks when relevant. Ask up to 3 clarifying questions only if a required input is missing.
Fill in
| Placeholder | What to enter | Example |
|---|---|---|
| [EXPECTED BEHAVIOR] | Describe precisely what the code should do for the failing case. | POST /api/invoices should reject an invoice whose dueDate is before issueDate with HTTP 400 and a field error. |
| [ACTUAL BEHAVIOR AND REPRO] | Give the observed result and numbered steps or input that reliably reproduces it. | It returns 201 and saves the record. Send {"issueDate":"2026-09-10","dueDate":"2026-09-01","total":125} to the endpoint. |
| [RELEVANT CODE] | Paste the smallest relevant code section and any caller or test needed to understand it. | Node/TypeScript Express route calls validateInvoice(body), then invoiceService.create(body). validateInvoice checks required fields but not date order. |
| [EVIDENCE] | Paste the exact error, logs, stack trace, request/response, or failed assertion. | Integration test expected 400 but received 201; database row shows due_date 2026-09-01. |
| [ENVIRONMENT AND RECENT CHANGES] | State language and dependency versions, runtime context, sample data, and recent changes that may matter. | Node 22, TypeScript 5.6, Express 5, PostgreSQL 16. A validation refactor moved date parsing last week. |
How to use
- Paste an exact failing input and output, because “it does not work” cannot become a reliable test.
- Include the smallest relevant code path and version details; remove secrets, tokens, and customer data before sharing logs.
- Run the proposed failing test before applying the patch, then run it again plus the existing suite afterward.
- Follow up with: “Here is the real test output after the patch. Diagnose any remaining failure without changing unrelated code.”
Variations
Production incident triage
Use this when a service is failing in production and you need a safe first investigation.
Triage this production incident using [SYMPTOMS], [TIMELINE], [LOGS AND METRICS], [RECENT DEPLOYS OR CONFIG CHANGES], and [SERVICE ARCHITECTURE]. Produce a timeline, a ranked set of falsifiable hypotheses, and the next safest diagnostic check for each. Identify immediate containment actions separately from permanent fixes, and state their tradeoffs. Do not invent telemetry or tell me to restart or roll back without evidence. Include customer-data, availability, and dependency risks. Ask up to 3 questions only for missing information that prevents a safe next step.
Code review bug hunt
Use this when code has not failed yet but you want to find likely correctness bugs.
Review [CODE] for correctness defects in the context of [INTENDED BEHAVIOR], [INPUTS AND DATA MODEL], and [RUNTIME ENVIRONMENT]. Return only concrete, plausible bugs: severity, triggering input or sequence, affected line or construct, consequence, and a minimal fix. Cover error paths, boundary conditions, nullability, parsing, async ordering, resource cleanup, and authorization where relevant. Do not report style preferences as bugs. For each finding, supply a test that would expose it. Mark anything requiring unseen code as an assumption.
Test failure analysis
Use this when a single unit or integration test is failing and you want to preserve its intended contract.
Analyze this failing test: [TEST CODE], [FAILURE OUTPUT], [IMPLEMENTATION], and [RECENT CHANGE]. First state the contract the test is asserting and whether that contract is supported by the implementation’s public behavior. Then give 2–4 hypotheses, each with a quick check. Recommend whether to fix code, correct the test, or revise both only after the evidence. Provide the smallest patch and an additional regression test. Do not weaken assertions merely to make the suite pass; flag brittle timing, mock, fixture, or shared-state issues.
Tips
- Make a repro input copy-pasteable and include the expected status code, value, or side effect; it becomes the seed of a regression test.
- Read the first application stack frame and the immediate caller before changing code; downstream exceptions frequently mask an earlier bad state.
- For async bugs, record ordering and timing evidence such as request IDs, timestamps, retry count, and shared resource state rather than assuming a race condition.
- A fix is incomplete if the test passes only because it stops reaching the broken code path; assert the business result and relevant side effect.
FAQ
Should I paste my entire repository into a debugging prompt?
No. Start with the failing path, relevant caller, test or reproduction, and exact evidence. Add surrounding code only when a hypothesis depends on it.
Can Claude identify a bug from a stack trace alone?
It can suggest hypotheses, but a stack trace rarely proves root cause. Pair it with the failing input, relevant code, versions, and recent changes.
How do I know an AI-generated fix is safe?
Apply it in a branch, run the new regression test and existing tests, and inspect interface, migration, authorization, and performance effects before deployment.