---
name: diagnosing-bugs
description: Investigate bugs and performance regressions to explain their cause with evidence. Use for diagnosis or debugging; implement repairs only when fixing is also requested.
---

# Diagnosing Bugs

Read the relevant flow, existing tests, `CONTEXT.md`, and applicable ADRs. Establish the requested outcome: diagnosis ends with a cause and evidence; an authorized fix also includes repair and regression checks. Keep all investigation within permitted systems and preserve unrelated work.

## Find a useful signal

Start from the reported symptom and what is already known. Read code, logs, and recent changes to form hypotheses; do not require a running reproduction before inspecting the code.

Prefer the smallest reliable reproduction: an existing failing test, a scoped command with dummy input, a local request, or a browser check. Choose a harness only if existing checks cannot reach the failure. When a human must perform the trigger, adapt [the HITL loop template](scripts/hitl-loop.template.sh); do not run it unattended.

Capture the exact error, wrong result, or measured regression. Distinguish the reported bug from nearby failures. Minimize inputs when it helps separate causes; perfect minimization and second-long execution are not prerequisites.

For intermittent bugs, record attempts, failures, and environmental conditions. Use bounded stress or repeated runs when safe; do not overload shared systems. A low reproduction rate is evidence, not a reason to abandon inspection.

If execution is unavailable, continue safe code/trace analysis, distinguish a probable cause from a confirmed one, and state what would confirm it. Request only the missing artifact or access that materially limits progress. Production instrumentation requires explicit authority.

## Test explanations

Rank plausible hypotheses by evidence and state a prediction for each. One well-supported explanation may be enough; compare alternatives when uncertainty warrants it.

Use targeted inspection or probes to distinguish predictions. Change one relevant variable at a time where practical. Tag temporary instrumentation with a task-unique prefix, avoid sensitive payloads, and keep track of exactly what you added.

For performance, measure the same workload against a baseline before proposing an optimization; account for warmup and noise. Use profiling, query plans, or bisection when they help isolate the cause. Keep bisection out of a shared dirty worktree.

## Repair only when requested

For an authorized fix, turn the reproduction into a regression check before the repair where feasible. Exercise the real failing caller pattern: a single-caller unit test cannot prove a multi-caller race is fixed.

Apply the smallest root-cause correction, rerun the original scenario, then relevant surrounding tests. If no reliable check is available, state the resulting verification gap rather than claiming success from an unrelated green test.

## Hand off

Remove only your own temporary probes and disposable artifacts. Report the cause, supporting evidence, checks run, and remaining uncertainty. For a fix, also report the changed behavior and regression result.

Mention a broader architecture issue only when the evidence supports it; do not launch another audit or refactor unless requested or necessary for the authorized repair.