/fix-issue

name: fix-issue
license: MIT
compatibility: "Claude Code 2.1.277+. Requires memory MCP server, context7 MCP server, gh CLI."
description: "Fixes a GitHub issue: parallel root-cause analysis, a fix with tests, a PR linked back to the issue, and prevention notes. Use when fixing a bug, regression or reported issue."
argument-hint: "[issue-number]"
context: fork
# user-typed commands stay interactive; CC >= 2.1.218 backgrounds forks by default (#3093)
background: false
user-invocable: true
allowed-tools: "SendMessage AskUserQuestion Bash Read Write Edit Agent TaskCreate TaskUpdate TaskStop Grep Glob ToolSearch ExitWorktree CronCreate CronDelete PushNotification mcp__memory__search_nodes mcp__memory__create_entities mcp__context7__resolve-library-id mcp__context7__query-docs"
skills: [explore, verify, memory, remember, chain-patterns]
model: sonnet
metadata:
  category: workflow-automation
  mcp-server: memory, context7
  version: "2.6.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "issue, bug-fix, github, debugging, rca, prevention"
triggers:
  keywords: [fix, debug, "bug report", broken, "500 errors", investigate, resolve, regression, "track down", "figure out why", "issue #"]
  examples:
    - "fix issue #234"
    - "there's a bug where users can't reset their passwords"
    - "something's causing 500 errors on the /api/users endpoint"
  anti-triggers: [implement, build, create, explore, review, brainstorm]
paths: ["src/**/*.{ts,tsx,js,jsx}", "package.json", "CLAUDE.md"]

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

**Check the target first, before any other step.** This skill forks and cannot see the conversation. Load `Read("../../shared/rules/target-resolution.md")`: if the target, flags stripped, is a bare pronoun or deictic (`this`, `them`, `that one`) or empty, return exactly `TARGET_UNRESOLVED: <word>` and stop. The caller resolves it and re-invokes.

ISSUE_NUMBER = "$ARGUMENTS" with the flags stripped  # the target the check above reads, e.g. "123"
# $ARGUMENTS contains the full argument string and may open with flags
# like --model=opus; indexing [0] would fetch the flag, not the issue.
# If the stripped target is not an issue number or URL, return
# TARGET_UNRESOLVED: <word> and stop.

STEP -1: MCP Probe + Resume Check

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

**Load the issue the target names first.** A fork skill never runs frontmatter hooks (#4683), so fetch `ISSUE_NUMBER` (the flags-stripped target, never `$ARGUMENTS[0]`) yourself and keep the result in mind. Do not call `skill/issue-context-loader` for this: it takes its number from the branch name, not from the argument, so on a branch like `fix/ork10-...` it loads a different issue. Use the CLI the M122 host note selects (`gh`, `glab`, or `bb`):

gh issue view "$ISSUE_NUMBER" --json title,body,labels,milestone,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):

| 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-di