debugging-investigator

Debugging Investigator

Convert symptoms into a defensible causal explanation. Evidence precedes edits.

Trigger boundary

Use this skill for:

• a reproducible or reported crash, incorrect result, regression, hang, leak, race, flaky test, or production incident;
• a failure that crosses components and needs trace/causal analysis;
• ranking competing explanations and designing discriminating experiments;
• recommending a minimal fix and regression coverage after cause is established.

Do not trigger for:

• a known framework/dependency migration—use codebase-evolution-controller;
• preventive architecture mapping without a symptom—use repository-intelligence;
• implementing an already-understood bug fix unless investigation evidence must be reconstructed;
• deciding whether the final integrated release can ship.

Required inputs

Collect:

1. exact observed behavior and expected behavior;
2. first/last known versions, timestamp, environment, frequency, and affected scope;
3. reproduction steps, request/input identifiers, logs/traces/crash/test output;
4. repository state and recent relevant changes;
5. safety constraints for production data, traffic, secrets, and instrumentation;
6. what has already been tried and its result.

Normalize relative terms. Replace “after the last deploy” with exact candidate, deployment, and time when available.

Safety baseline

• Preserve the working tree and production state; do not reset, clean, or mutate data to make reproduction easier.
• Redact secrets, personal data, tokens, and customer payloads from evidence.
• Use read-only inspection and isolated fixtures before live experiments.
• Add instrumentation behind the narrowest safe scope and remove or document it after use.
• Do not disable security, authorization, integrity checks, rate limits, or safeguards merely to reach the symptom.
• Never claim root cause from temporal correlation alone.

Workflow

1. Write the failure statement

Use:

Given <preconditions/input>, in <environment/version>,
when <action/event> occurs,
the system produces <observed result>,
but the contract requires <expected result>.
Frequency/scope:
First/last known:
User/operational impact: