/fix-issue

description: "Fixes GitHub issues using parallel analysis agents for root cause investigation, code exploration, and regression detection. Reads issue context from gh CLI, searches codebase and memory for related patterns, generates a fix with tests, and links the resolution back to the issue via PR. Includes prevention analysis to avoid recurrence. Use when debugging errors, resolving regressions, fixing bugs, or triaging issues."
argument-hint: "[issue-number]"
model: sonnet
context: fork
user-invocable: true
name: fix-issue
background: false
allowed-tools: [SendMessage, AskUserQuestion, Bash, Read, Write, Edit, Agent, TaskCreate, TaskUpdate, TaskStop, Grep, Glob, ToolSearch, ExitWorktree, CronCreate, CronDelete, PushNotification, mcp__memory__search_nodes, mcp__context7__get_library_docs]

Auto-generated from skills/fix-issue/SKILL.md

Source: https://github.com/yonatangross/orchestkit

Fix Issue

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

Quick Start

/ork:fix-issue 123
/ork:fix-issue 456

> **Opus 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("${CLAUDE_PLUGIN_ROOT}/skills/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_PLUGIN_ROOT}/skills/fix-issue/scripts/prior_fix_lookup.py "$CLAUDE_JOB_DIR"

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

| Skip reason | Trigger | |-------------|---------| | `signal absent` | `error_text` missing OR signature extractor returns `None` | | `yg-mcp-core not importable` | `yg-mcp-core>=0.3.0` not installed (orchestkit is public; yg-mcp-core lives on private `pypi.yonyon.ai` — HQ-only) | | `memory MCP unreachable` | MCP server down OR `.mcp.json` doesn't define `memory` |

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.

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:

| Effort Level | Approach | Agents | Phases | |-------------|----------|--------|--------| | **low** | Quick fix: read → fix → test → done | 0 agents | 1, 6, 7, 11 | | **medium** | Standard: investigate → fix → test → prevent | 2-3 agents | 1-4, 6-8, 11 | | **high