@sienklogic/plan-build-run 2.0.0 → 2.0.2

package/plugins/pbr/skills/debug/SKILL.md

@@ -1,489 +1,515 @@
----
-name: debug
-description: "Systematic debugging with hypothesis testing. Persistent across sessions."
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion
-argument-hint: "[issue description]"
----
-
-# /pbr:debug — Systematic Debugging
-
-You are running the **debug** skill. Your job is to run a structured, hypothesis-driven debugging session that persists across conversations. You track every hypothesis, test, and finding in a debug file so work is never lost.
-
-This skill **spawns Task(subagent_type: "pbr:debugger")** for investigation work.
-
----
-
-## Context Budget
-
-Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
-
-Additionally for this skill:
-- **Never** perform investigation work yourself — delegate ALL analysis to the debugger subagent
-- **Minimize** reading debug file content — read only the latest hypothesis and result section
-- **Delegate** all code reading, hypothesis testing, and fix attempts to the debugger subagent
-
----
-
-## Core Principle
-
-**Debug systematically, not randomly.** Every investigation step must have a hypothesis, a test, and a recorded result. No "let me just try this" — every action has a reason and is documented.
-
----
-
-## Flow
-
-### Step 1: Check for Active Debug Sessions
-
-**Load depth profile:** Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get `debug.max_hypothesis_rounds`. If the command fails (no config.json or CLI error), default to 5 rounds. Initialize a round counter at 0. This counter increments each time a continuation debugger is spawned.
-
-Scan `.planning/debug/` for existing debug files:
-
-```
-.planning/debug/
-  {NNN}-{slug}.md     # Each debug session is a file
-```
-
-Read each file's frontmatter to check status:
-- `status: active` — session is in progress
-- `status: resolved` — session is complete
-- `status: stale` — session was abandoned
-
-**If active sessions found:**
-
-Use the **debug-session-select** pattern from `skills/shared/gate-prompts.md`:
-  question: "Found active debug sessions. Which would you like?"
-
-Generate options dynamically from active sessions:
-- Each active session becomes an option: label "#{NNN}: {title}", description "Started {date}, last: {last hypothesis}"
-- Always include "New session" as the last option: description "Start a fresh debug investigation"
-- If more than 3 active sessions exist, show only the 3 most recent plus "New session" (max 4 options)
-
-Handle responses:
-- If user selects an existing session: go to **Resume Flow** (Step 2b)
-- If user selects "New session": go to **New Session Flow** (Step 2a)
-- If user types a session number not in the list: look it up and resume it
-
-**If no active sessions found:**
-- Go to **New Session Flow**
-
-### Step 2a: New Session Flow
-
-#### Gather Symptoms
-
-If `$ARGUMENTS` is provided and descriptive:
-- Use it as the initial issue description
-- Still ask targeted follow-up questions
-
-If `$ARGUMENTS` is empty or minimal:
-- Ask the user for symptoms
-
-**Symptom gathering questions** (ask as plain text — these are freeform, do NOT use AskUserQuestion):
-
-1. **Expected behavior**: "What should happen?"
-2. **Actual behavior**: "What actually happens? Include error messages if any."
-3. **Reproduction**: "How do you trigger this? Steps to reproduce?"
-4. **Onset**: "When did this start? Did anything change recently (new code, dependency update, config change)?"
-5. **Scope**: "Does this affect everything or just specific cases? Any patterns?"
-
-**Optional follow-ups** (ask if relevant):
-- "What have you already tried?"
-- "Does this happen in all environments (dev, prod, test)?"
-- "Any relevant log output?"
-
-#### Generate Session ID
-
-1. Scan `.planning/debug/` for existing files
-2. Extract NNN prefixes
-3. Next number = highest + 1 (start at 001)
-4. Generate slug from issue title (same rules as quick task slugs)
-
-#### Create Debug File
-
-Create `.planning/debug/{NNN}-{slug}.md`:
-
-```markdown
----
-id: "{NNN}"
-title: "{issue title}"
-status: active
-created: "{ISO date}"
-updated: "{ISO date}"
-severity: "{critical|high|medium|low}"
-category: "{runtime|build|test|config|integration|unknown}"
----
-
-# Debug Session: {title}
-
-## Symptoms
-
-**Expected:** {expected behavior}
-**Actual:** {actual behavior}
-**Reproduction:** {steps}
-**Onset:** {when it started}
-**Scope:** {affected areas}
-
-## Environment
-
-- OS: {detected or reported}
-- Runtime: {node version, python version, etc.}
-- Relevant config: {any config that matters}
-
-## Investigation Log
-
-### Round 1 (automated)
-
-{This section is filled by debugger}
-
-## Hypotheses
-
-| # | Hypothesis | Status | Evidence |
-|---|-----------|--------|----------|
-| 1 | {hypothesis} | {testing/confirmed/rejected} | {evidence} |
-
-## Root Cause
-
-{Filled when found}
-
-## Fix Applied
-
-{Filled when fixed}
-
-## Timeline
-
-- {ISO date}: Session created
-```
-
-#### Spawn Debugger
-
-Display to the user: `◐ Spawning debugger...`
-
-Spawn `Task(subagent_type: "pbr:debugger")` with the prompt template.
-
-Read `skills/debug/templates/initial-investigation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and symptom placeholders with values from the debug file created above.
-
-### Step 2b: Resume Flow
-
-1. Read the debug file content
-2. Parse the investigation log and hypotheses table
-3. Display to user:
-
-```
-Resuming debug session #{NNN}: {title}
-
-Last state:
-- Hypotheses tested: {N}
-- Confirmed: {list or "none yet"}
-- Rejected: {list}
-- Current lead: {most promising hypothesis}
-
-Continuing investigation...
-```
-
-4. Display to the user: `◐ Spawning debugger (resuming session #{NNN})...`
-
-   Spawn `Task(subagent_type: "pbr:debugger")` with the continuation prompt template.
-
-   Read `skills/debug/templates/continuation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and `{paste investigation log...}` placeholders with data from the debug file.
-
-### Step 3: Handle Debugger Results
-
-The debugger returns one of four outcomes:
-
-#### ROOT CAUSE FOUND + FIX
-
-```
-Root cause identified: {cause}
-Fix applied: {description}
-Commit: {hash}
-```
-
-Actions:
-1. Update debug file:
-   - Set `status: resolved`
-   - Fill "Root Cause" section
-   - Fill "Fix Applied" section
-   - Add timeline entry
-2. Update STATE.md if it has a Debug Sessions section
-3. Report to user with branded output:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PLAN-BUILD-RUN ► BUG RESOLVED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Session #{NNN}:** {title}
-**Root cause:** {cause}
-**Fix:** {description}
-**Commit:** {hash}
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Continue your workflow** — the bug is fixed
-
-`/pbr:status`
-
-<sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**Also available:**
-- `/pbr:continue` — execute next logical step
-- `/pbr:review {N}` — verify the current phase
-
-───────────────────────────────────────────────────────────────
-```
-
-#### ROOT CAUSE FOUND (no fix)
-
-Used when the debugger was invoked with `find_root_cause_only` or when the fix is too complex for auto-application.
-
-```
-Root cause identified: {cause}
-Suggested fix: {approach}
-```
-
-Actions:
-1. Update debug file:
-   - Set `status: resolved`
-   - Fill "Root Cause" section
-   - Add suggested fix to notes
-2. Suggest next steps to user:
-
-```
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Apply the fix** — root cause identified, fix needed
-
-`/pbr:quick {fix description}`
-
-<sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**Also available:**
-- `/pbr:plan` — for complex fixes that need planning
-- `/pbr:status` — see project status
-
-───────────────────────────────────────────────────────────────
-```
-
-#### CHECKPOINT
-
-The debugger found something but needs user input or more investigation.
-
-```
-Investigation progress:
-- Tested: {hypotheses tested}
-- Found: {key finding}
-- Need: {what's needed to continue}
-```
-
-Actions:
-1. Update debug file with findings so far
-2. Present checkpoint to user
-3. Use the **debug-checkpoint** pattern from `skills/shared/gate-prompts.md`:
-   question: "Investigation has reached a checkpoint. How should we proceed?"
-
-Handle responses:
-- "Continue": Display `◐ Spawning debugger (continuing investigation)...` and spawn another `Task(subagent_type: "pbr:debugger")` with updated context from the debug file
-- "More info": Ask the user freeform what additional context they have, then update the debug file and spawn another debugger
-- "New approach": Ask the user freeform what alternative angle to try, then update hypotheses and spawn another debugger
-
-#### INCONCLUSIVE
-
-The debugger exhausted its hypotheses without finding the root cause.
-
-```
-Investigation exhausted:
-- Tested: {all hypotheses}
-- Rejected: {list}
-- Remaining unknowns: {list}
-```
-
-Actions:
-1. Update debug file with all findings
-2. Report to user:
-   - What was tested and eliminated
-   - What remains unknown
-   - Suggested next investigation approaches:
-     - Different reproduction steps
-     - Log-level debugging
-     - Environment comparison
-     - Bisect (git bisect to find the breaking commit)
-     - External help (stack overflow, docs)
-3. Keep session active for future resumption
-
----
-
-## Debugger Investigation Protocol
-
-The debugger agent follows this protocol internally:
-
-### Hypothesis-Driven Investigation
-
-```
-1. OBSERVE: Read error messages, logs, code around the failure point
-2. HYPOTHESIZE: "The most likely cause is X because Y"
-3. PREDICT: "If X is the cause, then test Z should show W"
-4. TEST: Execute test Z
-5. EVALUATE:
-   - Result matches prediction → hypothesis supported → investigate deeper
-   - Result contradicts → hypothesis rejected → try next hypothesis
-   - Result is unexpected → new information → form new hypothesis
-```
-
-### Investigation Techniques
-
-| Technique | When to Use |
-|-----------|------------|
-| **Stack trace analysis** | Error with stack trace available |
-| **Code path tracing** | Logic error, wrong behavior |
-| **Log injection** | Need to see runtime values |
-| **Binary search** | Know it worked before, need to find when it broke |
-| **Isolation** | Complex system, need to narrow scope |
-| **Comparison** | Works in one case, fails in another |
-| **Dependency audit** | Recent dependency changes |
-| **Config diff** | Works in one environment, not another |
-
-### Evidence Quality
-
-| Quality | Description | Action |
-|---------|-------------|--------|
-| **Strong** | Directly proves/disproves hypothesis | Record and move on |
-| **Moderate** | Suggests but doesn't prove | Record, seek corroboration |
-| **Weak** | Tangentially related | Note but don't base decisions on it |
-| **Misleading** | Red herring | Record as eliminated, explain why |
-
-### Hypothesis Round Limit
-
-The maximum number of investigation rounds is controlled by the depth profile's `debug.max_hypothesis_rounds` setting:
-- `quick`: 3 rounds (fast, surface-level investigation)
-- `standard`: 5 rounds (default)
-- `comprehensive`: 10 rounds (deep investigation)
-
-The orchestrator tracks the round count. Before spawning each continuation debugger (Step 3 "CHECKPOINT" -> "Continue"), increment the round counter. If the counter reaches the limit:
-- Do NOT spawn another debugger
-- Present to user: "Debug session has reached the hypothesis round limit ({N} rounds for {depth} mode). Options:"
-
-Use AskUserQuestion:
-  question: "Reached {N}-round hypothesis limit. How should we proceed?"
-  header: "Debug Limit"
-  options:
-    - label: "Extend"    description: "Allow {N} more rounds (doubles the limit)"
-    - label: "Wrap up"   description: "Record findings so far and close the session"
-    - label: "Escalate"  description: "Save context for manual debugging"
-
-- If "Extend": double the limit and continue
-- If "Wrap up": update debug file status to `stale`, record all findings, suggest next steps
-- If "Escalate": write a detailed handoff document to the debug file with all hypotheses, evidence, and suggested manual investigation steps
-
----
-
-## Debug File Management
-
-### Lifecycle
-
-```
-active → resolved     (root cause found and fixed)
-active → stale        (abandoned — no updates for 7+ days)
-active → active       (resumed after pause)
-```
-
-### Staleness Detection
-
-When scanning for active sessions, check the `updated` date. If more than 7 days old:
-- Mark as `stale` in status
-- Still offer to resume, but warn: "This session is {N} days old. Context may have changed."
-
-### Cleanup
-
-Old resolved debug files can accumulate. They serve as a knowledge base for similar issues. Do NOT auto-delete them.
-
----
-
-## State Integration
-
-Update STATE.md Debug Sessions section (create if needed):
-
-```markdown
-### Debug Sessions
-
-| # | Issue | Status | Root Cause |
-|---|-------|--------|------------|
-| 001 | Login timeout | resolved | DB connection pool exhausted |
-| 002 | CSS not loading | active | investigating |
-```
-
----
-
-## Git Integration
-
-Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
-
-If `planning.commit_docs: true` in config.json:
-- New session: `docs(planning): open debug session {NNN} - {slug}`
-- Resolution: `docs(planning): resolve debug session {NNN} - {root cause summary}`
-- Fix commits use standard format: `fix({scope}): {description}`
-
----
-
-## Edge Cases
-
-### User provides a stack trace or error in arguments
-- Parse it as the "Actual behavior" symptom
-- Extract key information: error type, file, line number
-- Use this to form initial hypotheses immediately
-
-### Debugger agent fails
-If the debugger Task() fails or returns an error, display:
-```
-╔══════════════════════════════════════════════════════════════╗
-║  ERROR                                                       ║
-╚══════════════════════════════════════════════════════════════╝
-
-Debugger agent failed for session #{NNN}.
-
-**To fix:**
-- Check the debug file at `.planning/debug/{NNN}-{slug}.md` for partial findings
-- Re-run with `/pbr:debug` to resume the session
-- If the issue persists, try a fresh session with different symptom details
-```
-
-### Issue is in a dependency (not user code)
-- Document which dependency and version
-- Check if there's a known issue (search patterns in node_modules, site-packages, etc.)
-- Suggest: update dependency, pin version, or work around
-
-### Issue is intermittent
-- Note intermittency in symptoms
-- Suggest: run multiple times, add timing/logging, check for race conditions
-- Investigation must account for non-deterministic reproduction
-
-### Multiple issues interacting
-- If investigation reveals multiple separate issues, split into separate debug sessions
-- Create additional debug files
-- Track each independently
-
-### Fix would be a breaking change
-- Report the root cause but DO NOT auto-apply the fix
-- Present the trade-offs to the user
-- Let the user decide how to proceed
-
----
-
-## Anti-Patterns
-
-1. **DO NOT** skip hypothesis formation — every test must have a reason
-2. **DO NOT** make random changes hoping something works
-3. **DO NOT** ignore failed hypotheses — record why they failed
-4. **DO NOT** exceed the depth profile's `debug.max_hypothesis_rounds` limit without user confirmation (default: 5 for standard mode)
-5. **DO NOT** fix the symptom instead of the root cause
-6. **DO NOT** auto-apply fixes for breaking changes
-7. **DO NOT** delete debug files — they're a knowledge base
-8. **DO NOT** combine multiple bugs into one debug session
-9. **DO NOT** skip updating the debug file after each investigation round
-10. **DO NOT** start a new session when an active one covers the same issue
+---
+name: debug
+description: "Systematic debugging with hypothesis testing. Persistent across sessions."
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion
+argument-hint: "[issue description]"
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► DEBUGGING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
+# /pbr:debug — Systematic Debugging
+
+You are running the **debug** skill. Your job is to run a structured, hypothesis-driven debugging session that persists across conversations. You track every hypothesis, test, and finding in a debug file so work is never lost.
+
+This skill **spawns Task(subagent_type: "pbr:debugger")** for investigation work.
+
+---
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- **Never** perform investigation work yourself — delegate ALL analysis to the debugger subagent
+- **Minimize** reading debug file content — read only the latest hypothesis and result section
+- **Delegate** all code reading, hypothesis testing, and fix attempts to the debugger subagent
+
+---
+
+## Core Principle
+
+**Debug systematically, not randomly.** Every investigation step must have a hypothesis, a test, and a recorded result. No "let me just try this" — every action has a reason and is documented.
+
+---
+
+## Flow
+
+### Step 1: Ensure Debug Directory Exists
+
+Before any file operations, ensure both directories exist by running:
+
+```bash
+mkdir -p .planning/debug
+```
+
+This handles the case where neither `.planning/` nor `.planning/debug/` exist yet (debug can be run before other skills that create `.planning/`). Do NOT skip this step — writing files to a non-existent directory will fail.
+
+### Step 2: Check for Active Debug Sessions
+
+**Load depth profile:** Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth` to get `debug.max_hypothesis_rounds`. If the command fails (no config.json or CLI error), default to 5 rounds. Initialize a round counter at 0. This counter increments each time a continuation debugger is spawned.
+
+Scan `.planning/debug/` for existing debug files:
+
+```
+.planning/debug/
+  {NNN}-{slug}.md     # Each debug session is a file
+```
+
+Read each file's frontmatter to check status:
+- `status: active` — session is in progress
+- `status: resolved` — session is complete
+- `status: stale` — session was abandoned
+
+**If active sessions found:**
+
+Use the **debug-session-select** pattern from `skills/shared/gate-prompts.md`:
+  question: "Found active debug sessions. Which would you like?"
+
+Generate options dynamically from active sessions:
+- Each active session becomes an option: label "#{NNN}: {title}", description "Started {date}, last: {last hypothesis}"
+- Always include "New session" as the last option: description "Start a fresh debug investigation"
+- If more than 3 active sessions exist, show only the 3 most recent plus "New session" (max 4 options)
+
+Handle responses:
+- If user selects an existing session: go to **Resume Flow** (Step 3b)
+- If user selects "New session": go to **New Session Flow** (Step 3a)
+- If user types a session number not in the list: look it up and resume it
+
+**If no active sessions found:**
+- Go to **New Session Flow** (Step 3a)
+
+### Step 3a: New Session Flow
+
+#### Gather Symptoms
+
+If `$ARGUMENTS` is provided and descriptive:
+- Use it as the initial issue description
+- Still ask targeted follow-up questions
+
+If `$ARGUMENTS` is empty or minimal:
+- Ask the user for symptoms
+
+**Symptom gathering questions** (ask as plain text — these are freeform, do NOT use AskUserQuestion):
+
+1. **Expected behavior**: "What should happen?"
+2. **Actual behavior**: "What actually happens? Include error messages if any."
+3. **Reproduction**: "How do you trigger this? Steps to reproduce?"
+4. **Onset**: "When did this start? Did anything change recently (new code, dependency update, config change)?"
+5. **Scope**: "Does this affect everything or just specific cases? Any patterns?"
+
+**Optional follow-ups** (ask if relevant):
+- "What have you already tried?"
+- "Does this happen in all environments (dev, prod, test)?"
+- "Any relevant log output?"
+
+#### Generate Session ID
+
+1. Scan `.planning/debug/` for existing files
+2. Extract NNN prefixes
+3. Next number = highest + 1 (start at 001)
+4. Generate slug from issue title (same rules as quick task slugs)
+
+#### Create Debug File
+
+Create `.planning/debug/{NNN}-{slug}.md`:
+
+```markdown
+---
+id: "{NNN}"
+title: "{issue title}"
+status: active
+created: "{ISO date}"
+updated: "{ISO date}"
+severity: "{critical|high|medium|low}"
+category: "{runtime|build|test|config|integration|unknown}"
+---
+
+# Debug Session: {title}
+
+## Symptoms
+
+**Expected:** {expected behavior}
+**Actual:** {actual behavior}
+**Reproduction:** {steps}
+**Onset:** {when it started}
+**Scope:** {affected areas}
+
+## Environment
+
+- OS: {detected or reported}
+- Runtime: {node version, python version, etc.}
+- Relevant config: {any config that matters}
+
+## Investigation Log
+
+### Round 1 (automated)
+
+{This section is filled by debugger}
+
+## Hypotheses
+
+| # | Hypothesis | Status | Evidence |
+|---|-----------|--------|----------|
+| 1 | {hypothesis} | {testing/confirmed/rejected} | {evidence} |
+
+## Root Cause
+
+{Filled when found}
+
+## Fix Applied
+
+{Filled when fixed}
+
+## Timeline
+
+- {ISO date}: Session created
+```
+
+#### Spawn Debugger
+
+Display to the user: `◐ Spawning debugger...`
+
+Spawn `Task(subagent_type: "pbr:debugger")` with the prompt template.
+
+Read `skills/debug/templates/initial-investigation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and symptom placeholders with values from the debug file created above.
+
+### Step 3b: Resume Flow
+
+1. Read the debug file content
+2. Parse the investigation log and hypotheses table
+3. Display to user:
+
+```
+Resuming debug session #{NNN}: {title}
+
+Last state:
+- Hypotheses tested: {N}
+- Confirmed: {list or "none yet"}
+- Rejected: {list}
+- Current lead: {most promising hypothesis}
+
+Continuing investigation...
+```
+
+4. **Increment the round counter** (resuming counts as a new round). Display to the user: `◐ Spawning debugger (resuming session #{NNN}, round {N})...`
+
+   Spawn `Task(subagent_type: "pbr:debugger")` with the continuation prompt template.
+
+   Read `skills/debug/templates/continuation-prompt.md.tmpl` for the spawn prompt. Fill in the `{NNN}`, `{slug}`, and `{paste investigation log...}` placeholders with data from the debug file.
+
+### Step 4: Handle Debugger Results
+
+When the debugger agent completes, display: `✓ Debug session complete — {N} hypotheses tested` (read the hypothesis count from the debug file's Hypotheses table).
+
+The debugger returns one of four outcomes:
+
+#### ROOT CAUSE FOUND + FIX
+
+```
+Root cause identified: {cause}
+Fix applied: {description}
+Commit: {hash}
+```
+
+Actions:
+1. Update debug file:
+   - Set `status: resolved`
+   - Fill "Root Cause" section
+   - Fill "Fix Applied" section
+   - Add timeline entry
+2. Update STATE.md if it has a Debug Sessions section
+3. Report to user with branded output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► BUG RESOLVED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Session #{NNN}:** {title}
+**Root cause:** {cause}
+**Fix:** {description}
+**Commit:** {hash}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Continue your workflow** — the bug is fixed
+
+`/pbr:status`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:continue` — execute next logical step
+- `/pbr:review {N}` — verify the current phase
+
+───────────────────────────────────────────────────────────────
+```
+
+#### ROOT CAUSE FOUND (no fix)
+
+Used when the debugger was invoked with `find_root_cause_only` or when the fix is too complex for auto-application.
+
+```
+Root cause identified: {cause}
+Suggested fix: {approach}
+```
+
+Actions:
+1. Update debug file:
+   - Set `status: resolved`
+   - Fill "Root Cause" section
+   - Add suggested fix to notes
+2. Suggest next steps to user:
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Apply the fix** — root cause identified, fix needed
+
+`/pbr:quick {fix description}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:plan` — for complex fixes that need planning
+- `/pbr:status` — see project status
+
+───────────────────────────────────────────────────────────────
+```
+
+#### CHECKPOINT
+
+The debugger found something but needs user input or more investigation.
+
+```
+Investigation progress:
+- Tested: {hypotheses tested}
+- Found: {key finding}
+- Need: {what's needed to continue}
+```
+
+Actions:
+1. Update debug file with findings so far
+2. Present checkpoint to user
+3. Use the **debug-checkpoint** pattern from `skills/shared/gate-prompts.md`:
+   question: "Investigation has reached a checkpoint. How should we proceed?"
+
+Handle responses:
+- "Continue": **Increment the round counter** (e.g., round 1 becomes round 2). Then display `◐ Spawning debugger (continuing investigation, round {N})...` and spawn another `Task(subagent_type: "pbr:debugger")` with updated context from the debug file
+- "More info": **Increment the round counter.** Ask the user freeform what additional context they have, then update the debug file and spawn another debugger
+- "New approach": **Increment the round counter.** Ask the user freeform what alternative angle to try, then update hypotheses and spawn another debugger
+
+#### INCONCLUSIVE
+
+The debugger exhausted its hypotheses without finding the root cause.
+
+```
+Investigation exhausted:
+- Tested: {all hypotheses}
+- Rejected: {list}
+- Remaining unknowns: {list}
+```
+
+Actions:
+1. Update debug file with all findings
+2. Report to user:
+   - What was tested and eliminated
+   - What remains unknown
+   - Suggested next investigation approaches:
+     - Different reproduction steps
+     - Log-level debugging
+     - Environment comparison
+     - Bisect (git bisect to find the breaking commit)
+     - External help (stack overflow, docs)
+3. Keep session active for future resumption
+
+---
+
+## Debugger Investigation Protocol
+
+The debugger agent follows this protocol internally:
+
+### Hypothesis-Driven Investigation
+
+```
+1. OBSERVE: Read error messages, logs, code around the failure point
+2. HYPOTHESIZE: "The most likely cause is X because Y"
+3. PREDICT: "If X is the cause, then test Z should show W"
+4. TEST: Execute test Z
+5. EVALUATE:
+   - Result matches prediction → hypothesis supported → investigate deeper
+   - Result contradicts → hypothesis rejected → try next hypothesis
+   - Result is unexpected → new information → form new hypothesis
+```
+
+### Investigation Techniques
+
+| Technique | When to Use |
+|-----------|------------|
+| **Stack trace analysis** | Error with stack trace available |
+| **Code path tracing** | Logic error, wrong behavior |
+| **Log injection** | Need to see runtime values |
+| **Binary search** | Know it worked before, need to find when it broke |
+| **Isolation** | Complex system, need to narrow scope |
+| **Comparison** | Works in one case, fails in another |
+| **Dependency audit** | Recent dependency changes |
+| **Config diff** | Works in one environment, not another |
+
+### Evidence Quality
+
+| Quality | Description | Action |
+|---------|-------------|--------|
+| **Strong** | Directly proves/disproves hypothesis | Record and move on |
+| **Moderate** | Suggests but doesn't prove | Record, seek corroboration |
+| **Weak** | Tangentially related | Note but don't base decisions on it |
+| **Misleading** | Red herring | Record as eliminated, explain why |
+
+### Hypothesis Round Limit
+
+The maximum number of investigation rounds is controlled by the depth profile's `debug.max_hypothesis_rounds` setting:
+- `quick`: 3 rounds (fast, surface-level investigation)
+- `standard`: 5 rounds (default)
+- `comprehensive`: 10 rounds (deep investigation)
+
+The orchestrator tracks the round count. Before spawning each continuation debugger (Step 4 "CHECKPOINT" -> "Continue"), increment the round counter. If the counter reaches the limit:
+- Do NOT spawn another debugger
+- Present to user: "Debug session has reached the hypothesis round limit ({N} rounds for {depth} mode). Options:"
+
+Use AskUserQuestion:
+  question: "Reached {N}-round hypothesis limit. How should we proceed?"
+  header: "Debug Limit"
+  options:
+    - label: "Extend"    description: "Allow {N} more rounds (doubles the limit)"
+    - label: "Wrap up"   description: "Record findings so far and close the session"
+    - label: "Escalate"  description: "Save context for manual debugging"
+
+- If "Extend": double the limit and continue
+- If "Wrap up": update debug file status to `stale`, record all findings, suggest next steps
+- If "Escalate": write a detailed handoff document to the debug file with all hypotheses, evidence, and suggested manual investigation steps
+
+---
+
+## Debug File Management
+
+### Lifecycle
+
+```
+active → resolved     (root cause found and fixed)
+active → stale        (abandoned — no updates for 7+ days)
+active → active       (resumed after pause)
+```
+
+### Staleness Detection
+
+When scanning for active sessions, check the `updated` date. If more than 7 days old:
+- Mark as `stale` in status
+- Still offer to resume, but warn: "This session is {N} days old. Context may have changed."
+
+### Cleanup
+
+Old resolved debug files can accumulate. They serve as a knowledge base for similar issues. Do NOT auto-delete them.
+
+---
+
+## State Integration
+
+Update STATE.md Debug Sessions section (create if needed):
+
+```markdown
+### Debug Sessions
+
+| # | Issue | Status | Root Cause |
+|---|-------|--------|------------|
+| 001 | Login timeout | resolved | DB connection pool exhausted |
+| 002 | CSS not loading | active | investigating |
+```
+
+---
+
+## Git Integration
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `planning.commit_docs: true` in config.json:
+- New session: `docs(planning): open debug session {NNN} - {slug}`
+- Resolution: `docs(planning): resolve debug session {NNN} - {root cause summary}`
+- Fix commits use standard format: `fix({scope}): {description}`
+
+---
+
+## Edge Cases
+
+### User provides a stack trace or error in arguments
+- Parse it as the "Actual behavior" symptom
+- Extract key information: error type, file, line number
+- Use this to form initial hypotheses immediately
+
+### Debugger agent fails
+If the debugger Task() fails or returns an error, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Debugger agent failed for session #{NNN}.
+
+**To fix:**
+- Check the debug file at `.planning/debug/{NNN}-{slug}.md` for partial findings
+- Re-run with `/pbr:debug` to resume the session
+- If the issue persists, try a fresh session with different symptom details
+```
+
+### Issue is in a dependency (not user code)
+- Document which dependency and version
+- Check if there's a known issue (search patterns in node_modules, site-packages, etc.)
+- Suggest: update dependency, pin version, or work around
+
+### Issue is intermittent
+- Note intermittency in symptoms
+- Suggest: run multiple times, add timing/logging, check for race conditions
+- Investigation must account for non-deterministic reproduction
+
+### Multiple issues interacting
+- If investigation reveals multiple separate issues, split into separate debug sessions
+- Create additional debug files
+- Track each independently
+
+### Fix would be a breaking change
+- Report the root cause but DO NOT auto-apply the fix
+- Present the trade-offs to the user
+- Let the user decide how to proceed
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** skip hypothesis formation — every test must have a reason
+2. **DO NOT** make random changes hoping something works
+3. **DO NOT** ignore failed hypotheses — record why they failed
+4. **DO NOT** exceed the depth profile's `debug.max_hypothesis_rounds` limit without user confirmation (default: 5 for standard mode)
+5. **DO NOT** fix the symptom instead of the root cause
+6. **DO NOT** auto-apply fixes for breaking changes
+7. **DO NOT** delete debug files — they're a knowledge base
+8. **DO NOT** combine multiple bugs into one debug session
+9. **DO NOT** skip updating the debug file after each investigation round
+10. **DO NOT** start a new session when an active one covers the same issue