debug

name	debug
description	Use when code behaves differently from expectations — 'why does this happen', 'find the bug', 'follow the callstack', symptom reports even without the word debugging. Blackbox methodology: AS-IS/TO-BE confirmation, callstack tracing recorded in a CWD-relative trace file, red-green fix.

stv:debug: 'Blackbox Debugging'

A debugging methodology that records everything like an airplane black box while hunting for the root cause. Core constraint: An unexplored branch is an unexamined branch.

---

1. Problem Definition — AS-IS / TO-BE Confirmation

Before starting, always confirm with the user:

• Forward: "Did X, got Y → doing X should produce Z"
• Reverse: "Got Y → should have been Z"

The gap between AS-IS and TO-BE is the bug. Do not start debugging without confirmation.

2. Tracing — Follow the Callstack While Recording in trace.md

Create a debugging log file under the current working directory (NOT the home directory):

./.claude/stv/debugging/{issueID}-{YYYYMMDDhhmm}/trace.md

The ./ prefix is intentional — every stv artifact (spec.md, trace.md, debugging trace) lives under the active CWD so multi-tenant / multi-session agents stay isolated. The tradeoff is that the same {issueID} started in different working trees yields separate trace dirs; that is the intended isolation model, not a bug.

Path guards (all three are hard rules):

• NEVER write to the home-level .claude. The trace dir is always the CWD-relative ./.claude/stv/…; a trace path that resolves to the HOME-level .claude (~/.claude/…, $HOME/.claude/…, /Users/<user>/.claude/…, /home/<user>/.claude/…) is a bug in the run, not a fallback — older versions of this skill polluted ~/.claude/stv/debugging/ exactly this way. (A checkout that happens to live under /Users/<user>/project/ is fine — the guard is about the home .claude, not the home prefix.) If the CWD is somehow unwritable, stop and surface that instead of falling back to home.
• Keep trace dirs out of commits (gitignore). When the CWD is a git checkout, ./.claude/stv/ must be git-ignored before the first trace write: if ! git check-ignore -q .claude/stv; then echo '.claude/stv/' >> .git/info/exclude; fi. Default to .git/info/exclude (local scratch policy, no tracked-file mutation); append to the repo's .gitignore instead only when the project explicitly wants the ignore rule shared. A debugging trace that leaks into a commit is scratch entering the tree.
• Trace dirs are disposable evidence — cleanup is part of closing. When debugging concludes, fold the durable findings (root cause, the red→green test, the fix rationale) into the issue/PR/spec that owns the bug; the trace dir itself has served its purpose. Leave it in place for session-scoped CWDs (the sandbox is thrown away), and delete or trash it in long-lived checkouts once its content has been folded in. The lifecycle rule: durable knowledge moves out, the scratch dir never outlives the investigation.

Follow the callstack one step at a time from the entry point, recording in this file.

Recording Rules

• At each step, specify the actual filename:line number.
• At conditional branches, record which condition leads where.
• API calls to other services, DB queries, and message queue publications are part of the callstack. When crossing service boundaries, follow into that service's code and continue tracing.
• Do not assume. Only write what you have directly read and verified in the code.

Exploration Strategy: Heuristic → Exhaustive

1. Phase 1 — Heuristic: Quickly check the top-3 most likely hypotheses first.
2. Phase 2 — Exhaustive: If top-3 yields nothing, draw the callstack graph in trace.md and exhaustively explore every branch by actually writing each one down.

3. Verification — Red-Green Cycle

Once a hypothesis is identified:

1. Write a test that reproduces the bug first (Red — confirm the test fails)
2. Apply the fix
3. Confirm the test passes (Green)
4. Confirm existing tests are not broken (regression prevention)
5. Feed the root cause back to the vertical trace — if the bug lives in a feature that has docs/{feature}/trace.md, update that trace via the Delta Protocol (a wrong transformation rule → MODIFIED; a missing error path → ADDED) so trace and code stay synchronized. The debugging trace dir is scratch; the vertical trace is the contract.

---

4. Systematic Debugging Principles

The above blackbox method covers how to trace. These principles cover how to think while debugging.

4a. Reproduce First

• 재현 없이 수정하지 마라. 재현할 수 없으면 계측(instrumentation)부터 추가하라.
• 재현 가능하면 → 가설 수립. 재현 불가면 → 로그/계측 추가 후 재실행.

4b. Single Hypothesis per Iteration

• 한 번에 하나의 가설만 검증한다.
• 여러 수정을 동시에 하면 뭐가 효과인지 모른다.
• 가설이 틀리면 원복하고 새 가설을 세워라.

4c. Root-Cause Tracing

• 증상이 나타난 곳이 아니라 원인이 시작된 곳을 찾아라.
• 콜스택을 역방향으로 추적: "이 값은 어디서 왔나?" → "그걸 누가 넘겼나?" → 원점까지.
• 증상 지점에서 수정하면 다른 경로로 같은 버그가 재발한다.

4d. Condition-Based Waiting (Flaky Test 대응)

• setTimeout/sleep 대신 조건 폴링을 써라.
• 패턴: waitFor(() => condition, timeout) — 10ms 간격 폴링 + 타임아웃 필수.
• 타이밍 테스트가 아닌데 임의 딜레이를 쓰면 flaky의 원흉.

4e. Defense-in-Depth (버그 수정 후)

• 버그를 고친 뒤, 데이터가 지나는 모든 레이어에 검증을 추가하라.
• 4개 레이어: Entry Point → Business Logic → Environment Guard → Debug Instrumentation.
• 한 곳만 막으면 다른 코드 경로로 우회된다. 구조적으로 불가능하게 만들어라.

4f. 3회 실패 시 아키텍처 의심

• 3번 연속 수정이 실패하면 멈추고 구조를 의심하라.
• 각 수정이 다른 곳에서 새 문제를 만들면, 그건 버그가 아니라 설계 문제다.
• 더 고치지 말고 유저/Oracle과 상의하라.

---

trace.md Example

# Bug Trace: ISSUE-1234 — Soccer team names appear in results

## AS-IS: Movie search results include soccer team names mixed in
## TO-BE: Movie search results should only contain movies

## Phase 1: Heuristic Top-3

### Hypothesis 1: Search query runs without category filter
- `SearchController.cs:45` → calls `SearchService.Query()`
- `SearchService.cs:112` → check categoryFilter parameter → **passed as null** ✅ Likely

### Hypothesis 2: DB table join is incorrect
- `SearchRepository.cs:78` → check SQL → join is correct ❌ Ruled out

### Hypothesis 3: Response mapping mixes in other entities
- `SearchMapper.cs:34` → check mapping logic → correct ❌ Ruled out

## Conclusion: Hypothesis 1 confirmed — categoryFilter passed as null to SearchService.Query()