AgentSkillsCN

debugging-protocol

全面的协议，用于验证软件问题的根本原因。适用于需要系统性地调试复杂Bug、不稳定测试或未知系统行为时，通过形成假设并用具体任务验证它们。

SKILL.md
--- frontmatter
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

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.