Debug

Take the reported symptom through diagnosis to a verified fix in this session. Match effort to uncertainty. No brainstorm spec or diagnosis document is required.

Working rules

• The main agent inspects the report, reproduces the failure, diagnoses the cause, writes the regression and fix, and verifies the result itself.
• Use subagents only when useful, available, and permitted for bounded code lookup, alternative hypotheses, extra checks, or read-only review.
• Give agents current evidence, rules, and explicit file or environment ownership. Reuse them with updated context.
• Parallelize independent side tasks without further delegation. Serialize writes and probes unless dependencies and environments are isolated.
• Prevent probes from altering each other's signal or competing for measurement resources.
• Verify returned evidence, actions, and uncertainties. Present useful conclusions, keeping raw reports out of chat.

Step 1: Inspect the report

• Inspect repository instructions, relevant code, ADRs, recent changes, and expected versus actual behavior yourself.
• Research material unknowns using reliable primary sources. Check dates and applicability, retaining links.
• Capture the starting Git ref, status, and relevant diff. Reconcile findings and preserve unrelated user changes.

Step 2: Reproduce the signal

• Reproduce the signal yourself at a meaningful public boundary: test, CLI, HTTP request, browser flow, replay, or focused harness.
• Capture the specific failure and a working comparison when useful. Unrelated setup errors or non-crashing runs are not reproduction.
• Reduce inputs while preserving the signal. Stop minimization once the cause is evidenced.
• For flakes, repeat triggers and record failures/attempts, timing, seeds, and environment. Use controlled scheduling or stress if useful.
• For performance, record repeated comparable baselines before edits: workload, measurement boundary, and variation.
• Profile or compare scaling to locate cost. One fast run is insufficient evidence.
• If reproduction or access is missing, investigate locally and distinguish facts from hypotheses. Do not patch on speculation.
• When blocked, report attempts and request specific missing access, reproduction details, or a redacted capture.
• Success in another scenario does not verify the reported failure.

Step 3: Diagnose the cause

• Trace callers and system boundaries yourself. Optional side investigations may propose alternative hypotheses with evidence.
• Compare working inputs, configuration, and changes. Decide the cause from distinguishing evidence yourself.
• Test a falsifiable cause prediction with a distinguishing probe, varying one factor at a time.
• Reconcile evidence and rank hypotheses after each probe. An obvious bug does not require a hypothesis quota.
• When uncertain, share this update without turning it into an approval checkpoint:

Evidence: <observed failure and working comparison>
Hypotheses, ranked: <cause → support or conflict>
Next probe: <prediction and distinguishing command>

• Prefer targeted probes to broad logs. Mark temporary instrumentation uniquely and track disposable files.
• Inspect only needed fields, redact secrets, and keep credentials in the environment rather than command arguments.
• Avoid environment dumps. Follow environment authorization rules for external mutations and production instrumentation.
• Revert edits made for a refuted hypothesis before the next probe. Keep only changes the evidence supports.
• After three relevant failed fixes, including prior attempts, stop patching and reassess shared state, ownership, coupling, and assumptions.
• Explain what failures rule out. Gather new distinguishing evidence before another fix. Do not begin an unapproved redesign.

Step 4: Fix the supported cause

• Write the regression and fix yourself after evidence supports the cause. Keep the reproduction, rules, and criteria in view.
• Write a regression for the actual bug pattern at a meaningful automated seam. Observe failure for the reported reason before the fix.
• Exercise the interaction for cross-boundary or multi-caller bugs. Make the smallest evidence-supported change.
• Fix where the fault starts, not where it shows. A guard, retry, catch, or clamp is a fix only when its state is legitimate.
• If the state should never exist, fix what produced it. Check for the same fault in scope and fix it at that shared cause.
• Ship no "might help" changes beside the fix. Delete code the fix replaces and reuse existing helpers.
• Comment only a non-obvious why that the code cannot show. A workaround that needs a long comment means the fix is wrong.
• If no meaningful automated seam exists, explain why and use the strongest observable check. Avoid coverage-only tests.
• Inspect the result against regression red/green and original reproduction evidence.

Step 5: Verify the fix

• Run the regression green, original unminimized scenario, and relevant neighboring checks. Investigate failures.
• Extra checks may be side tasks with a specified revision and environment. Verify the original failure yourself before claiming success.
• Repeat comparable flaky/performance measurements. Report bounded results: finite successful runs cannot prove a race absent.

Step 6: Review independently

• If no behavior changed, skip fix review and report whether the symptom was reproduced, resolved without edits, unconfirmed, or blocked.
• When delegation is available and permitted, give two reviewers the report, reproduction, cause evidence, baseline, fix diff, rules, and checks.
• Use reviewers who did not implement the fix. Run read-only reviews in parallel without further delegation.
• If delegation is unavailable or prohibited, review each axis yourself and disclose the limitation.
• Cause and regression: check cause evidence, test seam, detection of the bug or a plausible equivalent, and original reproduction.
• Code: check correctness, maintainability, security, concurrency, errors, compatibility, unintended behavior, and repository rules.
• Ask what could be deleted without changing behavior. Flag guards hiding illegitimate states and edits the cause does not need.
• Distinguish rule violations from judgment calls. Exclude unrelated pre-existing issues.
• Keep separate verdicts (Approve, Findings, Blocked), unverifiable items, and findings graded critical, important, or minor.
• Each finding needs file:line, conflicting evidence or rule, impact, and a concrete fix when needed.

Step 7: Resolve review findings

• Verify findings against evidence and code. Fix valid in-scope issues yourself and reuse the original reviewers.
• Rerun affected regression and original reproduction. Recheck every open finding and new problems introduced by fixes.
• Repeat full reviews when cause, behavior, or design changes materially.
• Continue until both axes approve without material findings or a concrete external blocker prevents completion.

Step 8: Clean up and report

• Audit instrumentation, abandoned fix attempts, disposable harnesses, final diff, and untracked files against the baseline.
• A read-only side check may help.
• Remove temporary artifacts while preserving user files. Retain harnesses only for explicit regression or benchmark purposes.
• Verify cleanup and ensure final checks cover review fixes. Reuse current passing evidence if no relevant change followed it.
• Report in chat without requiring a commit, publication, or diagnosis document:

Symptom and reproduction: <command and observed result>
Root cause: <evidence, or unconfirmed>
Change: <fix and regression, or none>
Reviews: <cause/regression verdict; code verdict; fixes>
Verification: <commands, outcomes, original scenario>
Limits or blocker: <remaining uncertainty or required input>