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

AskUserQuestion(
  questions=[{
    "question": "What approach for this fix?",
    "header": "Approach",
    "options": [
      {"label": "Proper fix (Recommended)", "description": "Full RCA, tests, prevention recommendations"},
      {"label": "Quick fix", "description": "Minimal fix to resolve the immediate issue"},
      {"label": "Investigate first", "description": "Understand the issue before deciding on approach"},
      {"label": "Hotfix", "description": "Emergency patch, minimal testing"}
    ],
    "multiSelect": false
  }]
)

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

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

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

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

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

Task(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()

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

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