Fix Issue

Fix Issue

Host-neutral workflow. Invoke by skill name (fix-issue). Claude Code slash routing, YAML hook loaders, and .claude/chain live in references/claude-code.md.

Systematic issue resolution with hypothesis-based root cause analysis, similar issue detection, and prevention recommendations.

Quick Start

fix-issue 123
fix-issue 456

Opus 5.5: Root cause analysis uses native adaptive thinking. Dynamic token budgets scale with context window for thorough investigation.

CC ≥ 2.1.119 multi-host note (M122): Issue fetching works against GitHub, GitLab, Bitbucket, and GitHub Enterprise. The argument is either a numeric ID (use the configured default remote's host) or a full URL (parsed via parsePrUrl/parseIssueUrl from src/hooks/src/lib/pr-host-parser.ts). Branch on the detected host family for the right CLI: gh issue view (GitHub/GHE), glab issue view (GitLab), bb issue view (Bitbucket). Reference: src/skills/chain-patterns/references/pr-from-platform.md.

Argument Resolution

ISSUE_NUMBER = "$ARGUMENTS[0]"  # e.g., "123" (CC 2.1.59 indexed access)
# $ARGUMENTS contains the full argument string
# $ARGUMENTS[0] is the first space-separated token

STEP -1: MCP Probe + Resume Check

Run BEFORE any other step. Detect available MCP servers and check for resumable state.

# Probe MCPs (parallel — all in ONE message):
# memory is alwaysLoad in .mcp.json (CC 2.1.121+, #1541) — probe below kept as fallback for older CC:
ToolSearch(query="select:mcp__memory__search_nodes")
ToolSearch(query="select:mcp__context7__resolve-library-id")

# Write capability map:
Write(".claude/chain/capabilities.json", JSON.stringify({
  "memory": <true if found>,
  "context7": <true if found>,
  "timestamp": now()
}))

# Check for resumable state:
Read(".claude/chain/state.json")
# If exists and skill == "fix-issue":
#   Read last handoff, skip to current_phase
#   Tell user: "Resuming from Phase {N}"
# If not exists: write initial state
Write(".claude/chain/state.json", JSON.stringify({
  "skill": "fix-issue",
  "issue": ISSUE_NUMBER,
  "current_phase": 1,
  "completed_phases": [],
  "capabilities": capabilities
}))

Load pattern details: Read("../chain-patterns/references/mcp-detection.md")

Phase 0b — Prior-fix lookup (signal-fired, optional)

Before diagnosis kicks off, optionally invoke scripts/prior_fix_lookup.py <session-dir> to surface similar fixes already recorded in the memory MCP. READ-ONLY — no writeback. Self-skips on every non-happy-path so it never blocks the fix:

python3 ${CLAUDE_SKILL_DIR}/scripts/prior_fix_lookup.py "$CLAUDE_JOB_DIR"

Auto-skip conditions (all exit 0, all WARN-logged):

Session dir must contain fix-issue-input.json (with error_text: str). The signature extractor (signature_lib.extract_signature) normalizes Python tracebacks, JS stack traces, and generic <Type>: <msg> errors to a <error_type> <primary_path>:<lineno> shape used as the search_nodes query. Handoff JSON at <session-dir>/prior-fix-matches.json records status, signature, and matches_count; the top-3 matches land in <session-dir>/prior-fix-matches.md as a Markdown table.

Mirrors the memory-consumer pattern from PR #1889 but read-only. Closes orchestkit#1895.

Finish line. Done means: the root cause is confirmed by a failing test that now passes, the full suite is green, and the PR links the issue. Follow Read("../../shared/rules/long-run-protocol.md"): keep going when a step needs no input from the user, stop and ask only when you can't continue without them or before anything destructive, check each subagent's evidence before accepting it, and mark anything you couldn't confirm with where you looked.

Budget: at most 5 RCA agents (Phase 4) and 3 fix-test iterations (one iteration = Phase 6 fix, then Phase 7 validation with the full suite); stop and report at the finish line or the first cap, whichever comes first.

CRITICAL: Task Management is MANDATORY (CC 2.1.16)

BEFORE doing ANYTHING else (after MCP probe), create tasks to track progress:

# 1. Create main task IMMEDIATELY
TaskCreate(
  subject="Fix Issue: #{ISSUE_NUMBER}",
  description="Systematic issue resolution with RCA and prevention",
  activeForm="Fixing issue #{ISSUE_NUMBER}"
)

# 2. Create subtasks for each key phase
TaskCreate(subject="Understand issue", activeForm="Reading issue details")
TaskCreate(subject="Hypothesis & RCA", activeForm="Analyzing root cause")
TaskCreate(subject="Implement fix", activeForm="Applying fix with tests")
TaskCreate(subject="Validate & prevent", activeForm="Validating fix and prevention")
TaskCreate(subject="Commit and PR", activeForm="Creating PR for fix")

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])
TaskUpdate(taskId="4", addBlockedBy=["3"])
TaskUpdate(taskId="5", addBlockedBy=["4"])
TaskUpdate(taskId="6", addBlockedBy=["5"])

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done

STEP 0: Effort-Aware Fix Scaling (CC 2.1.76)

Scale investigation depth based on /effort level:

Override: Explicit user selection (e.g., "Proper fix") overrides /effort downscaling. Hotfix always uses minimal phases regardless of effort.

STEP 0a: Verify User Intent

BEFORE creating tasks, clarify fix approach:

AskUserQuestion(
  questions=[{
    "question": "How do you want to approach this fix?",
    "header": "Fix Approach",
    "options": [
      {"label": "Proper fix (Recommended)", "description": "Full RCA, regression test, prevention plan"},
      {"label": "Quick fix", "description": "Minimal investigation, fix and test"},
      {"label": "Investigate first", "description": "Deep analysis before deciding on approach"},
      {"label": "Hotfix", "description": "Emergency fix, minimal process"}
    ],
    "multiSelect": false
  }]
)

Based on answer, adjust workflow:

• Proper fix: All 11 phases, 5 parallel RCA agents
• Quick fix: Phases 1, 6, 7, 11 only — skip RCA agents and prevention
• Investigate first: Enter plan mode for read-only analysis, then decide
• Hotfix: Phases 1, 6, 11 only — emergency path

Sub-question: Local-CI Strategy (AskUserQuestion — M118 #1467)

Once the approach is chosen, ask whether to run CI locally before pushing — orthogonal to fix depth:

# Skip when invocation flag is explicit:
#   fix-issue 123 --local-ci          → skip, run full suite locally
#   fix-issue 123 --security-only     → skip, security tests only
#   fix-issue 123 --push-and-let-ci   → skip, no local run
#
# Force local-CI when issue has security or data-loss labels (warns user it overrode their choice).

AskUserQuestion(questions=[{
  "question": "Before push?",
  "header": "Local CI",
  "options": [
    {"label": "Push and let CI run (default)", "description": "Fastest round-trip, CI catches failures"},
    {"label": "Run full suite locally first", "description": "~2-3 min extra; catches CI failures locally before push"},
    {"label": "Run security tests only", "description": "~30s; covers the usual blocker class — secrets, deps, common vulns"}
  ]
}])

Override rule: if the issue's GitHub labels include security or data-loss, override the user's selection with "Run full suite locally first" and surface a one-line notification: "Security/data-loss label detected — running full local suite as a precaution." The user can still bypass with the --push-and-let-ci arg, which logs the bypass for audit.

If 'Investigate first' selected:

# 1. Enter read-only plan mode
EnterPlanMode("Investigate issue: $ISSUE_REF")

# 2. Investigation phase — Read/Grep/Glob ONLY, no Write/Edit
#    - Read the issue description and linked context
#    - Trace the error path through relevant code
#    - Search for related issues, past fixes, test failures
#    - Build hypothesis list with evidence

# 3. Produce RCA report:
#    - Root cause hypothesis (ranked by confidence)
#    - Affected files and blast radius
#    - Recommended approach (proper fix vs quick fix)
#    - Risk assessment

# 4. Exit plan mode — returns analysis for user decision
ExitPlanMode()

# 5. User reviews RCA. If "proceed with fix" → continue to Phase 5 (Fix).
#    If "need more info" → re-enter investigation.

Load Read("rules/evidence-gathering.md") for detailed workflow adjustments per approach.

STEP 0b: Select Orchestration Mode

Choose Agent Teams (mesh) or Agent (star, the Agent tool). A Workflow-tool mode is planned (a future workflows/rca-fanout.js for Phase 4 RCA) and is not selectable yet. Load Read("references/agent-selection.md") for the selection criteria, cost comparison, and task creation patterns.

Service Discovery & Visual Inspection

When the issue involves a running web app, API, or UI bug, discover services and inspect visually before forming hypotheses:

# 1. Discover services via Portless (preferred)
portless list 2>/dev/null
# api → api.localhost   (port 8080)
# app → app.localhost   (port 3000)

# 2. Fallback: discover ports manually
lsof -iTCP -sTCP:LISTEN -nP | grep -E 'node|python|java'

# 3. Visual inspection with agent-browser
agent-browser open "https://app.localhost"
agent-browser screenshot /tmp/issue-before.png     # capture broken state
agent-browser console                              # check for JS errors
agent-browser network log                          # inspect failed API calls
agent-browser get text @error-banner               # extract error messages

Use Portless named URLs (*.localhost) in all investigation steps — they're stable, self-documenting, and eliminate port-guessing failures. Install with npm i -g portless.

Workflow Overview

Progressive Output (CC 2.1.76)

Output results incrementally as each phase completes — don't batch until the PR:

For the proper fix path with 5 parallel RCA agents, output each agent's findings as they return — don't wait for all 5. If one agent identifies the root cause with high confidence early, flag it immediately so the user can confirm and skip remaining agents.

Phase Handoffs (CC 2.1.71)

Write handoff JSON after phases 3, 4, 6, 7 to .claude/chain/. See chain-patterns skill for schema.

Worktree-Isolated RCA Agents (CC 2.1.50)

Phase 4 agents SHOULD use isolation: "worktree" when they need to edit files:

Agent(subagent_type="ork:debug-investigator",
  prompt="Investigate hypothesis: {desc}...",
  isolation="worktree", run_in_background=true)

Nested delegation (CC 2.1.172+): Phase 4 RCA agents MAY be instructed to delegate a bounded sub-problem to their declared sub-agents (e.g. code-quality-reviewer → security-auditor for a vulnerability hypothesis) instead of investigating everything inline. Keep chains ≤ 3 levels deep; independent hypotheses belong in the existing 5-agent parallel fan-out, not a serial chain. See chain-patterns Pattern 9 (CC 2.1.172+).

Post-Fix Monitoring (CC 2.1.71)

After Phase 11 (commit + PR), schedule CI monitoring:

# Guard: Skip cron in headless/CI (CLAUDE_CODE_DISABLE_CRON)
# if env CLAUDE_CODE_DISABLE_CRON is set, run a single check instead
CronCreate(
  schedule="*/5 * * * *",
  prompt="Check CI for PR #{pr_number}: gh pr checks {pr_number} --repo {repo}.
    All pass → CronDelete this job. Any fail → alert with details."
)

Worktree Cleanup (CC 2.1.72)

If worktree isolation was used in Phase 4, clean up after validation:

# After Phase 7 validation passes — exit worktree, keep branch for PR
ExitWorktree(action="keep")

Every EnterWorktree or isolation: "worktree" agent must have a matching cleanup. If agents used isolation: "worktree", they handle their own exit — but if the lead entered a worktree in Step 0, it must call ExitWorktree before Phase 11 commit.

Fix Pattern Memory

If memory MCP is available (from Step -1 probe), save the fix pattern:

if capabilities.memory:
  mcp__memory__create_entities([{
    name: "fix-pattern-{slug}",
    entityType: "fix-pattern",
    observations: [root_cause, fix_description, regression_test, issue_ref]
  }])

Full phase details: Load Read("references/fix-phases.md") for bash commands, templates, and procedures for each phase.

Critical Constraints

• Feature branch MANDATORY -- NEVER commit directly to main or dev
• Regression test MANDATORY -- write failing test BEFORE implementing fix
• Prevention required -- at least one of: automated test, validation rule, or process check
• Make minimal, focused changes; DO NOT over-engineer