Bugfix

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
No completion claims without evidence
Must stop after 3 failed attempts

/bugfix "error description"

Phase 1: DIAGNOSE ─────────────────────────────────
  debugger + verification-planner + gap-analyzer (all parallel)
  → Blast-radius grep scan + Triage recommendation
  → User confirmation (includes triage hint)

Phase 2: REQUIREMENTS GENERATION ──────────────────
  Diagnosis results → requirements.md (hoyeon-cli req init + Write)

Phase 3: EXECUTE ──────────────────────────────────
  Skill("execute", args=spec_dir)
  → Success: Phase 5
  → HALT: Phase 4

Phase 4: RESULT HANDLING (if HALT) ────────────────
  Retry (max 3) with stagnation detection → Phase 3
  Circuit breaker → .hoyeon/debug/{slug}.md → suggest /specify

Phase 5: CLEANUP & REPORT ─────────────────────────
  Save .hoyeon/debug/{slug}.md → final summary

SESSION_ID = [from hook — $CLAUDE_SESSION_ID]
slug = convert bug description to kebab-case (e.g. "null-pointer-in-auth")
DEBUG_STATE = "$HOME/.hoyeon/$SESSION_ID/debug-state.md"
hoyeon-cli session set --sid $SESSION_ID --json '{"skill":"bugfix","debug":"'"$DEBUG_STATE"'"}'

Write(DEBUG_STATE):
# Debug: {bug description}
status: investigating

attempt: 0
slug: {slug}

## Symptoms (IMMUTABLE after Phase 1)
- expected: {from user input}
- actual: {from user input}
- error: {from user input}

## Diagnosis
root_cause: pending
spec_dir: pending

## Attempts

Task(debugger):
  "Bug Description: {user input}
   Error Output: {error logs, if available}
   Context: {related files/recent changes, if available}

   Investigate this bug following your Investigation Protocol.
   Classify Bug Type, trace backward to root cause, assess Severity."

Task(verification-planner):
  "User's Goal: Fix the bug described below
   Current Understanding: {user input}
   Work Breakdown:
   - Reproduce bug with test
   - Apply minimal fix at root cause
   - Verify fix resolves the issue

   Focus on Auto items only (what commands prove the fix works).
   Keep it minimal — this is a bug fix, not a feature.

   Note: /bugfix uses Tier 1-3 (Auto items) only. Do not inline VERIFICATION.md.
   Tier 4 (sandbox items) are not needed. Mark sandbox section as 'bugfix mode — Tier 1-3 only'."

Update DEBUG_STATE:
  ## Diagnosis section:
  root_cause: {debugger's Root Cause — 1 line}
  bug_type: {classification}
  proposed_fix: {proposed fix — 1 line}

Task(gap-analyzer):
  "User's Goal: Fix the bug below
   Current Understanding: {debugger's full Bug Analysis Report}
   Intent Type: Bug Fix

   Focus on:
   - Whether root cause vs symptom distinction is correct
   - Whether proposed fix could break other areas
   - Whether similar bugs exist with the same pattern"

# Extract from debugger's Root Cause section:
#   fn   = function or symbol name at the root cause (e.g. "parseToken")
#   mod  = module path without extension (e.g. "src/auth/token")
# If the function name cannot be reliably extracted, set fn="" and skip caller_count.

total_files=$(git ls-files | wc -l | tr -d ' ')
callers=$(git grep -l -F "$fn" 2>/dev/null | wc -l | tr -d ' ')
importers=$(git grep -l -F "$mod" 2>/dev/null | wc -l | tr -d ' ')
test_refs=$(git grep -l -F "$fn" -- '**/*test*' '**/*spec*' 2>/dev/null | wc -l | tr -d ' ')
hot_path=$(git grep -l -F "$fn" -- 'migrations/**' 'auth/**' 'payment/**' 'billing/**' 'schema/**' 2>/dev/null | wc -l | tr -d ' ')

Update DEBUG_STATE:
  ## Diagnosis:
    blast:
      total_files: {total_files}
      callers: {callers}
      importers: {importers}
      tests: {test_refs}
      hot_path: {hot_path}

Update DEBUG_STATE:
  triage:
    hint: {specify|discuss|bugfix}
    reason: "{1-line reason}"

AskUserQuestion:
  header: "Root Cause & Triage"
  question: "Review diagnosis and choose how to proceed."

  Display:
  - Bug Type: [classification]
  - Root Cause: [file:line + 1-line description]
  - Proposed Fix: [change description — 1 line]
  - Verification: [verification commands from verification-planner]
  - Assumptions: [debugger's Assumptions section]
  - Key warnings from Gap Analysis

  - Blast Radius: callers={N}, importers={M}, tests={T}, hot_path={H}
  - Triage: {hint from Step 1.3c} — {reason}
    (e.g. "/specify recommended — touches auth/ (hot path)")

  options:
  - "Continue with bugfix" → Phase 2
      (if triage hint != bugfix, show as "Continue with bugfix (override triage)")
  - "Switch to /specify" → Hand off requirements.md + debug-state.md to /specify
  - "Switch to /discuss" → Exit bugfix, suggest running /discuss with the bug context
  - "Root cause is different" → Re-run Step 1.2 with user's additional info
  - "Stop" → Exit

# requirements.md hasn't been written yet (Phase 2 is skipped on handoff),
# but debug-state.md contains all Phase 1 findings. Save a skeleton so /specify
# has a starting point, then exit bugfix.

hoyeon-cli req init ${SPEC_DIR} --type bugfix --goal "Fix: {bug description}"
# Append debugger report + blast scan to ${SPEC_DIR}/requirements.md as context
# (sections: ## Debug Context, ## Blast Radius)

Update DEBUG_STATE: status: escalated, reason: "user_triage_specify"

print("Handed off to /specify. Run: /specify {SPEC_DIR}")

SPEC_DIR = "$HOME/.hoyeon/$SESSION_ID"

hoyeon-cli req init ${SPEC_DIR} --type bugfix --goal "Fix: {bug description}"

---
type: bugfix
goal: "Fix: {bug description}"
non_goals:
  - "No refactoring beyond the fix"
  - "No unrelated feature changes"
---

# Requirements

## R-B1: {Bug fix requirement title — describes the broken behavior}
- behavior: {one-sentence description of what should work correctly after fix}

#### R-B1.1: {sub-requirement — the core bug scenario}
- given: {the precondition/state that triggers the bug}
- when: {the action that exercises the broken path}
- then: {the expected (post-fix) outcome — what "fixed" looks like}

#### R-B1.2: {sub-requirement — edge case or similar issue, if any}
- given: {precondition for the edge case}
- when: {action that triggers it}
- then: {expected outcome}

## R-T1: Minimal diff constraint
- behavior: Fix targets root cause only with minimal code changes

#### R-T1.1: Root cause targeting
- given: {root cause identified at file:line}
- when: the fix is applied
- then: only the root cause location is modified, no unrelated changes

## Constraints
- Minimal diff (<5% of codebase)
- Fix root cause, not symptom
- No refactoring beyond what the fix requires

hoyeon-cli session set --sid $SESSION_ID --spec "$SPEC_DIR"

Skill("execute", args="${SPEC_DIR}")

IF execute completed successfully (all tasks done, report output):
  → Phase 5

IF execute HALTED:
  → Phase 4

# Extract failure reason from execute's HALT output
# or read from context dir's audit.md, issues.json
CONTEXT_DIR = "${SPEC_DIR}/context"
failure_reason = {execute HALT output or last triage result from audit.md}