# Speckit.debug

> Systematic Debugger - Diagnose problems, find individual root causes, and recommend fix plans.

- Skill: `wedabro/speckit-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wedabro/speckit-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wedabro/speckit-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wedabro (https://skillmd.com/u/wedabro)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wedabro/speckit-debug

---


## 🎯 Mission
Use scientific methodology to find the root cause of bugs without disturbing the main context of feature development.

## 📋 Protocol

### Phase 1: Symptom Gathering (Symptom collection)
Before starting to code, make it clear:
- **Expected behavior**: What is the expected result?
- **Actual behavior**: What is the actual result that is happening?
- **Error messages**: Specific error logs (paste directly).
- **Reproduction**: Specific steps to reproduce the error (required).

### Phase 2: Isolation & Hypothesis (Isolation & Hypothesis)
- Create file `.agents/debug/[issue-slug].md` to save the investigation log.
- Hypotheses: "Maybe the error lies in function X because of Y".
- Use the commands `grep` , `log` to verify the hypothesis.

### Phase 3: Root Cause Found (Determine the cause)
- Only end the investigation when the specific line of code/configuration causing the error is found.
- Explain **WHY** it fails instead of just saying **IT IS ERROR**.

### Phase 4: Fix Proposal (Proposal to fix errors)
- Do not correct errors directly in this skill.
- The output is either a proposed fix or the creation of a `gap_plan` for `speckit.implement` to execute.

## 🚫 Guard Rails
- NO guessing. Every conclusion must have evidence from logs or code.
- DO NOT further damage existing code during debugging (use Read-only tools mainly).
- MUST create a debug log file to save traces.