debugging-protocol

# 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: 1. Formalize a debugging session. 2. Systematically eliminate potential root causes. 3. 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` 1. Create `docs/debugging/` if it doesn't exist 2. Copy the template and fill in the issue details 3. 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:** 1. Identify the primary language of the codebase being debugged 2. Load the corresponding module from `languages/` 3. Integrate its toolchain, hypothesis categories, and validation tasks into your debugging session **Available modules:** | Module | Languages/Runtimes | |---|---| | [Go](languages/go.md) | Go (goroutines, pprof, Delve, race detector) | | [TypeScript](languages/typescript.md) | TypeScript, Node.js, Vue, React (async debugging, memory leaks) | | [Python](languages/python.md) | Python, Django, FastAPI (pdb, async, import resolution) | | [Rust](languages/rust.md) | Rust (cargo, rustc, tokio) | | [Java](languages/java.md) | Java, Spring Boot (JVM tools, heap/thread dumps, connection pools) | | [C#](languages/csharp.md) | C#, .NET, ASP.NET Core (dotnet diagnostics, EF Core, async deadlocks) | | [Swift](languages/swift.md) | Swift, SwiftUI, iOS/macOS (LLDB, Instruments, actors, retain cycles) | | [Flutter](languages/flutter.md) | Flutter, Dart (DevTools, widget rebuilds, layout overflow, isolates) | | [C++](languages/cpp.md) | C++ (sanitizers, GDB/LLDB, Valgrind, iterator invalidation, data races) | | [Kotlin](languages/kotlin.md) | Kotlin (coroutine debugger, platform types, cancellation, JVM tools) | | [PHP](languages/php.md) | PHP, Laravel (Xdebug, autoloading, sessions, white page of death) | | [Ruby](languages/ruby.md) | Ruby, Rails (debug gem, Pry, Zeitwerk, N+1, monkey-patch detection) | | [Frontend](languages/frontend.md) | 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)