grimoire-debug
Find, reproduce, locate, and explain failures. An error message is a clue, not proof of a root cause; connect the observed symptom to a mechanism with code inspection and discriminating runtime evidence where available. Separate observations, hypotheses, and confirmed causes.
Choose depth automatically
Use the smallest sufficient depth; change it when evidence warrants, without asking the user to select a mode.
| Mode | When | Method |
|---|---|---|
| Direct | The cause is clear and the impact local | Inspect the causal path, make an authorized fix, and verify the original symptom. No mandatory hypothesis list or minimization exercise. Escalate if the explanation or fix fails. |
| Investigate | The cause is unclear | Establish a failing feedback loop, reduce the case while preserving the symptom, and test competing explanations. |
| Deep | Concurrency, performance, intermittent failures, or interacting causes | Use targeted traces, profiling, controlled scheduling, bisect, or differential experiments as relevant; not a checklist of required tools. |
Establish and narrow the failure
Capture expected versus actual behavior and the triggering input, environment, version, and command or interaction. Preserve a baseline for comparison. Reuse existing evidence when it describes the same failure and conditions.
For Investigate/Deep, prefer a repeatable reproducer before changing production behavior. Minimize inputs, dependencies, or steps without removing the triggering conditions. For each useful hypothesis, predict an observation that would distinguish it from alternatives, vary one relevant factor, and compare the result with the prediction. Update or reject the hypothesis before stacking speculative patches. A passing unrelated test does not discriminate causes.
For intermittent or performance failures, record workload, scheduling/seed where controllable, repetitions, and failure rate or timing distribution. Compare equivalent before/after conditions; a single clean run does not establish resolution. Avoid unsafe production experiments; use an isolated reproduction or request the necessary access.