# Debug Issue

> A strict, scientific debugging protocol (The "Iron Law"). No fixes allowed without root cause investigation.

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

---


# Systematic Debugging (The Iron Law)

**Core Principle**: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
Symptom patching is failure.

## Inputs
*   **Issue Description**: What is broken?
*   **Observed Behavior**: What is happening instead?
*   **Stack Trace/Logs**: (Optional) Error output.

## Tooling Strategy
*   Use `grep_search` to find error messages in code.
*   Use `view_file` to inspect logic.
*   Use `run_command` to run reproduction scripts.

## Workflow

### 1. Isolation & Symptom Analysis
*   **Deviation**: Clearly define `Expected` vs `Observed`.
*   **Error Messages**: Read the ENTIRE stack trace. Do not skim.
*   **Environment**: Dev vs Prod? Recent changes?

### 2. Reproduction (The MRE)
*   **Steps**: List the exact steps to fail.
*   **Determinism**: Is it 100% consistent or flaky?
*   **MRE**: Create a Minimal Reproducible Example (strip away everything else).

### 3. Root Cause Investigation (The "Why")
*   **Trace Data Flow**: Follow the bad value backwards. Where did it originate?
*   **Instrumentation**: "Measure, Don't Guess." Add logs at boundaries.
*   **Hypothesis**: Formulate: "I think X fails because Y."

### 4. Implementation (The Fix)
*   **The 3-Strike Rule**: If you have tried 3 fixes and they failed, STOP.
    *   *Observation*: You likely have an architecture problem, not a bug.
    *   *Action*: Question the fundamental pattern.
*   **Single Change**: Apply ONE fix. Test it.

### 5. Verification & Regression
*   **Verify**: Does the MRE pass now?
*   **Regression**: Did anything else break? Run `enhance_ui` or standard tests.

## Rationalization Busting
If you catch yourself saying these, STOP and return to Step 1:
*   "I'll just try this quickly..."
*   "It's probably X..."
*   "I don't know why this works but it does."

## Advanced Debugging Strategies
- **Binary Search**: If a long script or a large commit history fails, cut it in half. Test which half fails. Repeat.
- **Targeted Instrumentation**: Don't just `console.log("here")`. Log state: `console.log({ user: req.user, authHeader: req.headers.authorization })`.
- **Form Hypotheses & Controlled Experiments**: Before changing code, write down what you think is wrong and what single change will prove it.
- **Rubber Ducking / Write it Down**: Explain the data flow step-by-step out loud (or in the prompt). The assumption gap often reveals itself.