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 /quick-fix or /orchestrator 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:

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 @logging-and-observability-principles.md (structured logging for diagnostics)
• Testing Strategy @testing-strategy.md (regression test for the fix)