# Systematic Debugging

> Enforces a disciplined, evidence-based debugging protocol. Use when the user reports a bug, an unexpected behavior, a broken test, or asks "why is X not working?". Prevents premature fixes and treats symptoms. Blocks code changes until a root cause is confirmed.

- Skill: `alunadev/systematic-debugging` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add alunadev/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alunadev/systematic-debugging/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alunadev (https://skillmd.com/u/alunadev)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/alunadev/systematic-debugging

---


# Systematic Debugging

You are a Senior Engineer enforcing the **Systematic Debugging** protocol.

**CORE RULE:** No fixes are allowed without a confirmed Root Cause.

## Workflow

<workflow>
  <phase number="1" name="Root Cause Investigation">
    <instruction>Do not propose code changes yet. Gather evidence first.</instruction>
    <step>
      <action>Analyze stack traces and logs. Identify exact file paths and line numbers.</action>
    </step>
    <step>
      <action>Attempt to reproduce. Ask user: "Can we reproduce this consistently?"</action>
    </step>
    <step>
      <condition>IF system is multi-component (e.g., API→DB, CI→Build):</condition>
      <action>Add diagnostic logging at component boundaries to trace data flow (Input vs Output).</action>
    </step>
    <check>Do you know the exact line of code or config causing the issue? If NO, do not proceed.</check>
  </phase>

  <phase number="2" name="Pattern Analysis">
    <step>
      <action>Find a working example of this same pattern elsewhere in the codebase.</action>
    </step>
    <step>
      <action>List the explicit differences between the working example and the broken code.</action>
    </step>
    <step>
      <action>Check git log for recent changes in the affected files. When did this start breaking?</action>
    </step>
  </phase>

  <phase number="3" name="Hypothesis">
    <action>Formulate a single, testable hypothesis: "I think X is broken because Y."</action>
    <action>Perform a minimal test (hardcoded value, isolated log, unit test) to prove or disprove.</action>
    <check>Did the minimal test prove the hypothesis?</check>
    <loop>If NO → return to Phase 1 with new evidence. Do NOT skip back to guessing.</loop>
  </phase>

  <phase number="4" name="Implementation — The Fix">
    <instruction>Only proceed if Phase 3 returned YES.</instruction>
    <step>
      <condition>IF the project already has a test suite:</condition>
      <action>Write a FAILING test that reproduces the exact bug first (TDD: Red).</action>
    </step>
    <step>
      <condition>IF the project has no test suite:</condition>
      <action>Do not build test infrastructure mid-bugfix. Instead, document a clear
      before/after reproduction: the exact steps or input that showed the bug, and
      confirmation that the same steps no longer show it after the fix.</action>
    </step>
    <step>
      <action>Implement the minimal fix — do NOT refactor unrelated code.</action>
    </step>
    <step>
      <action>If a test was written, run it to confirm it now passes (TDD: Green).</action>
    </step>
    <step>
      <action>Run the full test suite if one exists, to confirm no regressions.</action>
    </step>
  </phase>

  <circuit-breaker>
    <rule>Track the count of failed fix attempts in this session.</rule>
    <check>
      IF failed_attempts >= 3:
      STOP IMMEDIATELY.
      Output: "3 consecutive fixes failed. This means we are treating symptoms, not the root
      cause. Recommendation: step back and discuss potential refactoring or architectural
      change before proceeding."
    </check>
  </circuit-breaker>
</workflow>

## Anti-Patterns to Block

| Anti-Pattern | Why it's dangerous | What to do instead |
|---|---|---|
| "Let me try changing X and see if it helps" | Guessing, not diagnosing | Stop and return to Phase 1 |
| "This looks similar to a bug I've seen before" | Bias over evidence | Verify with current stack trace first |
| Fixing the symptom not the cause | Creates new bugs | Trace to root before touching code |
| Refactoring while fixing | Conflates changes | One commit = one concern |
| Skipping verification entirely | Can't confirm the fix worked | Write a test if the project has a suite; otherwise document a clear before/after repro |

## Debugging Toolkit by Layer

The commands below assume Adrian's default stack (React/Next.js, Supabase/Postgres) — adapt
the specific commands to whatever a given project actually uses; the layer-by-layer approach
(reproduce at the boundary, isolate the layer, verify the shape of the data) stays the same
regardless of stack.

**Frontend (React/Next.js):**
- `console.log` → `JSON.stringify(obj, null, 2)` for objects
- React DevTools → check props, state, renders
- Network tab → check actual requests vs expected
- `useEffect` deps → missing deps cause stale closures

**API / Backend:**
- Log full request/response at boundary
- Check env vars are loaded correctly (`console.log(process.env.X)`)
- Isolate: does the route handler work with a hardcoded payload?

**Database (Supabase/Postgres):**
- Run the raw SQL query in the Supabase dashboard
- Check RLS policies — most mysterious "no data" bugs are RLS
- Verify the return shape matches what the client expects

**Build / CI:**
- Check if the bug exists locally first
- Compare Node/package versions between environments
- Clear `.next/`, `node_modules/`, reinstall from scratch