hypothesis-driven-debugging

Investigate build failures, test errors, runtime crashes, or unexpected behavior through systematic minimal reproduction, multi-hypothesis testing, and evidence-based verification. Use when asked to "debug", "investigate a failure", "find root cause", "troubleshoot", "fix a failing test", or "diagnose an issue". Always re-run builds and tests after changes.

Jump to install

Repository: fabioc-aloha/ChessCoach
Last source activity: May 5, 2026 at 20:58
Detected SKILL.md language: English
Stars: 1
Forks: 0

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

type	skill
lifecycle	stable
inheritance	inheritable
name	hypothesis-driven-debugging
description	Investigate build failures, test errors, runtime crashes, or unexpected behavior through systematic minimal reproduction, multi-hypothesis testing, and evidence-based verification. Use when asked to "debug", "investigate a failure", "find root cause", "troubleshoot", "fix a failing test", or "diagnose an issue". Always re-run builds and tests after changes.
applyTo	*/debug,/bug,/error,/fix*
tier	standard
currency	2026-04-22T00:00:00.000Z

Hypothesis-Driven Debugging

Apply the scientific method to debugging: observe, hypothesize, experiment, conclude. No trial-and-error.

When to Use

Test failures, build errors, runtime crashes, performance regressions
Intermittent or environment-specific failures
Any situation where the root cause is not immediately obvious

Core Principles

Always start with a minimal reproduction
Form at least 3 competing hypotheses
Verify hypotheses one at a time with evidence
Re-run the project's build and test commands after every change

Process

Step 1: Observe and Reproduce

Create the smallest possible reproduction:

Capture the failure: exact error message, stack trace, unexpected output
Detect the environment: discover the project's runtime, build system, and config by scanning for build/dependency files in the repo
Determine: deterministic or intermittent?
Isolate: remove unrelated code and dependencies until you have the minimal failing case

Document:

File/Component: [path]
Command: [detect from project's build/test config]
Expected vs Actual: [describe]
Deterministic?: [yes/no — if no, rate: X/10]

Step 2: Form 3+ Hypotheses

Always form at least 3 competing hypotheses to prevent anchoring.

For each, record: Theory | Supporting evidence | Verification plan | Fix approach if confirmed

Generation tips:

Consider different layers: input validation, business logic, infrastructure, configuration
What changed recently: code, dependencies, environment, data?
Timing/ordering issues: race conditions, initialization order, async behavior?
Check assumptions: are inputs matching expected types/ranges/formats?

Step 3: Verify Systematically

Test hypotheses one at a time, starting with the most likely or easiest to verify:

Technique	When to Use
Code instrumentation	Add temporary debug output at key decision points

# Hypothesis Investigation: [Issue Summary]
## Minimal Reproduction — [commands/code]
## Hypotheses
### H1: [Title] — [✅/❌/⚠️] — Theory | Verification | Result
### H2: ...
### H3: ...
## Root Cause — [confirmed cause]
## Fix Applied — [what changed and why]
## Lessons Learned — [patterns to watch for]

File/Component: src/middleware/auth.ts
Command: npm test -- --grep "auth middleware"
Expected: 200 OK for valid JWT    Actual: 401 Unauthorized
Deterministic?: yes

#	Theory	Verification Plan
H1	JWT secret mismatch between sign and verify	Compare env vars in test setup vs app config
H2	Token expiry validation uses wrong clock	Log `iat`, `exp`, and `Date.now()` in middleware
H3	Header parsing drops the "Bearer " prefix	Add debug log of raw `Authorization` header

// Before
if (!authHeader.startsWith("Bearer ")) return res.sendStatus(401);
// After
if (!authHeader.toLowerCase().startsWith("bearer ")) return res.sendStatus(401);

$ npm test -- --grep "auth middleware"
✓ returns 200 for valid token (lowercase bearer)
✓ returns 200 for valid token (uppercase Bearer)
✓ returns 401 for missing token
All 3 tests passed.

Scenario	Action
Cannot reproduce locally	Document environment differences; check CI logs and deployment config
Build/test commands not found	Scan for build files; ask user if none detected
All hypotheses denied	Re-examine assumptions, widen scope, form 3 new hypotheses
Fix introduces regressions	Revert immediately — root cause analysis was incomplete

❌ Don't	✅ Do Instead
Jump to a fix without understanding root cause	Form and test hypotheses first
Form only one hypothesis	Always consider at least 3
Make multiple changes at once	One change at a time, verify each
Skip minimal reproduction	Invest upfront to isolate the issue
Claim "fixed" without evidence	Re-run build and tests; record results
Leave debug instrumentation in code	Clean up before committing

> debug why the auth middleware returns 401 for valid tokens
> investigate the flaky test in UserService.test.ts
> find root cause of the memory leak in the worker process
> troubleshoot why the build fails only on CI but works locally