debugging-protocol

name	debugging-protocol
description	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.

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	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)