// Use when encountering any bug, test failure, or unexpected behavior. Four-phase root cause investigation. No fixes without understanding the problem first.
| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior. Four-phase root cause investigation. No fixes without understanding the problem first. |
| version | 1.0.0 |
| author | Aixlarity (adapted from Hermes Agent / obra/superpowers) |
| license | Apache-2.0 |
| metadata | {"aixlarity":{"tags":["debugging","troubleshooting","root-cause","investigation"],"related_skills":["tdd","code-review"],"origin":"Hermes Agent systematic-debugging skill"}} |
Random fixes waste time and create new bugs. Always find the root cause before attempting fixes.
Before anything else, reproduce the failure:
# Run the failing test or trigger the bug
cargo test <failing_test_name>
Record: exact error message, stack trace, which input triggers it.
Narrow the scope:
dbg!() or eprintln!() at suspected boundaries.git bisect if needed.Before writing any fix:
If you cannot do all three, you have not finished Phase 3.
Cargo.toml first.Use when evaluating whether a proposed change fits the existing architecture. Prevents layer violations, dependency cycles, and accidental coupling.
Use when the user wants a code review instead of implementation. Prioritizes correctness bugs, behavioral regressions, missing tests, and risky assumptions.
Use when reviewing documentation for accuracy, completeness, and alignment with source code. Catches doc-code drift before it confuses readers.
Use when making changes that should be committed. Enforces atomic commits, meaningful messages, and clean history.
Use when investigating slow execution, high memory usage, or excessive token consumption. Systematic measurement before optimization.
Use when improving code structure without changing behavior. Ensures each refactoring step preserves all existing tests.