Skill

systematic-debugging

Hypothesis-driven debugging loop. Forces explicit hypothesis formation before any fix attempt. Prevents guess-and-check debugging. Use when investigating or fixing an observed bug, failing test, runtime error, broken behavior, or performance regression.

npx claudepluginhub iadr-dev/colab --plugin oh-my-colab

Tool Access

This skill is limited to using the following tools:

Read Write Bash

Preview

Never guess-and-check. Always hypothesize first, then design a test for the hypothesis.

Supporting Assets

references/debug-hypotheses.mdreferences/feedback-loops.md

SKILL.md

Similar Skills

using-superpowers

178.4k

Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.

3 files

superpowers

Stats

Stars1

Forks0

Last CommitApr 29, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

Systematic Debugging

Never guess-and-check. Always hypothesize first, then design a test for the hypothesis.

Step 1: Build the Feedback Loop

Create a fast, deterministic, agent-runnable pass/fail signal for the bug. Prefer, in order: failing test, curl/CLI script, browser script, replayed trace, throwaway harness, or stress loop for flakes.

If you cannot build a loop, stop and report what artifact or environment access is missing. Do not patch from code reading alone.

Step 2: Reproduce

Run the loop and confirm it matches the user's bug.

Document: exact inputs → expected output → actual output
For flakes: raise the reproduction rate until the signal is useful
If the loop finds a different bug, fix the loop first

Step 3: Hypothesize

Write 3 hypotheses, ordered by likelihood (most likely first):

H1: IF [condition] THEN [expected] BUT we see [actual]
    Evidence for: [why this is likely]
    Evidence against: [why this might be wrong]

H2: [same format]
H3: [same format]

Step 4: Test Most Likely Hypothesis

Design a targeted test that confirms OR rules out H1. A good test is:

Targeted: tests H1 specifically, not the whole system
Binary: clearly confirms OR rules out
Fast: no full rebuild needed

Use targeted instrumentation only. Tag temporary logs with a unique prefix like [DEBUG-a4f2] so cleanup is mechanical.

Step 5: Record and Iterate

H1: [confirmed | ruled out]
Evidence: [what you observed]

If confirmed: root cause found → go to Step 6. If ruled out: move to H2. Repeat. If all 3 ruled out: write 3 new hypotheses based on what you learned.

Step 6: Fix with Confidence

Write a regression test that captures the bug (RED)
Fix the root cause (not the symptom)
Run regression test (GREEN)
Re-run the original feedback loop
Remove all tagged debug instrumentation
Run full test suite — no regressions

Common Mistake: Fixing the Symptom

Symptom: API returns 500 Root cause: DB connection pool exhausted Wrong fix: retry API call → symptom addressed, root cause remains

Always trace back to WHY, not just WHAT.

See references/debug-hypotheses.md for hypothesis templates by error type. See references/feedback-loops.md for ways to construct a reliable debug loop.