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?