fix-issue

What this skill does

# Fix Issue

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

## Quick Start

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

> **Opus 4.8**: 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

```python
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.

```python
# 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:

```bash
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-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:**

```python
# 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. Before starting each task, verify it's unblocked
task = TaskGet(taskId="2")  # Verify blockedBy is empty

# 5. 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** (default) | Full RCA: 5 parallel agents → fix → prevent → lessons | 5 agents | All 11 phases |
| **xhigh** (Opus 4.8, CC 2.1.111+) | Full RCA + extra regression-scan pass across sibling modules | 5 agents | All 11 phases + regression sweep |

> **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:

```python
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:

```python
# Skip when invocation flag is explicit:
#   /ork:fix-issue 123 --local-ci          → skip, run full suite locally
#   /ork:fix-issue 123 --security-only     → skip, security tests only
#   /ork: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:**

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

#