debugging-methodology
/debugging-methodology
Debugs failures by gathering evidence before proposing fixes, enforcing no fix without root-cause investigation. Use this skill when encountering bugs, test failures, unexpected behavior, intermittents, or works-locally-fails-in-CI, before changing code. Do not use when/for implementing a feature with no failure under investigation, or pure code-flow-analysis without a live failure.
- Author
- jagreehal ↗
- Repository
- jagreehal-claude-skills ↗
- Licence
- MIT
- Last repository change
- 30.07.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 30.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Debugs failures by gathering evidence before proposing fixes, enforcing no fix without root-cause investigation. Use this skill when encountering bugs, test failures, unexpected behavior, intermittents, or works-locally-fails-in-CI, before changing code. Do not use when/for implementing a feature with no failure under investigation, or pure code-flow-analysis without a live failure.
Original author description
Debugs failures by gathering evidence before proposing fixes, enforcing no fix without root-cause investigation. Use this skill when encountering bugs, test failures, unexpected behavior, intermittents, or works-locally-fails-in-CI, before changing code. Do not use when/for implementing a feature with no failure under investigation, or pure code-flow-analysis without a live failure.
How it works
- Critical rules
- Workflow
- Resources
- Validation
- Constraints
SKILL.md preview
--- name: debugging-methodology description: >- Debugs failures by gathering evidence before proposing fixes, enforcing no fix without root-cause investigation. Use this skill when encountering bugs, test failures, unexpected behavior, intermittents, or works-locally-fails-in-CI, before changing code. Do not use when/for implementing a feature with no failure under investigation, or pure code-flow-analysis without a live failure. version: 1.3.0 --- # Debugging Methodology ## Critical rules - `NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST`. No evidence → no fix proposal. - Measure; do not speculate. Instrumentation before hypothesis. - One change at a time. Never stack unverified fixes. - 3+ failed fixes → stop, question architecture, discuss before more attempts. - Red flags: "quick fix now", "try changing X", multi-change batches, "probably X", proposing solutions before data flow is traced. - Before instrumenting, map the path with `code-flow-analysis`. Before deep examples, read [references/protocol.md](references/protocol.md). ## Workflow 1. Document the exact symptom (error text, expected vs actual, inputs, environment). 2. Add instrumentation at decision points before forming any hypothesis. 3. For complex flows, use OpenTelemetry spans (or existing production traces). 4. Form a testable, evidence-based hypothesis that explains all symptoms. 5. Apply one change; retest; keep structured logging, remove debug-only noise. 6. For `Result` / workflow failures: log every `err()`, each step, and mock interactions. See protocol for patterns. ## Resources - [references/protocol.md](references/protocol.md) — instrumentation, Result/workflow debugging, decision tree, anti-patterns, rationalizations. Read before instrumenting or when stuck. ## Validation - [ ] Exact symptom captured - [ ] Instrumentation evidence explains the failure (not a guess) - [ ] Hypothesis confirmed with a single isolating change - [ ] Root cause identified (not only symptom location) - [ ] Regression test fails without fix, passes with it - [ ] Original failure no longer reproduces; suite/build green - [ ] Debug-level noise removed; structured logs/traces kept ## Constraints - Skip the full protocol only for trivial self-evident issues the compiler already names (typo, missing import). - Related: `code-flow-analysis`, `investigation-modes`, `result-types`, `fn-args-deps`, `verification-before-completion`, `confidence-levels`, `observability`.
Files in this package (2)
- SKILL.md 2 KB
- references/protocol.md 5 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · jagreehal/jagreehal-claude-skills | 100 | MIT |
| laurigates/claude-plugins | 100 | MIT |
| thoughtbot/skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version b56d436de4d8 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100systematic-debugging
Root cause investigation methodology for bugs and failures. Use when encountering test failures, unexpected behavior, or errors during research or implement phases. Find the cause before attempting fixes. - 100systematic-debugging
Root-cause-first debugging methodology for any bug, test failure, exception, or unexpected behavior — mandates investigation before proposing fixes. Use when something is broken, not working, crashing, or throwing errors; triggers: debug, error, bug, exception, stack trace, not working, crash. - 100systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - 100systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior. Requires root cause investigation before proposing fixes. - 90vc:debug
Debug systematically with root-cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, CI failures, or system investigation. - 90vc:debug
Debug systematically with root-cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, CI failures, or system investigation.