A Claude Code skill for hypothesis-driven debugging — reproduce, isolate, hypothesize, test, fix, document. Find the root cause, not a workaround.
This is the companion to vibe-engineer-skills. That repo states the principle: hypothesis before help. This repo is the procedure that enacts it when you actually sit down to debug.
"Fix this" is the most expensive prompt in software. Handed a vague symptom, an AI guesses at the most plausible cause, writes a change that compiles and passes a test, and hands back a green build. The build is green because the symptom is gone, not because the bug is gone.
The result is a workaround that hides the real failure:
- A try/catch that swallows the error instead of preventing it.
- A defensive null check that masks an upstream contract violation.
- A renamed variable that still holds the wrong state.
- A mocked dependency that was the thing actually broken.
Each one passes tests. Each one propagates the bug to the next caller of the same broken code. The fix that hides a bug is worse than no fix, because now the bug is invisible.
The cure is to refuse to write a fix until the cause is known. That is what this protocol enforces.
| Phase | Does | Output |
|---|---|---|
| 1. Reproduce | Make the failure happen on demand | A repeatable trigger and the exact error |
| 2. Isolate | Narrow scope via recent diffs and a minimal case | "This input to this function fails" |
| 3. Hypothesize | Write a ranked hypothesis table before touching code | Ranked causes, each with a test |
| 4. Test | Work the table top-down, confirm or refute each row | A confirmed root cause |
| 5. Fix | Smallest change that addresses the cause, plus a regression test | A verified fix, not a workaround |
| 6. Document | Record root cause, fix, and prevention | A lesson, not just a closed ticket |
The load-bearing step is Phase 3. The ranked hypothesis table is what turns an AI's job from inventing a cause into testing yours. Full content: CLAUDE.md. Worked walkthroughs: EXAMPLES.md.
Drop CLAUDE.md at the root of your repository. Claude Code picks it up automatically. Merge with existing project instructions if any.
curl -o CLAUDE.md https://raw.githubusercontent.com/HermeticOrmus/hypothesis-debugging-skills/main/CLAUDE.mdThe same content is packaged as a skill under skills/hypothesis-debugging/ for ~/.claude/skills/. See the SKILL.md inside for installation.
Save the protocol as a slash command so you can invoke it on demand with the symptom as an argument.
curl -o ~/.claude/commands/debug.md https://raw.githubusercontent.com/HermeticOrmus/hypothesis-debugging-skills/main/CLAUDE.mdThen run /debug <error-or-symptom> in any Claude Code session to start the loop against a specific failure.
See CURSOR.md for the Cursor-rule equivalent at .cursor/rules/hypothesis-debugging.mdc. The rule is situational (alwaysApply: false) so it activates when you are debugging rather than on every edit.
If your tool reads a single instruction file at the project root, copy CLAUDE.md to whatever name your tool expects (AGENTS.md, INSTRUCTIONS.md, etc.).
vibe-engineer-skills: the principle this repo enacts, hypothesis before help, plus the four other Vibe Engineer principles for directing AI codegen.andrej-karpathy-skills: how the AI should behave while you run this loop, think before coding, simplicity first, surgical changes, goal-driven execution.
PRs welcome, especially for additional worked walkthroughs in EXAMPLES.md, translations of the README, and adaptations of CURSOR.md for other AI coding tools (Windsurf, Cline, Aider, Continue, etc.).
MIT. Use it, fork it, merge it into your own CLAUDE.md.
This repository is part of a growing family of open-source toolkits for Claude Code.
- LibreUIUX-Claude-Code — UI/UX development (152 agents, 70 plugins, 76 commands, 74 skills)
- LibreArch-Claude-Code — Software architecture and system design
- LibreCopy-Claude-Code — Technical writing and documentation engineering
- LibreDevOps-Claude-Code — DevOps engineering and infrastructure automation
- LibreEmbed-Claude-Code — Embedded systems, firmware, and IoT development
- LibreFinTech-Claude-Code — Financial technology development
- LibreGEO-Claude-Code — AI-search optimization (ChatGPT, Perplexity, Gemini, Google AI Overviews)
- LibreGameDev-Claude-Code — Game development across Godot, Unity, Unreal
- LibreMLOps-Claude-Code — ML engineering and AI operations
- LibreMobileDev-Claude-Code — Mobile app development (Flutter, React Native, native iOS, native Android)
- LibreSecOps-Claude-Code — Security operations
- LibreSessionFlow-Claude-Code — Session lifecycle: handoff, pickup, absorb, explore, close
- vibe-engineer-skills — Direct AI codegen well: hypothesis before help, scoped prompts, validate before accepting
- markdown-discipline-skills — Strip AI-slop from markdown (no em dashes, no marketing fluff)
- shell-safety-skills —
set -euo pipefaildiscipline plus 15 failure-mode examples - commit-standard-skills — Ormus Commit Standard v1.0 plus commit-msg hook and commitlint
- unwoke-skills — Strip AI theater (ten sins to eliminate, symmetric engagement)
- python-conventions-skills — Modern Python 3.11+ (types, pathlib, async, ruff, mypy, uv)
- typescript-conventions-skills — TypeScript strict mode, discriminated unions, Result types
- hermetic-laws-skills — Seven Hermetic Principles applied to engineering
- riper-workflow-skills — Research / Innovate / Plan / Execute / Review systematic dev
- six-day-cycle-skills — Sustainable shipping cadence with mandatory rest
- token-optimization-skills — Claude Code token and context optimization
- osint-skills — OSINT research methodology (multi-wave investigative spiral)
- calcinate-skills — Stage 1 of the Magnum Opus (burn project bloat)
- claude-md-overhaul-skills — Audit CLAUDE.md and MEMORY.md against caps
- session-handoff-skills — Session handoff and pickup discipline
- naming-skills — Product naming methodology (mine the brand's vocabulary)
- magnum-opus-skills — Seven-stage alchemy applied to project transformation
- mem-search-skills — Search claude-mem cross-session memory: search, filter, fetch
- vibe-proof-skills — Security hardening for vibe-coded full-stack apps
- tdd-skills — Test-driven development (Red-Green-Refactor) for JS/TS and Python
- mars-skills — Production-readiness audit: the five mortal sins of vibe-coded MVPs
- git-workflow-skills — Clean git workflow: branch, atomic commits, reviewable PRs
- code-review-skills — Domain-aware code review: classify the code, then focus
- code-comprehension-skills — Understand an unfamiliar codebase fast
- dx-audit-skills — Audit developer experience: docs, onboarding, tooling friction
- setup-env-skills — Set up a project's development environment
- automate-skills — Turn repetitive tasks into reliable automation scripts
- quick-fix-skills — Fast troubleshooting for common issues
- prime-context-skills — Prime project context at the start of a session
- auto-docs-skills — Generate and maintain project documentation
- learning-skills — Learn any technology: roadmaps, explanations, practice, cheatsheets, comparisons
- linux-sysadmin-skills — Linux system administration: security, performance, diagnostics, monitoring, maintenance
- andrej-karpathy-skills — the canonical single-file CLAUDE.md pattern (fork of jiayuan_jy's original)
Star the family, not just one — that's how the suite stays coherent.