| name | debug |
| description | Diagnose a reproducible software failure by tightening the red feedback loop, testing one hypothesis at a time, and proving root cause before recommending a fix. |
Root-Cause Debugging
Run a systematic root-cause investigation before any fix is attempted.
Use this for failing tests, production bugs, build errors, regressions, unexpected behavior, or any situation where guessing would waste time.
Workflow
- Read the exact error and obtain the smallest deterministic reproduction.
- Capture the failing command and expected-versus-actual behavior.
- Compare the broken path with a working analogue and trace the data/control boundary
where they diverge.
- State one falsifiable hypothesis at a time and run the smallest discriminating test.
- Stop once evidence identifies the root cause. Recommend the smallest fix and the
regression test that fails before it.
Delegate an independent reproduction or trace only when it can run without overlapping
changes. This workflow diagnoses; it does not patch source code.
Evidence Receipt
Return spk.evidence/v1 with the reproduction command/result, observations,
hypotheses tested, proven root cause, affected paths, regression-test recommendation,
risks, and next action.
Guardrails
- No fixes before root cause evidence.
- If reproduction is impossible, return
NEEDS_REPRO with exact missing information.
- If 3 attempted fixes have already failed, flag
POSSIBLE_ARCHITECTURE_ISSUE instead of proposing a fourth patch.
- Never probe production data, credentials, destructive actions, or external services
without explicit operator approval in the main conversation.
