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.

설치로 이동

저장소: fabioc-aloha/ChessCoach
최근 소스 활동: 2026년 5월 5일 20:58
감지된 SKILL.md 언어: 영어
스타: 1
포크: 0

설치 방법

기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.

소스 파일 검토

설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.

검색으로 돌아가기 설치로 돌아가기

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