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.

Aller à l'installation

Dépôt: fabioc-aloha/ChessCoach
Dernière activité de la source: 5 mai 2026 à 20:58
Langue détectée de SKILL.md: anglais
Étoiles: 1
Forks: 0

Options d'installation

Le prompt qui vérifie d'abord la source est sélectionné par défaut. Vous pouvez passer à une commande directe ou télécharger une copie locale.

Vérifiez les fichiers source

Lisez SKILL.md et les fichiers associés affichés par SkillsMP avant de décider de l'installer.

Retour à la recherche Retour à l’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