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 (e.g., when handing off to a
/bugfix or /workflow-solo workflow)
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 |
| Go |
Go (goroutines, pprof, Delve, race detector) |
| TypeScript |
TypeScript, Node.js, Vue, React (async debugging, memory leaks) |
| Python |
Python, Django, FastAPI (pdb, async, import resolution) |
| Rust |
Rust (cargo, rustc, tokio) |
| Java |
Java, Spring Boot (JVM tools, heap/thread dumps, connection pools) |
| C# |
C#, .NET, ASP.NET Core (dotnet diagnostics, EF Core, async deadlocks) |
| Swift |
Swift, SwiftUI, iOS/macOS (LLDB, Instruments, actors, retain cycles) |
| Flutter |
Flutter, Dart (DevTools, widget rebuilds, layout overflow, isolates) |
| C++ |
C++ (sanitizers, GDB/LLDB, Valgrind, iterator invalidation, data races) |
| Kotlin |
Kotlin (coroutine debugger, platform types, cancellation, JVM tools) |
| PHP |
PHP, Laravel (Xdebug, autoloading, sessions, white page of death) |
| Ruby |
Ruby, Rails (debug gem, Pry, Zeitwerk, N+1, monkey-patch detection) |
| Frontend |
Vue 3, React, browser, Vite (CSS, rendering, network) |
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 @error-handling-principles.md (proper error propagation)
- Logging and Observability Principles @.agents/skills/logging-implementation/SKILL.md (structured logging for diagnostics)
- Testing Strategy @testing-strategy.md (regression test for the fix)
1---2name: debugging-protocol-23description: Comprehensive protocol for validating root causes of software issues. Use when you need to systematically debug a complex bug, flaky test, or unknown system behavior by forming hypotheses and validating them with specific tasks.4---56# Debugging Protocol78## Overview910This 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.1112Use this skill to:131. Formalize a debugging session.142. Systematically eliminate potential root causes.153. Document findings for future reference or team communication.1617## Protocol Workflow1819To run a structured debugging session, follow these steps:2021### 1. Initialize the Session22Create a new debugging document using the provided template. This serves as the "source of truth" for the investigation.2324**Template location:** `assets/debugging-session-template.md`2526**Save to:** `docs/debugging/{issue-name}-{YYYY-MM-DD}-{HHmm}.md`27281. Create `docs/debugging/` if it doesn't exist292. Copy the template and fill in the issue details303. This makes the session accessible from other conversations and agents (e.g., when handing off to a `/bugfix` or `/workflow-solo` workflow)3132### 2. Define the Problem33Clearly articulate the **System Context** and **Problem Statement**.34* **Symptom**: What is the observable behavior? How does it differ from expected behavior?35* **Scope**: Which components are involved?3637### 3. Formulate Hypotheses38List distinct, testable hypotheses.39* Avoid vague guesses.40* Differentiate between layers (e.g., "Frontend Hypothesis" vs "Backend Hypothesis").41* Example: "Race condition in UI state update" vs "Database schema misconfiguration".4243### 4. Design Validation Tasks44For each hypothesis, design a specific validation task.45* **Objective**: What are you trying to prove or disprove?46* **Steps**: Precise, reproducible actions.47* **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).48* **Success Criteria**: Explicitly state what output confirms the hypothesis.4950### 5. Execute and Document51Run the tasks in order. For each task, record:52* **Status**: ✅ VALIDATED, ❌ FAILED, or ⚠️ INCONCLUSIVE.53* **Findings**: Key observations and raw evidence (logs, screenshots).54* **Conclusion**: Does this support or refute the hypothesis?5556### 6. Determine Root Cause57Synthesize the findings into a **Root Cause Analysis**.58* Identify the Primary Root Cause.59* Assign a Confidence Level.60* Propose specific fixes.6162## Best Practices6364* **Be Specific**: Don't just say "check the logs." Say "grep for 'Error 500' in `/var/log/nginx/access.log`".65* **Isolate Variables**: Change one thing at a time.66* **Validate Assumptions**: Verify configuration and versions first (e.g., "Task 1: Validate Current Schema").67* **Preserve Evidence**: Keep the specific trace IDs, log timestamps, or reproduction scripts.6869## Language-Specific Modules7071The `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.7273**Convention:** Each module is a standalone markdown file at `languages/{language}.md`.7475**How to use:**761. Identify the primary language of the codebase being debugged772. Load the corresponding module from `languages/`783. Integrate its toolchain, hypothesis categories, and validation tasks into your debugging session7980**Available modules:**8182| Module | Languages/Runtimes |83|---|---|84| [Go](languages/go.md) | Go (goroutines, pprof, Delve, race detector) |85| [TypeScript](languages/typescript.md) | TypeScript, Node.js, Vue, React (async debugging, memory leaks) |86| [Python](languages/python.md) | Python, Django, FastAPI (pdb, async, import resolution) |87| [Rust](languages/rust.md) | Rust (cargo, rustc, tokio) |88| [Java](languages/java.md) | Java, Spring Boot (JVM tools, heap/thread dumps, connection pools) |89| [C#](languages/csharp.md) | C#, .NET, ASP.NET Core (dotnet diagnostics, EF Core, async deadlocks) |90| [Swift](languages/swift.md) | Swift, SwiftUI, iOS/macOS (LLDB, Instruments, actors, retain cycles) |91| [Flutter](languages/flutter.md) | Flutter, Dart (DevTools, widget rebuilds, layout overflow, isolates) |92| [C++](languages/cpp.md) | C++ (sanitizers, GDB/LLDB, Valgrind, iterator invalidation, data races) |93| [Kotlin](languages/kotlin.md) | Kotlin (coroutine debugger, platform types, cancellation, JVM tools) |94| [PHP](languages/php.md) | PHP, Laravel (Xdebug, autoloading, sessions, white page of death) |95| [Ruby](languages/ruby.md) | Ruby, Rails (debug gem, Pry, Zeitwerk, N+1, monkey-patch detection) |96| [Frontend](languages/frontend.md) | Vue 3, React, browser, Vite (CSS, rendering, network) |9798> **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.99100## Rule Compliance101When debugging, verify against:102- Error Handling Principles @error-handling-principles.md (proper error propagation)103- Logging and Observability Principles @.agents/skills/logging-implementation/SKILL.md (structured logging for diagnostics)104- Testing Strategy @testing-strategy.md (regression test for the fix)