---
title: "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."
---

<span className="badge badge-blue">Command</span> <span className="badge badge-yellow">medium</span>

```bash title="Invoke"
/ork:fix-issue
```

<ContextualSkillSidebar slug="fix-issue" />


# 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.6**: 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 &lt;session-dir&gt;` 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 plugins/ork/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 `&lt;Type&gt;: &lt;msg&gt;` errors to a `&lt;error_type&gt; &lt;primary_path&gt;:&lt;lineno&gt;` shape used as the `search_nodes` query. Handoff JSON at `&lt;session-dir&gt;/prior-fix-matches.json` records `status`, `signature`, and `matches_count`; the top-3 matches land in `&lt;session-dir&gt;/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.7 only, 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", "markdown": "```\nProper Fix (11 phases)\n──────────────────────\n  Understand ──▶ Hypothesize ──▶ RCA\n       │              │           │\n       ▼              ▼           ▼\n  5 parallel     Ranked       Confirmed\n  agents         hypotheses   root cause\n       │\n       ▼\n  Fix ──▶ Validate ──▶ Prevent ──▶ PR\n  + regression test   + runbook\n```"},
      {"label": "Quick fix", "description": "Minimal investigation, fix and test", "markdown": "```\nQuick Fix (~10 min)\n───────────────────\n  Read issue ──▶ Fix ──▶ Test ──▶ PR\n\n  Skip: full RCA, prevention plan,\n  runbook, lessons learned\n  Keep: regression test (mandatory)\n```"},
      {"label": "Investigate first", "description": "Deep analysis before deciding on approach", "markdown": "```\nInvestigate First\n─────────────────\n  Read issue ──▶ 5 parallel agents ──▶ Report\n\n  Output: Root cause analysis\n  + hypothesis ranking\n  + recommended approach\n  No code changes yet\n```"},
      {"label": "Hotfix", "description": "Emergency fix, minimal process", "markdown": "```\nHotfix (emergency)\n──────────────────\n  Read issue ──▶ Fix ──▶ Push\n\n  Skip: agents, RCA, prevention\n  Keep: basic test verification\n  Post-fix: schedule proper RCA\n```"}
    ],
    "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", "markdown": "```\nPush + Remote CI\n────────────────\n  fix ──▶ commit ──▶ push ──▶ CI\n                                │\n                                v\n                            5-15 min\n  + fastest local turnaround\n  - failures discovered remotely\n  - rebase if CI red on main move\n```"},
    {"label": "Run full suite locally first", "description": "~2-3 min extra; catches CI failures locally before push", "markdown": "```\nLocal Full Suite + Push\n───────────────────────\n  fix ──▶ commit ──▶ npm test ──▶ push\n                       │\n                       v\n                   ~2-3 min\n  + catches all CI failures locally\n  - slower per-iteration\n  recommended when issue label =\n  security | data-loss\n```"},
    {"label": "Run security tests only", "description": "~30s; covers the usual blocker class — secrets, deps, common vulns", "markdown": "```\nSecurity-only + Push\n────────────────────\n  fix ──▶ commit ──▶ test:security ──▶ push\n                          │\n                          v\n                       ~30s\n  + catches secrets/deps/owasp\n  + faster than full suite\n  - misses lint/type/unit issues\n```"}
  ]
}])
```

**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")

# 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("$\{CLAUDE_SKILL_DIR\}/rules/evidence-gathering.md")` for detailed workflow adjustments per approach.

## STEP 0b: Select Orchestration Mode

Choose **Agent Teams** (mesh) or **Task tool** (star). Load `Read("$\{CLAUDE_SKILL_DIR\}/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:

```bash
# 1. Discover services via Portless (preferred)
portless list 2>/dev/null
# api → api.localhost:1355   (port 8080)
# app → app.localhost:1355   (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 "http://app.localhost:1355"
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:1355`) in all investigation steps — they're stable, self-documenting, and eliminate port-guessing failures. Install with `npm i -g portless`.

## Workflow Overview

| Phase | Activities | Output |
|-------|------------|--------|
| **1. Understand Issue** | Read GitHub issue details | Problem statement |
| **1b. Service Discovery** | Portless list, agent-browser visual inspection | Service URLs, screenshots |
| **2. Similar Issue Detection** | Search for related past issues | Related issues list |
| **3. Hypothesis Formation** | Form hypotheses with confidence scores | Ranked hypotheses |
| **4. Root Cause Analysis** | 5 parallel agents investigate | Confirmed root cause |
| **5. Fix Design** | Design approach based on RCA | Fix specification |
| **6. Implementation** | Apply fix with tests | Working code |
| **7. Validation** | Verify fix resolves issue, screenshot after state | Evidence |
| **8. Prevention** | How to prevent recurrence | Prevention plan |
| **9. Runbook** | Create/update runbook entry | Runbook |
| **10. Lessons Learned** | Capture knowledge | Persisted learnings |
| **11. Commit and PR** | Create PR with fix | Merged PR |

### Progressive Output (CC 2.1.76)

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

| After Phase | Show User |
|-------------|-----------|
| 1. Understand Issue | Problem statement, affected files |
| 3. Hypothesis Formation | Ranked hypotheses with confidence scores |
| 4. RCA | Confirmed root cause, evidence chain |
| 6. Implementation | Fix description, files changed |
| 7. Validation | Test results, before/after behavior |

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.

| After Phase | Handoff File | Key Outputs |
|-------------|-------------|-------------|
| 3. Hypothesis | `03-hypotheses.json` | Ranked hypotheses with confidence scores |
| 4. RCA | `04-rca.json` | Confirmed root cause, evidence, affected files |
| 6. Implementation | `06-fix.json` | Fix description, files changed, test plan |
| 7. Validation | `07-validation.json` | Test results, coverage delta |

### Worktree-Isolated RCA Agents (CC 2.1.50)

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

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

### Post-Fix Monitoring (CC 2.1.71)

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

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

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

```python
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("$\{CLAUDE_SKILL_DIR\}/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

## CC 2.1.49 Enhancements

> Load `Read("$\{CLAUDE_SKILL_DIR\}/references/cc-enhancements.md")` for session resume, task metrics, tool guidance, worktree isolation, and adaptive thinking.

## Rules Quick Reference

| Rule | Impact | What It Covers |
|------|--------|----------------|
| evidence-gathering (load `$\{CLAUDE_SKILL_DIR\}/rules/evidence-gathering.md`) | HIGH | User intent verification, confidence scale, key decisions |
| rca-five-whys (load `$\{CLAUDE_SKILL_DIR\}/rules/rca-five-whys.md`) | HIGH | 5 Whys iterative causal analysis |
| rca-fishbone (load `$\{CLAUDE_SKILL_DIR\}/rules/rca-fishbone.md`) | MEDIUM | Ishikawa diagram, multi-factor analysis |
| rca-fault-tree (load `$\{CLAUDE_SKILL_DIR\}/rules/rca-fault-tree.md`) | MEDIUM | Fault tree analysis, AND/OR gates, critical systems |

> **Push notifications (CC 2.1.110+):** Issue-fix flows can span 10–20 min with RCA → fix → test → PR. When the fix lands and tests pass, call `PushNotification` so the user knows the fix is ready for review. Requires Remote Control + "Push when Claude decides" config; fails silently if unavailable.
>
> ```python
> PushNotification(
>   title="ork:fix-issue complete",
>   body=f"#\{issue_number\}: fix pushed, \{tests_passing\}/\{tests_total\} tests · PR #\{pr_number\}"
> )
> ```

## Agent Coordination

### Dispatch envelope (CC 2.1.142+ flags — M146-6 / #1849)

When spawning the 5 RCA agents (debug-investigator, code-quality-reviewer, test-generator, etc.) — whether in-session via the `Agent` tool or headless via `claude -p --bare` — set explicit per-role flags so behaviour is deterministic across interactive and CI runs:

| Agent role | `--permission-mode` | `--effort` |
|---|---|---|
| RCA / investigation (`debug-investigator`, `Explore`) | `dontAsk` | `low` — `medium` |
| Test reproduction (`test-generator`) | `acceptEdits` | `medium` |
| Fix authoring (production code) | `default` (keep user in loop) | `medium` — `high` |
| Verification (`code-quality-reviewer`) | `dontAsk` | `low` |

**Never** use `bypassPermissions` — fix-issue's RCA phase often touches code paths; the audit trail matters. For headless invocations (e.g. from `/ork:ci-sentinel` or a cron-driven bug sweep), pass the flags explicitly:

```bash
claude -p --bare \
  --permission-mode dontAsk \
  --effort medium \
  --max-turns 12 \
  "/ork:fix-issue <N>"
```

### SendMessage (Evidence Sharing)

When an RCA agent discovers the root cause, share with the fix agent:

```python
SendMessage(to="debug-investigator", message="Root cause: race condition in cache invalidation — see git blame for commit abc123")
```

### Context Passing

All 5 RCA agents receive: issue description, ranked hypotheses, reproduction steps, and affected file paths — not just "investigate issue #N".

### Skill Chain

After fix is applied: `TaskCreate(subject="Verify fix", addBlockedBy=[fix_task_id])` → `/ork:verify`.

### Verification Gate

Before claiming any fix is complete, apply the 5-step verification gate: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/shared/rules/verification-gate.md")`. "Should work now" is not evidence — run the test, read the output, cite the result.

### Response Protocol

When reporting fix status, follow `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/shared/rules/anti-sycophancy.md")` — state findings directly, no performative language. Use the agent status protocol: DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT.

## Related Skills

- `ork:commit` - Commit issue fixes
- `debug-investigator` - Debug complex issues
- `browser-tools` - Visual inspection with agent-browser + Portless
- `ork:issue-progress-tracking` - Auto-updates from commits
- `ork:remember` - Store lessons learned

> **Session recovery (CC 2.1.108+):** After idle periods or interruptions, use `/recap` to restore conversational context alongside checkpoint-resume state. Enabled by default since CC 2.1.110 (even with telemetry disabled).

## Picker fallback (#1795)

If the `AskUserQuestion` picker stalls (CC 2.1.139 input bug — orchestkit#1795), set `ORK_ASK_FALLBACK=text` before starting CC. The `lifecycle/ask-fallback-injector` hook injects a reminder telling the assistant to pose options inline as a numbered list and ask the user to reply with the option number.

## References

Load on demand with `Read("$\{CLAUDE_SKILL_DIR\}/references/&lt;file&gt;")`:
| File | Content |
|------|---------|
| `fix-phases.md` | Bash commands, templates, procedures per phase |
| `agent-selection.md` | Orchestration mode selection criteria and cost comparison |
| `similar-issue-search.md` | Similar issue detection patterns |
| `hypothesis-rca.md` | Hypothesis-based root cause analysis |
| `agent-teams-rca.md` | Agent Teams RCA workflow |
| `prevention-patterns.md` | Recurrence prevention patterns |
| `cc-enhancements.md` | CC 2.1.49 session resume, task metrics, adaptive thinking |

---

**Version:** 2.4.0 (March 2026) — Rich elicitation with options for fix approach, progressive output for incremental phase results


---

## Rules (4)

### Evidence Gathering — HIGH


# Evidence Gathering Patterns

## Verify User Intent (STEP 0)

**BEFORE creating tasks**, clarify fix approach with AskUserQuestion:

```python
AskUserQuestion(
  questions=[{
    "question": "What approach for this fix?",
    "header": "Approach",
    "options": [
      {"label": "Proper fix (Recommended)", "description": "Full RCA, tests, prevention recommendations", "markdown": "```\nProper Fix (11 phases)\n──────────────────────\n  Issue ──▶ RCA ──▶ Fix ──▶ Prevent\n  ┌─────┐  ┌─────┐  ┌─────┐  ┌───────┐\n  │Read │  │5-Why│  │Code │  │Tests  │\n  │issue│  │Fish │  │impl │  │Runbook│\n  │+hist│  │bone │  │+test│  │Lessons│\n  └─────┘  └─────┘  └─────┘  └───────┘\n  5 parallel agents for RCA\n  Regression test BEFORE fix\n  Prevention + lessons learned\n```"},
      {"label": "Quick fix", "description": "Minimal fix to resolve the immediate issue", "markdown": "```\nQuick Fix (phases 1-7)\n──────────────────────\n  Issue ──▶ Diagnose ──▶ Fix\n  ┌─────┐   ┌────────┐  ┌─────┐\n  │Read │   │Focused │  │Code │\n  │issue│   │RCA     │  │+test│\n  └─────┘   └────────┘  └─────┘\n  Skip: prevention, runbook,\n  lessons learned phases\n  Still requires regression test\n```"},
      {"label": "Investigate first", "description": "Understand the issue before deciding on approach", "markdown": "```\nInvestigate Only (phases 1-4)\n─────────────────────────────\n  Issue ──▶ Search ──▶ Hypotheses\n  ┌─────┐  ┌──────┐  ┌──────────┐\n  │Read │  │Find  │  │Rank by   │\n  │issue│  │similar│  │confidence│\n  └─────┘  └──────┘  └──────────┘\n  Output: Root cause analysis\n  NO code changes made\n  Decide approach after findings\n```"},
      {"label": "Hotfix", "description": "Emergency patch, minimal testing", "markdown": "```\nHotfix (minimal)\n────────────────\n  Issue ──▶ Fix ──▶ Ship\n  ┌─────┐  ┌────┐  ┌────┐\n  │Skim │  │Min │  │Push│\n  │issue│  │fix │  │now │\n  └─────┘  └────┘  └────┘\n  Skip: similar issue search,\n  deep RCA, prevention\n  ⚠ Follow up with proper fix\n```"},
      {"label": "Plan first", "description": "Investigate root cause in plan mode before fixing", "markdown": "```\nPlan Mode Investigation\n──────────────────────\n  1. EnterPlanMode("Issue #$ISSUE")\n  2. Read issue + repro\n  3. Trace code paths\n  4. Identify root cause\n  5. ExitPlanMode → fix plan\n  6. User approves approach\n  7. Implement fix + tests\n\n  Best for: Complex bugs,\n  regressions, multi-file fixes\n```"}
    ],
    "multiSelect": false
  }]
)
```

**If 'Plan first' selected:** Call `EnterPlanMode("Investigate issue #$ISSUE: $TITLE")`, perform research using Read/Grep/Glob only, then `ExitPlanMode` with the plan for user approval before proceeding.

**Based on answer, adjust workflow:**
- **Proper fix**: All 11 phases, parallel agents for RCA
- **Quick fix**: Skip phases 8-10 (prevention, runbook, lessons)
- **Investigate first**: Only phases 1-4 (understand, search, hypotheses, analyze)
- **Hotfix**: Minimal phases, skip similar issue search

**Incorrect:**
```python
# Jump straight to code without understanding the issue
Edit(file_path="src/auth.py", old_string="return token", new_string="return new_token")
```

**Correct:**
```python
# Gather evidence first: read issue, search codebase, form hypotheses
Read(file_path="src/auth.py")
Grep(pattern="token.*expir", path="src/")
# Hypothesis: token refresh skips validation (confidence: 75%)
```

## Hypothesis Confidence Scale

| Confidence | Meaning |
|------------|---------|
| 90-100% | Near certain |
| 70-89% | Highly likely |
| 50-69% | Probable |
| 30-49% | Possible |
| 0-29% | Unlikely |

## Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Feature branch | MANDATORY | Never commit to main/dev directly |
| Regression test | MANDATORY | Fix without test is incomplete |
| Hypothesis confidence | 0-100% scale | Quantifies certainty |
| Similar issue search | Before hypothesis | Leverage past solutions |
| Prevention analysis | Mandatory phase | Break recurring issue cycle |
| Runbook generation | Template-based | Consistent documentation |


### Map all failure paths with fault tree analysis to prevent recurring system failures — MEDIUM


## Fault Tree Analysis (FTA)

Top-down, deductive analysis mapping all paths to a failure using boolean logic (AND/OR gates). Best for critical systems and exhaustive failure analysis.

### FTA Symbols

| Symbol | Meaning |
|--------|---------|
| TOP | Top event — the failure being analyzed |
| AND | All inputs must occur for output |
| OR | Any input causes output |
| Basic Event | Root cause (leaf node) |
| Undeveloped | Needs further analysis |

### Example: Authentication Failure

```
                USER CANNOT
                AUTHENTICATE
                     |
                   [OR]
        +------------+------------+
        |            |            |
    Invalid      Auth Service   Account
   Credentials     Down         Locked
        |            |
      [OR]         [OR]
    +---+---+    +---+---+
    |   |   |    |   |   |
   Wrong Expired Token DB  Redis External
   Pass  Token  Invalid Down Down  Auth
```

### Building a Fault Tree

1. **Define top event** — the failure to analyze
2. **Ask "what causes this?"** — list immediate causes
3. **Classify as AND/OR** — do ALL causes need to happen, or ANY one?
4. **Decompose each cause** — repeat until reaching basic events
5. **Identify minimal cut sets** — smallest combinations that cause failure
6. **Prioritize by probability** — most likely paths first

### Minimal Cut Sets

The smallest set of basic events that together cause the top event:

```
Top: User Cannot Authenticate (OR gate)
  Cut Set 1: {Wrong Password}         — single point of failure
  Cut Set 2: {Expired Token}          — single point of failure
  Cut Set 3: {DB Down}                — single point of failure
  Cut Set 4: {Account Locked}         — single point of failure
```

Single-event cut sets indicate **no redundancy** — add defense-in-depth.

### When to Use FTA

| Scenario | Use FTA? |
|----------|----------|
| Safety-critical system failure | Yes |
| Need exhaustive failure path mapping | Yes |
| Complex multi-component failure | Yes |
| Simple linear bug | No — use 5 Whys |
| Multiple contributing factors | Maybe — Fishbone first |
| Regulatory compliance analysis | Yes |
| Post-incident for serious outages | Yes |

**Incorrect — stopping at high-level causes without decomposition:**
```
USER CANNOT AUTHENTICATE
         |
       [OR]
    +----+----+
    |         |
Auth Service  Account
   Down       Locked
```

**Correct — decompose to basic events with AND/OR gates:**
```
                USER CANNOT
                AUTHENTICATE
                     |
                   [OR]
        +------------+------------+
        |            |            |
    Invalid      Auth Service   Account
   Credentials     Down         Locked
        |            |
      [OR]         [OR]
    +---+---+    +---+---+
    |   |   |    |   |   |
   Wrong Expired Token DB  Redis External
   Pass  Token  Invalid Down Down  Auth

Minimal Cut Sets identified:
  {Wrong Password}, {Expired Token}, {DB Down}, {Account Locked}
  → All single-event cuts = no redundancy, needs defense-in-depth
```

### Key Rules

- Start from the **top event** (failure) and work **downward**
- Every gate must be classified as **AND** (all required) or **OR** (any sufficient)
- Decompose until reaching **basic events** (actionable root causes)
- Identify **minimal cut sets** to find the most vulnerable paths
- Single-event cut sets indicate **missing redundancy**
- Use for **critical systems** where exhaustive analysis is justified


### Analyze multi-factor problems with fishbone diagrams to avoid single-cause fixation — MEDIUM


## Fishbone Diagram (Ishikawa)

Visualize multiple potential causes organized by category. Best for problems with several contributing factors.

### Software-Specific Categories

```
                    +-------------+
          Code -----+             |
                    |             |
 Infrastructure ----+             +---- BUG/INCIDENT
                    |             |
   Dependencies ----+             |
                    |             |
   Configuration ---+             |
                    |             |
        Process ----+             |
                    |             |
        People -----+             |
                    +-------------+
```

### Example: API Latency Spike

| Category | Potential Causes |
|----------|-----------------|
| **Code** | N+1 query, missing index, sync blocking call |
| **Infrastructure** | DB connection pool exhausted, network saturation, insufficient RAM |
| **Dependencies** | External API slow, Redis timeout, CDN cache miss |
| **Configuration** | Wrong pool size, missing timeout, debug logging on |
| **Process** | No load testing, no perf regression CI |
| **People** | Unfamiliarity with query optimizer, missing review |

### Fishbone Process

1. **Define the problem** clearly (the fish head)
2. **Identify major categories** (the bones) — use software categories above
3. **Brainstorm causes** for each category
4. **Analyze relationships** between causes across categories
5. **Prioritize** most likely root causes by evidence
6. **Verify** with data, metrics, or targeted testing
7. **Take action** on confirmed causes

### When to Use Fishbone

| Scenario | Use Fishbone? |
|----------|---------------|
| Multiple things went wrong | Yes |
| Problem has one clear cause | No — use 5 Whys |
| Team brainstorming session | Yes |
| Safety-critical failure analysis | No — use Fault Tree |
| Recurring issue with no clear pattern | Yes |

**Incorrect — jumping to one cause without category analysis:**
```markdown
### API Latency Spike Analysis

**Root Cause:** N+1 query in user endpoint
**Fix:** Add query optimization
```

**Correct — fishbone analysis across all categories:**
```markdown
### API Latency Spike — Fishbone Analysis

**Code:**
- N+1 query in user endpoint (CONFIRMED via query log)
- Sync blocking call to external API

**Infrastructure:**
- DB connection pool exhausted (CONFIRMED: 0 available connections)
- Network saturation (ruled out: 20% utilization)

**Dependencies:**
- Redis timeout increased (ruled out: within SLA)

**Configuration:**
- Connection pool size too small (CONFIRMED: 10 max, need 50)

**Process:**
- No load testing in CI (process gap)

**Root Causes (cross-category):**
1. N+1 query (Code) + small pool (Config) = exhaustion
2. Missing load tests (Process) = undetected before prod

**Actions:**
- Fix N+1 query immediately
- Increase pool size 10 → 50
- Add load tests to CI
```

### Key Rules

- Use **software-specific categories** (Code, Infrastructure, Dependencies, Configuration, Process, People)
- Brainstorm causes per category **before** analyzing relationships
- Look for **cross-category interactions** (e.g., code + config)
- **Prioritize by evidence**, not by assumption
- Verify top candidates with **data or experiments** before committing to a fix


### Apply the 5 Whys technique to reach root causes instead of fixing symptoms — HIGH


## 5 Whys Technique

Iteratively ask "why" to drill down from symptom to root cause. Simple, fast, and effective for linear causal chains.

### Process

```
Problem Statement: [Clear description of the issue]
    |
    v
Why #1: [First level cause]
    |
    v
Why #2: [Deeper cause]
    |
    v
Why #3: [Even deeper]
    |
    v
Why #4: [Getting to root]
    |
    v
Why #5: [Root cause identified]
    |
    v
Action: [Fix that addresses root cause]
```

### Example: Production Outage

```markdown
**Problem:** Website was down for 2 hours

**Why 1:** The application server ran out of memory and crashed.
**Why 2:** A memory leak in the image processing service accumulated over time.
**Why 3:** The service wasn't releasing image buffers after processing.
**Why 4:** The cleanup code had a bug introduced in last week's release.
**Why 5:** We don't have automated memory leak detection in our test suite.

**Root Cause:** Missing automated memory leak testing
**Action:** Add memory profiling to CI pipeline, add cleanup tests
```

### Best Practices

| Do | Don't |
|----|-------|
| Base answers on evidence | Guess or assume |
| Stay focused on one causal chain | Branch too early |
| Keep asking until actionable | Stop at symptoms |
| Involve people closest to issue | Assign blame |
| Document your reasoning | Skip steps |

### When 5 Whys Falls Short

- **Multiple contributing factors** — use Fishbone diagram instead
- **Complex system interactions** — use Fault Tree Analysis
- **Organizational/process issues** — needs broader systemic analysis
- **Concurrent failures** — 5 Whys assumes linear causation

**Incorrect — stopping at symptom without root cause:**
```markdown
**Problem:** Website was down for 2 hours

**Why 1:** The application server crashed.
**Action:** Restart the server
```

**Correct — drilling down to root cause with 5 Whys:**
```markdown
**Problem:** Website was down for 2 hours

**Why 1:** The application server ran out of memory and crashed.
  Evidence: Out-of-memory error in logs

**Why 2:** A memory leak in the image processing service accumulated over time.
  Evidence: Memory usage increased 2GB/hour in metrics

**Why 3:** The service wasn't releasing image buffers after processing.
  Evidence: Code review shows missing .dispose() calls

**Why 4:** The cleanup code had a bug introduced in last week's release.
  Evidence: Git blame + diff shows removal of cleanup in PR #234

**Why 5:** We don't have automated memory leak detection in our test suite.
  Evidence: No memory profiling in CI pipeline

**Root Cause:** Missing automated memory leak testing
**Actions:**
- Add memory profiling to CI pipeline
- Add cleanup tests for image processing
- Revert PR #234's cleanup removal
```

### Key Rules

- Always start with a **clear, specific problem statement**
- Each "why" must be **supported by evidence** (logs, metrics, code)
- Stop when you reach an **actionable root cause** (not always exactly 5)
- The fix should address the **root cause**, not the symptom
- Document the full chain for **knowledge sharing**



---

## References (7)

### Agent Selection

# Agent Selection & Orchestration Mode

## Orchestration Mode Selection

Choose **Agent Teams** (mesh -- RCA agents share hypotheses) or **Task tool** (star -- all report to lead):

1. Agent Teams mode (GA since CC 2.1.33) -> **recommended for cross-cutting bugs** (backend + frontend + tests)
2. Task tool mode -> **for focused single-domain bugs**
3. `ORCHESTKIT_FORCE_TASK_TOOL=1` -> **Task tool** (override)

| Aspect | Task Tool | Agent Teams |
|--------|-----------|-------------|
| Hypothesis sharing | Lead relays between agents | Investigators share hypotheses in real-time |
| Conflicting evidence | Lead resolves | Investigators debate directly |
| Cost | ~250K tokens | ~600K tokens |
| Best for | Single-domain bugs | Cross-cutting bugs with multiple hypotheses |

> **Fallback:** If Agent Teams encounters issues, fall back to Task tool for remaining investigation.

## RCA Agent Roster (Phase 4)

Launch ALL 5 agents in parallel with `run_in_background=True` and `max_turns=25`:

| # | Agent | Role |
|---|-------|------|
| 1 | debug-investigator | Root cause tracing |
| 2 | debug-investigator | Impact analysis |
| 3 | backend-system-architect | Backend fix design |
| 4 | frontend-ui-developer | Frontend fix design |
| 5 | test-generator | Test requirements |

Each agent outputs structured JSON with findings and SUMMARY line.

## Task Management (CC 2.1.16)

```python
# Create main fix task
TaskCreate(
  subject="Fix issue #{number}",
  description="Systematic issue resolution with hypothesis-based RCA",
  activeForm="Fixing issue #{number}"
)

# Create subtasks for 11-phase process
phases = ["Understand issue", "Search similar issues", "Form hypotheses",
          "Analyze root cause", "Design fix", "Implement fix", "Validate fix",
          "Generate prevention", "Create runbook", "Capture lessons", "Commit and PR"]
for phase in phases:
    TaskCreate(subject=phase, activeForm=f"{phase}ing")
```


### Agent Teams Rca

# Agent Teams RCA Workflow

In Agent Teams mode, form an investigation team where RCA agents share hypotheses and evidence in real-time:

```python
TeamCreate(team_name="fix-issue-{number}", description="RCA for issue #{number}")

Agent(subagent_type="debug-investigator", name="root-cause-tracer",
     team_name="fix-issue-{number}",
     prompt="""Trace the root cause for issue #{number}: {issue description}
     Hypotheses: {hypothesis list from Phase 3}
     Test each hypothesis. When you find evidence supporting or refuting a hypothesis,
     message impact-analyst and the relevant domain expert (backend-expert or frontend-expert).
     If you find conflicting evidence, share it with ALL teammates for debate.""")

Agent(subagent_type="debug-investigator", name="impact-analyst",
     team_name="fix-issue-{number}",
     prompt="""Analyze the impact and blast radius for issue #{number}.
     When root-cause-tracer shares evidence, assess how many code paths are affected.
     Message test-planner with affected paths so they can plan regression tests.
     If the impact is larger than expected, message the lead immediately.""")

Agent(subagent_type="backend-system-architect", name="backend-expert",
     team_name="fix-issue-{number}",
     prompt="""Investigate backend aspects of issue #{number}.
     When root-cause-tracer shares backend-related hypotheses, design the fix approach.
     Message frontend-expert if the fix affects API contracts.
     Share fix design with test-planner for test requirements.""")

Agent(subagent_type="frontend-ui-developer", name="frontend-expert",
     team_name="fix-issue-{number}",
     prompt="""Investigate frontend aspects of issue #{number}.
     When root-cause-tracer shares frontend-related hypotheses, design the fix approach.
     If backend-expert changes API contracts, adapt the frontend fix accordingly.
     Share component changes with test-planner.""")

Agent(subagent_type="test-generator", name="test-planner",
     team_name="fix-issue-{number}",
     prompt="""Plan regression tests for issue #{number}.
     When root-cause-tracer confirms the root cause, write a failing test that reproduces it.
     When backend-expert or frontend-expert share fix designs, plan verification tests.
     Start with the regression test BEFORE the fix is applied (TDD approach).""")
```

**Team teardown** after fix is implemented and validated:
```python
SendMessage(type="shutdown_request", recipient="root-cause-tracer", content="Fix validated")
SendMessage(type="shutdown_request", recipient="impact-analyst", content="Fix validated")
SendMessage(type="shutdown_request", recipient="backend-expert", content="Fix validated")
SendMessage(type="shutdown_request", recipient="frontend-expert", content="Fix validated")
SendMessage(type="shutdown_request", recipient="test-planner", content="Fix validated")
TeamDelete()

# Worktree cleanup (CC 2.1.72)
ExitWorktree(action="keep")
```

> **Fallback:** If team formation fails, use standard Phase 4 Task spawns.


### Cc Enhancements

# CC 2.1.27+ Enhancements for Fix Issue

## Session Resume with PR Context

When you create a PR for the fix, the session is automatically linked:

```bash
# Later: Resume with full PR context
claude --from-pr 789
```

## Task Metrics (CC 2.1.30)

Track RCA efficiency across the 5 parallel agents:

```markdown
## Phase 4 Metrics (Root Cause Analysis)
| Agent | Tokens | Tools | Duration |
|-------|--------|-------|----------|
| debug-investigator #1 | 520 | 12 | 18s |
| debug-investigator #2 | 480 | 10 | 15s |
| backend-system-architect | 390 | 8 | 12s |

**Root cause found in:** 45s total
```

## Tool Guidance (CC 2.1.31)

When investigating root cause:

| Task | Use | Avoid |
|------|-----|-------|
| Read logs/files | `Read(file_path=...)` | `bash cat` |
| Search for errors | `Grep(pattern="ERROR")` | `bash grep` |
| Find affected files | `Glob(pattern="**/*.py")` | `bash find` |
| Check git history | `Bash git log/diff` | (git needs bash) |

## Session Resume Hints (CC 2.1.31)

Before ending fix sessions, capture investigation context:

```bash
/ork:remember Issue #$ARGUMENTS RCA findings:
  Root cause: [one line]
  Confirmed by: [key evidence]
  Fix status: [implemented/pending]
  Prevention: [recommendation]
```

Resume later:
```bash
claude                              # Shows resume hint
/ork:memory search "issue $ARGUMENTS"  # Loads your findings
```


### Fix Phases

# Fix Issue: 11-Phase Workflow

Detailed procedures for each phase of the fix-issue workflow.

---

## Phase 1: Understand the Issue

```bash
gh issue view $ARGUMENTS --json title,body,labels,assignees,comments
gh pr list --search "issue:$ARGUMENTS"
gh issue view $ARGUMENTS --comments
```

**Start Work ceremony** (from `issue-progress-tracking`): move issue to in-progress, comment on issue, ensure branch is named `issue/N-description`.

---

## Phase 2: Similar Issue Detection

See [Similar Issue Search](similar-issue-search.md) for patterns.

```bash
gh issue list --search "[key error message]" --state all
mcp__memory__search_nodes(query="issue [error type] fix")
```

| Similar Issue | Similarity | Status | Relevant? |
|---------------|------------|--------|-----------|
| #101 | 85% | Closed | Yes |

**Determine:** Regression? Variant? New issue?

---

## Phase 3: Hypothesis Formation

See [Hypothesis-Based RCA](hypothesis-rca.md) for confidence scoring.

```markdown
## Hypothesis 1: [Brief name]
**Confidence:** [0-100]%
**Description:** [What might cause the issue]
**Test:** [How to verify]
```

| Confidence | Meaning |
|------------|---------|
| 90-100% | Near certain |
| 70-89% | Highly likely |
| 50-69% | Probable |
| 30-49% | Possible |
| 0-29% | Unlikely |

---

## Phase 4: Root Cause Analysis (5 Agents)

Launch ALL 5 agents in ONE message with `run_in_background=True` and `max_turns=25`.

Agents that edit files SHOULD use `isolation: "worktree"` to prevent conflicts:

```python
# PARALLEL — All 5 in ONE message
Agent(
  subagent_type="debug-investigator",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  ROOT CAUSE TRACING

  1. Trace the code path that triggers the bug
  2. Identify the exact line/condition causing the failure
  3. Check git blame for when the bug was introduced

  SUMMARY: End with: "RESULT: Root cause is [X] in [file:line] — introduced in [commit]"

  Issue: #$ARGUMENTS
  Investigate the primary hypothesis: {hypothesis_1}
  Evidence files: {relevant_files}
  """,
  isolation="worktree",
  run_in_background=True,
  max_turns=25
)
Agent(
  subagent_type="debug-investigator",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  IMPACT ANALYSIS

  Assess the blast radius of the confirmed root cause:
  1. What other code paths are affected?
  2. Are there similar patterns elsewhere that might have the same bug?
  3. What's the user-facing impact scope?

  SUMMARY: End with: "RESULT: Impact scope: [N] files, [M] code paths affected"

  Issue: #$ARGUMENTS
  Evidence files: {relevant_files}
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  subagent_type="backend-system-architect",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  BACKEND FIX DESIGN

  Design the fix approach for the backend:
  1. Propose minimal code changes to resolve the root cause
  2. Identify edge cases the fix must handle
  3. Assess risk of regression

  SUMMARY: End with: "RESULT: Fix requires changes to [N] files — risk: [low/medium/high]"

  Issue: #$ARGUMENTS
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  subagent_type="frontend-ui-developer",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  FRONTEND FIX DESIGN

  Design the fix approach for the frontend (if applicable):
  1. UI/UX impact of the bug and proposed fix
  2. Component changes needed
  3. Accessibility implications

  SUMMARY: End with: "RESULT: Frontend [affected/not affected] — [N] components to update"

  Issue: #$ARGUMENTS
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  subagent_type="test-generator",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  TEST REQUIREMENTS

  Define the test plan for the fix:
  1. Write a FAILING regression test that reproduces the bug
  2. Identify edge cases that must be covered
  3. Match test types to the fix using the Test Requirements Matrix

  SUMMARY: End with: "RESULT: [N] tests needed — regression test targets [file:function]"

  Issue: #$ARGUMENTS
  """,
  run_in_background=True,
  max_turns=25
)
```

Each agent outputs structured findings and a SUMMARY line.

### Agent Teams Alternative

> See [agent-teams-rca.md](agent-teams-rca.md) for Agent Teams root cause analysis workflow.

---

## Phase 5: Fix Design

```markdown
## Fix Design for Issue #$ARGUMENTS

### Root Cause (Confirmed)
[Description]

### Proposed Fix
[Approach]

### Files to Modify
| File | Change | Reason |
|------|--------|--------|
| [file] | MODIFY | [why] |

### Risks
- [Risk 1]

### Rollback Plan
[How to revert]
```

---

## Phase 6: Implementation

### CRITICAL: Feature Branch Required

**NEVER commit directly to main or dev.** Always create a feature branch:

```bash
# Determine base branch
BASE_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d: -f2 | tr -d ' ')

# Create feature branch (MANDATORY)
git checkout $BASE_BRANCH && git pull origin $BASE_BRANCH
git checkout -b issue/$ARGUMENTS-fix
```

### CRITICAL: Regression Test Required

**A fix without a test is incomplete.** Add test BEFORE implementing fix:

```bash
# 1. Write test that reproduces the bug (should FAIL)
# 2. Implement the fix
# 3. Verify test now PASSES
```

**Guidelines:**
- Make minimal, focused changes
- Add proper error handling
- Add regression test FIRST (MANDATORY)
- DO NOT over-engineer
- DO NOT commit directly to protected branches

---

## Phase 7: Validation

```bash
# Backend
poetry run ruff format --check app/
poetry run pytest tests/unit/ -v --tb=short

# Frontend
npm run lint && npm run typecheck && npm run test
```

---

## Phase 8: Prevention Recommendations

**CRITICAL: Prevention must include at least one of:**
1. **Automated test** - CI catches similar issues (PREFERRED)
2. **Validation rule** - Schema/lint rule prevents bad state
3. **Process check** - Review checklist item

See [Prevention Patterns](prevention-patterns.md) for full template.

| Category | Examples | Effectiveness |
|----------|----------|---------------|
| **Automated test** | Unit/integration test in CI | HIGH - catches before merge |
| **Validation rule** | Schema check, lint rule | HIGH - catches on save/commit |
| Architecture | Better error boundaries | MEDIUM |
| Process | Review checklist item | LOW - human-dependent |

---

## Phase 9: Runbook Generation

```markdown
# Runbook: [Issue Type]

## Symptoms
- [Observable symptom]

## Diagnosis Steps
1. Check [X] by running: `[command]`

## Resolution Steps
1. [Step 1]

## Prevention
- [How to prevent]
```

Store in memory for future reference.

---

## Phase 10: Lessons Learned

```python
mcp__memory__create_entities(entities=[{
  "name": "lessons-issue-$ARGUMENTS",
  "entityType": "LessonsLearned",
  "observations": [
    "root_cause: [brief]",
    "key_learning: [most important]",
    "prevention: [recommendation]"
  ]
}])
```

---

## Phase 11: Commit and PR

```bash
git add .
git commit -m "fix(#$ARGUMENTS): [Brief description]

Root cause: [one line]
Prevention: [recommendation]"

git push -u origin issue/$ARGUMENTS-fix
gh pr create --base dev --title "fix(#$ARGUMENTS): [description]"
```


### Hypothesis Rca

# Hypothesis-Based Root Cause Analysis

Scientific method for identifying root causes with quantified confidence.

## The Scientific Method for RCA

```
1. Observe symptoms
2. Form hypotheses
3. Gather evidence
4. Test hypotheses
5. Confirm or reject
6. Repeat until root cause found
```

## Hypothesis Template

```markdown
## Hypothesis: [Brief name]
**Confidence:** [0-100]%

**Description:**
[What might be causing the issue]

**Evidence For:**
- [Supporting evidence 1]
- [Supporting evidence 2]

**Evidence Against:**
- [Contradicting evidence 1]

**Test Plan:**
1. [Step to verify/refute]
2. [Expected outcome if true]
```

## Confidence Score Guidelines

| Score | Meaning | Evidence Required |
|-------|---------|-------------------|
| 90-100% | Near certain | Reproduction + multiple strong evidence |
| 70-89% | Highly likely | Clear evidence, logical chain |
| 50-69% | Probable | Some evidence, plausible mechanism |
| 30-49% | Possible | Limited evidence, needs investigation |
| 0-29% | Unlikely | Weak evidence, backup hypothesis |

## Evidence Classification

| Type | Weight | Examples |
|------|--------|----------|
| **Reproduction** | +30% | Consistent reproduction steps |
| **Code trace** | +20% | Stack trace to specific line |
| **Timing correlation** | +15% | Issue appeared after deployment X |
| **Log evidence** | +15% | Error messages match hypothesis |
| **Similar patterns** | +10% | Same error in related code |
| **User report** | +5% | Consistent user descriptions |

## Contradicting Evidence

| Evidence | Weight |
|----------|--------|
| Hypothesis disproven by test | -40% |
| Works in same conditions | -25% |
| Unrelated timing | -15% |
| No supporting logs | -10% |

## Multiple Hypothesis Comparison

```markdown
| Hypothesis | Initial | After Test | Status |
|------------|---------|------------|--------|
| Race condition | 65% | 85% | INVESTIGATING |
| Null reference | 40% | 15% | REJECTED |
| Cache stale | 30% | 30% | ON HOLD |
```

## Best Practices

1. **Start with 3+ hypotheses** - Avoid tunnel vision
2. **Test highest confidence first** - Efficient investigation
3. **Update scores after each test** - Track progress
4. **Document rejected hypotheses** - Prevent repeated investigation
5. **Look for evidence against** - Avoid confirmation bias


### Prevention Patterns

# Prevention Patterns

Strategies to prevent issue recurrence by category.

## Code-Level Prevention

| Issue Type | Prevention Pattern |
|------------|-------------------|
| Null/undefined | Optional chaining, nullish coalescing |
| Type errors | Strict TypeScript, runtime validation |
| Input validation | Zod schemas at boundaries |
| Error handling | Result types, explicit error states |
| Race conditions | Locks, atomic operations, idempotency |
| Memory leaks | Cleanup in useEffect, WeakRef |

```typescript
// Before: Vulnerable
const name = user.profile.name;

// After: Defensive
const name = user?.profile?.name ?? 'Unknown';
```

## Architecture-Level Prevention

| Issue Type | Prevention Pattern |
|------------|-------------------|
| Cascading failures | Circuit breakers |
| Network instability | Retry with backoff |
| Data inconsistency | Transactions, saga pattern |
| Timeout issues | Request deadlines, cancellation |
| Resource exhaustion | Rate limiting, pooling |

```python
# Circuit breaker example
@circuit_breaker(failure_threshold=5, recovery_timeout=30)
async def external_api_call():
    ...
```

## Process-Level Prevention

| Issue Type | Prevention Pattern |
|------------|-------------------|
| Logic errors | Mandatory PR review |
| Missing tests | Coverage requirements (>80%) |
| Regression | Required regression test before fix |
| Knowledge gaps | ADR for decisions |
| Onboarding issues | Runbook documentation |

## Tooling-Level Prevention

| Issue Type | Prevention Pattern |
|------------|-------------------|
| Style issues | ESLint/Ruff rules |
| Type errors | Pre-commit type check |
| Security vulnerabilities | Dependency scanning in CI |
| Format inconsistency | Auto-format on save |
| Secrets in code | Pre-commit secret detection |

```yaml
# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: type-check
      name: TypeScript check
      entry: npx tsc --noEmit
      language: system
```

## Prevention Priority Matrix

| Effort | Impact | Priority |
|--------|--------|----------|
| Low | High | Immediate |
| Low | Low | Backlog |
| High | High | Sprint planning |
| High | Low | Skip |


### Similar Issue Search

# Similar Issue Search

Find related past issues to leverage previous solutions and detect regressions.

## GitHub Issue Search Patterns

```bash
# Search by error message
gh issue list --search "TypeError: Cannot read property" --state all

# Search by component/file
gh issue list --search "UserService" --state all --json number,title,state

# Search by label
gh issue list --label "bug" --state closed --limit 20

# Combined search
gh issue list --search "auth login 401" --state all --json number,title,closedAt
```

## Memory/Knowledge Graph Queries

```python
# Search for past fixes
mcp__memory__search_nodes(query="fix authentication error")

# Search by error type
mcp__memory__search_nodes(query="TypeError resolution")

# Search by component
mcp__memory__search_nodes(query="UserService bug")
```

## Stack Trace Similarity Matching

Match by:
1. **Exception type** - Same error class
2. **File/line** - Same code location
3. **Call stack depth** - Similar execution path
4. **Error message pattern** - Regex match on message

## Similarity Assessment Criteria

| Factor | Weight | High Match |
|--------|--------|------------|
| Same exception type | 30% | Exact match |
| Same file | 25% | Same file involved |
| Similar error message | 20% | >80% string similarity |
| Same component | 15% | Same service/module |
| Recent (&lt; 30 days) | 10% | Recently resolved |

## When to Reuse vs Investigate Fresh

**Reuse Previous Solution When:**
- Similarity > 80%
- Same root cause confirmed
- Fix is still applicable
- No code changes since fix

**Investigate Fresh When:**
- Similarity &lt; 60%
- Context has changed significantly
- Previous fix may be incomplete
- New dependencies involved

## Issue Classification

| Type | Action |
|------|--------|
| **Regression** | Same issue, fix reverted or bypassed |
| **Variant** | Similar pattern, different trigger |
| **New** | No similar issues found |



---

## Checklists (1)

### Fix Complete Checklist

# Fix Complete Checklist

Verify all aspects of issue resolution before closing.

## Root Cause Analysis

- [ ] Root cause identified with confidence >= 70%
- [ ] Hypotheses documented (at least 2 considered)
- [ ] Evidence for/against documented
- [ ] Similar issues checked

## Fix Verification

- [ ] Regression test added
- [ ] All existing tests pass
- [ ] Fix manually verified
- [ ] Edge cases covered

## Prevention

- [ ] Prevention recommendation documented
- [ ] At least one prevention measure implemented or ticketed
- [ ] Runbook entry created/updated

## Knowledge Capture

- [ ] Lessons learned stored in memory
- [ ] RCA report generated (for high/critical issues)
- [ ] Related issues linked

## PR/Commit

- [ ] Commit message includes issue number
- [ ] Commit message describes root cause
- [ ] PR links to issue with "Fixes #N"

## Final Verification

```bash
# Quick verification commands
git log -1 --oneline  # Check commit message
gh pr checks          # Check CI status
gh issue view [N]     # Verify issue linked
```

