/bugfix

name: bugfix
description: |
  Root cause based one-shot bug fix. debugger diagnosis → requirements.md generation → /execute.
  /bugfix "error description"
  Full investigation pipeline: debugger + gap-analyzer + standard verify.
  QA suggestion after successful fix.
allowed_tools:
  - Read
  - Grep
  - Glob
  - Task
  - Bash
  - Edit
  - Write
  - AskUserQuestion
  - Skill
validate_prompt: |
  Must complete with one of:
  1. Execute completed successfully (all plan.json tasks done)
  2. Circuit breaker triggered (max attempts exhausted, report saved)
  3. Escalated to /specify (with requirements.md + debug report saved)
  Must NOT: skip root cause analysis, apply multiple fixes simultaneously,
  or manually write plan.json (execute derives it from requirements.md).

/bugfix Skill

Root cause based one-shot bug fix. Diagnose → generate requirements.md → delegate to /execute for fix, verification, and commit.

The Iron Law

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

Architecture

/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

Execution Mode

Always runs the full investigation + execution pipeline. No SIMPLE/COMPLEX branching.

| Phase 1 | Retry | |---------|-------| | debugger + verification-planner + gap-analyzer | bugfix-managed (max 3) |

`/execute` will prompt for dispatch/work/verify via AskUserQuestion when invoked — bugfix does not pre-select these modes.

---

Phase 1: DIAGNOSE

Step 1.1: Parse Input

Extract from user input:

• **Bug description**: error message, symptoms, reproduction steps
• **Error output**: stack trace, test failure logs (if available)
• **Context**: related files, recent changes (if available)

**Initialize Debug State:**

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

Step 1.2: Parallel Investigation

**Always dispatch 2 agents in parallel:**

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'."

**After receiving debugger results, update debug-state.md:**

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

Step 1.3: Gap Analysis

Always run gap-analyzer after debugger results:

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"

Step 1.3b: Blast-radius Quick Scan

After debugger identifies `root_cause.location` (e.g. `src/auth/token.ts:42`), extract the function/module name and run grep-based structural scan. Always use `wc -l` so the LLM compares integers, not raw grep output.

# 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 ' ')

Use `-F` (fixed string) to avoid regex injection from extracted symbols. Empty or malformed symbols → skip that signal, do NOT fail the phase.

Store the scan in `DEBUG_STATE`:

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

**Blind-spot note**: grep misses dynamic dispatch, reflection