/ork:fix-issue

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

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

# Probe MCPs (parallel — all in ONE message):
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
}))

# 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

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
  }]
)

# 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.

# 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

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

# 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."
)

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

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

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

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
  }]
)

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

# 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%)

                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

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

USER CANNOT AUTHENTICATE
         |
       [OR]
    +----+----+
    |         |
Auth Service  Account
   Down       Locked

                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

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

### API Latency Spike Analysis

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

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

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]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# 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
)

## 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]

# 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

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

# 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

# Runbook: [Issue Type]

## Symptoms
- [Observable symptom]

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

## Resolution Steps
1. [Step 1]

## Prevention
- [How to prevent]

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

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]"

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

## 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]

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

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

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

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

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

# 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

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

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