41 lines
3.3 KiB
Markdown
41 lines
3.3 KiB
Markdown
---
|
|
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.
|