| name | debugging-protocol |
| description | Execute a structured debugging protocol to systematically identify root causes of software issues. Use when diagnosing complex bugs, flaky tests, intermittent failures, or unknown system behavior by forming hypotheses and validating them through specific, reproducible tasks. |
Debugging Protocol
Overview
This skill provides a rigorous framework for debugging complex software issues. It moves beyond ad-hoc troubleshooting to a structured process of hypothesis generation and validation.
Use this skill to:
- Formalize a debugging session.
- Systematically eliminate potential root causes.
- Document findings for future reference or team communication.
Protocol Workflow
To run a structured debugging session, follow these steps:
1. Initialize the Session
Create a new debugging document using the provided template. This serves as the "source of truth" for the investigation.
Template location: assets/debugging-session-template.md
Save to: docs/debugging/{issue-name}-{YYYY-MM-DD}-{HHmm}.md
- Create
docs/debugging/ if it doesn't exist
- Copy the template and fill in the issue details
- This makes the session accessible from other conversations and agents
2. Define the Problem
Clearly articulate the System Context and Problem Statement.
- Symptom: What is the observable behavior? How does it differ from expected behavior?
- Scope: Which components are involved?
3. Formulate Hypotheses
List distinct, testable hypotheses.
- Avoid vague guesses.
- Differentiate between layers (e.g., "Frontend Hypothesis" vs "Backend Hypothesis").
- Example: "Race condition in UI state update" vs "Database schema misconfiguration".
4. Design Validation Tasks
For each hypothesis, design a specific validation task.
- Objective: What are you trying to prove or disprove?
- Steps: Precise, reproducible actions.
- Code Pattern: Provide the exact code or command to run (e.g., a specific SQL query, a Python script using the client library, a
curl command).
- Success Criteria: Explicitly state what output confirms the hypothesis.
5. Execute and Document
Run the tasks in order. For each task, record:
- Status: ✅ VALIDATED, ❌ FAILED, or ⚠️ INCONCLUSIVE.
- Findings: Key observations and raw evidence (logs, screenshots).
- Conclusion: Does this support or refute the hypothesis?
6. Determine Root Cause
Synthesize the findings into a Root Cause Analysis.
- Identify the Primary Root Cause.
- Assign a Confidence Level.
- Propose specific fixes.
Best Practices
- Be Specific: Don't just say "check the logs." Say "grep for 'Error 500' in
/var/log/nginx/access.log".
- Isolate Variables: Change one thing at a time.
- Validate Assumptions: Verify configuration and versions first (e.g., "Task 1: Validate Current Schema").
- Preserve Evidence: Keep the specific trace IDs, log timestamps, or reproduction scripts.
Language-Specific Modules
The languages/ directory contains modular, language-specific debugging guides. When debugging a project, load the relevant language module to augment this protocol with language-specific tools, hypothesis categories, and validation strategies.
Convention: Each module is a standalone markdown file at languages/{language}.md.
How to use:
- Identify the primary language of the codebase being debugged
- Load the corresponding module from
languages/
- Integrate its toolchain, hypothesis categories, and validation tasks into your debugging session
Available modules:
| Module | Languages/Runtimes |
|---|
| Rust | Rust (cargo, rustc, tokio) |
| Frontend | Vue 3, React, browser, Vite |
Contributing new modules: To add support for a new language, create languages/{language}.md following the structure of existing modules. Each module should include: a toolchain reference table, language-specific hypothesis categories, validation task patterns, and an error-type-to-first-action quick reference.
Rule Compliance
When debugging, verify against:
- Error Handling Principles @.claude/rules/error-handling-principles.md (proper error propagation)
- Logging and Observability Principles — load the
logging-and-observability-principles skill (structured logging for diagnostics)
- Testing Strategy @.claude/rules/testing-strategy.md (regression test for the fix)
