# Debugging Protocol

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

- Skill: `majiayu000/debugging-protocol` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/debugging-protocol`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/debugging-protocol/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/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`

### 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.