deep-debug

Files (1)

• SKILL.md

SKILL.md (first lines)

## Inputs (skill args)

| 인자 | 의미 |
|---|---|
| (없음) | Debug sub-mode 진입 — 현재 실패 컨텍스트로부터 root cause 분석 |

빈 args / 매칭되지 않는 토큰 → 본문의 default 분기로 진입.

## Prerequisites


# Systematic Debugging

You are entering **Debug Sub-Mode** within a Deep Work implementation session.

## Language

Read(`${CLAUDE_PLUGIN_ROOT}/skills/shared/references/user-language.md`) and follow it.

## Iron Rule

🚫 **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**

Do NOT:
- Guess at fixes based on the error message alone
- Try random changes to see if they work
- Apply a fix without understanding WHY the bug exists
- Move on after a fix without verifying the root cause theory

## Trigger Conditions

This command activates automatically when:
- `verification_cmd` fails after the GREEN phase (unexpected regression)
- A previously passing test starts failing
- The user explicitly calls `/deep-debug`

## Phase 1: Investigate

1. **Read the error carefully**:
   ```
   에러 분석:
      테스트: [failing test name]
      에러 메시지: [exact error]
      스택 트레이스: [relevant lines]
   ```

2. **Reproduce consistently**: Run the failing command 2 more times to confirm it's not flaky

3. **Check recent changes**: What was the last edit before the failure?
   ```bash
   git diff HEAD
   git log --oneline -5
   ```

4. **Gather evidence**: Read related files, check imports, trace data flow

## Phase 2: Analyze

1. **Find a working reference**: Is there similar code that works? Compare patterns.

2. **Identify the difference**: What's different between the working and broken state?

3. **Trace data flow**: Follow the data from input to the failure point:
   ```
   데이터 흐름:
      입력: [source] → [transform1] → [transform2] → ❌ [failure point]
      예상: [expected value at failure point]
      실제: [actual value at failure point]
   ```

## Phase 3: Hypothesize

1. **Form ONE hypothesis**: Based on evidence, not guessing
   ```
   가설:
      원인: [specific root cause]
      근거: [evidence supporting this hypothesis]
      검증 방법: [how to test this hypothesis]
   ```

2. **Test the hypothesis minimally**: Verify with the smallest possible change or check

3. **If hypothesis is wrong**: Return to Phase 2 with new data. Do NOT try another random fix.

## Phase 4: Implement Fix

1. **Apply the minimal fix** based on verified root cause
2. **Run the failing test** — it should now pass
3. **Run the full test suite** — no regressions
4. **Record the root cause**:

Write to `$WORK_DIR/debug-log/RC-NNN.md`:
```markdown
# Root Cause: [Title]

## 증상
- 실패한 테스트: [test name]
- 에러 메시지: [message]

## 근본 원인
[Explanation of why the bug existed]

## 수정 내용
[What was changed and why]

## 교훈
[What to watch for in the future]

## 관련 Slice
- SLICE-NNN: [goal]
```

5. **Update receipt**: Set `debug.root_cause_note` to the RC file path

## Escalation

If 3 fix attempts fail (3 different hypotheses tested and invalidated):

```

From Sungmin-Cho/deep-work, MIT.

More from Sungmin-Cho/deep-work