Issue Resolution Pipeline

Systematically resolve issues through iterative diagnosis and verified fixes.

Pipeline Overview

INPUT → Triage → Reproduction → Root Cause Analysis → Impact → Fix → Verify
              ◄──────────────►◄────────────────────►
                    (Iterative loops allowed)

| Phase | Purpose | Output | | ---------------------- | ---------------------------------- | ------------------- | | 0. Triage | Normalize input, classify severity | Issue Brief | | 1. Reproduction | Prove the bug, trace code path | Repro Report + Test | | 2. Root Cause Analysis | Find WHY, not just WHERE | RCA Report | | 3. Impact Assessment | Blast radius, regression risk | Impact Report | | 4. Fix Decomposition | Break into beads | .beads/*.md | | 5. Verification | Prove fix works, no regressions | Passing tests |

Phase 0: Triage

Normalize different input types to a structured Issue Brief.

Input Types

| Type | Triage Strategy | | --------------------- | ------------------------------------- | | Vague report | Clarify → Explore → Reproduce | | Error/Stack trace | Parse trace → Locate code → Reproduce | | Failing test | Run test → Extract assertion → Trace |

Vague Report Triage

User: "Login is broken"
         │
         ▼
Ask clarification questions:
• What error do you see?
• When did it start working / stop working?
• What steps trigger it?
• Specific user/browser/environment?
         │
         ▼ (if user can't clarify)
Explore:
• mcp__gkg__search_codebase_definitions: Find auth/login related code
• git log: Recent changes in area
• Check logs if available

Error/Stack Trace Triage

Parse the stack trace:
• Extract file:line locations
• mcp__gkg__get_definition on functions in trace
• Read surrounding context
         │
         ▼
Identify reproduction conditions:
• What input caused this?
• Can we write a test?

Failing Test Triage

Run test in isolation:
• bun test <file> --filter "<test name>"
• Read test file for setup/assertions
• Check git log: was it passing before?
         │
         ▼
Trace implementation:
• What code does test exercise?
• mcp__gkg__get_references on tested function
• Recent changes to implementation?

Severity Classification

Determines reproduction requirements:

| Severity | Reproduction Required | | ----------------------------------- | ---------------------- | | CRITICAL (production, security) | Failing test REQUIRED | | REGRESSION (was working) | Failing test REQUIRED | | RACE CONDITION (timing) | Failing test REQUIRED | | LOGIC BUG | Failing test PREFERRED | | UI/VISUAL | Manual + screenshot OK | | PERFORMANCE | Benchmark/profile OK | | QUICK FIX (obvious cause) | Manual repro OK |

Issue Brief Template

Save to history/issues/<id>/brief.md:

# Issue Brief: <Short Title>

**Severity**: CRITICAL / HIGH / MEDIUM / LOW
**Type**: Regression / Edge case / Race condition / UI / Performance / Other
**Repro Required**: Failing test / Manual OK

## Symptom

<What is happening>

## Expected Behavior

<What should happen>

## Reproduction

<Steps, test command, or code path>

## Evidence

<Error message, stack trace, test output>

## Affected Area

<Files, modules, features involved>

## Timeline

<When started, recent changes if known>

Phase 1: Reproduction

Prove the bug exists and trace the code path.

If Failing Test Required

# Create test file
# packages/<area>/src/__tests__/<feature>.regression.test.ts

# Test should:
# 1. Set up conditions that trigger bug
# 2. Assert expected behavior (currently fails)
# 3. Be deterministic

Reproduction Checklist

• [ ] Bug is reproducible on demand
• [ ] Exact error/behavior captured
• [ ] Minimal reproduction (simplest case that fails)
• [ ] Code path identified (stack trace or tracing)

Code Path Tracing

mcp__gkg__get_definition     → Find where error originates
mcp__gkg__get_references     → Find callers
git blame <file>       → Who changed it, when
git log -p <file>      → What changed recently

Repro Report Template

Save to history/issues/<id>/repro.md:

# Reproduction Report: <Issue Title>

## Reproduction Method

☐ Failing test: `<test file and name>`
☐ Manual: <steps>

## Error/Behavior Captured

<Exact error message, stack trace>

## Code Path

1. Entry: `<file>:<line>` - <function>
2. Calls: `<file>:<line>` - <function>
3. Fails at: `<file>:<line>` - <reason>

## Recent Changes (if relevant)

- <commit>: <summary>

Phase 2: Root Cause Analysis

Find WHY the bug happens, not just WHERE.

RCA Framework

STEP 1: Generate hypotheses (3-5)
         │
         ▼
STEP 2: Gather evidence for/against each
         │
         ▼
STEP 3: Eliminate hypotheses
         │
         ▼
STEP 4: Confirm root cause

Bug Type → RCA Strategy

| Bug Type | Strategy | Key Tools | | ------------------- | ------------------------- | ------------------------------- | | Regression | Find breaking change | git bisect, git blame | | Edge case | Analyze boundary inputs | Type inspection, boundary tests | | Race condition | Trace async flow | Timing logs, async analysis | | Data corruption | Trace state changes | Data flow analysis | | External dep | Check version/API changes | Changelogs, API docs |

Oracle for RCA

Hypothesis Generation:

oracle(
  task: "Generate root cause hypotheses",
  context: """
    Symptom: <error>
    Code path: <trace>
    Recent changes: <git log>

    Generate 3-5 hypotheses ranked by likelihood.
    For each, what evidence would support/refute it?
  """,
  files: ["<affected files>"]
)

Hypothesis Validation:

oracle(
  task: "Validate root cause hypothesis",
  context: """
    Hypothesis: <proposed cause>
    Evidence: <gathered evidence>

    1. Does evidence support or refute?
    2. Explain causal chain: cause → symptom
    3. What would confirm this?
  """,
  files: ["<relevant files>"]
)

Iteration: RCA → Reproduction Loop

If hypothesis needs more evidence:

IN RCA: "Need timing logs to confirm race condition"
    │
    ▼
BACK TO REPRO:
• Add instrumentation
• Run with specific conditions
• Capture new evidence
    │
    ▼
RETURN TO RCA with new evidence

RCA Report Template

Save to history/issues/<id>/rca.md:

# Root Cause Analysis: <Issue Title>

## Iteration: <N>

## Hypotheses Considered

### Hypothesis A: <Description>

- **Likelihood**: HIGH / MEDIUM / LOW
- **Supporting evidence**: ...
- **Refuting evidence**: ...
- **Verdict**: ✓ CONFIRMED / ✗ ELIMINATED

### Hypothesis B: ...

## Root Cause (Confirmed)

**Cause**: <Clear statement>

**Causal chain**:

1. <Step> leads to
2. <Step> leads to
3. <Symptom>

## Why This Happened

<Underlying reason - missing validation, wrong assumption, etc.>

## Fix Approach

**Immediate**: <What to change>
**Preventive**: <How to prevent similar bugs>

Phase 3: Impact Assessment

Before fixing, understand blast radius.

Impact Analysis

mcp__gkg__get_references <affected function>
    → Who else calls this?

Grep for related patterns
    → Similar code that might have same bug?

Review test coverage
    → What tests cover this area?

Regression Risk

| Factor | Risk Level | | ------------------- | ---------- | | High usage function | HIGH | | Shared utility | HIGH | | Public API change | HIGH | | Internal helper | LOW | | Isolated module | LOW |

Spike for Complex Fixes

If fix approach is uncertain:

bd create "Spike: Validate fix approach for <issue>" -t task -p 0

Execute via MULTI_AGENT_WORKFLOW, write to .spikes/<issue-id>/.

Impact Report Template

Save to history/issues/<id>/impact.md:

# Impact Assessment: <Issue Title>

## Blast Radius

### Direct Impact

- <File/function directly changed>

### Callers Affected

- <List from mcp__gkg__get_references>

### Related Code

- <Similar patterns that may need same fix>

## Regression Risk

**Level**: HIGH / MEDIUM / LOW
**Reason**: <Why this risk level>

## Test Coverage

- Existing tests: <list>
- Tests to add: <list>

## Fix Validation

☐ Spike completed (if needed): `.spikes/<id>/`
☐ Fix approach validated

Phase 4: Fix Decomposition

Break fix into beads.

Simple Fix (Single Bead)

bd create "Fix: <issue title>" -t bug -p <priority>

Bead includes:

• Root cause reference
• Fix implementation
• Test (failing → passing)
• Docs update (if behavior change)

Complex Fix (Multiple Beads)

bd create "Epic: Fix <issue>" -t epic -p <priority>
bd create "Add regression test for <issue>" -t task --blocks <epic>
bd create "Fix <component A>" -t bug --blocks <epic> --deps <test>
bd create "Fix <component B>" -t bug --blocks <epic> --deps <test>
bd create "Update docs for <behavior change>" -t task --blocks <epic> --deps <fix-a>,<fix-b>

Fix Bead Template

# Fix: <Issue Title>

**Type**: bug
**Priority**: <0-4>
**Fixes**: <issue reference>

## Root Cause

<From RCA report>

## Fix Implementation

<What to change and why>

## Files to Modify

- `<file>`: <change description>

## Acceptance Criteria

- [ ] Regression test passes
- [ ] Original symptom no longer reproducible
- [ ] No new test failures
- [ ] `bun run check-types` passes
- [ ] `bun run build` passes

Phase 5: Verification

Prove fix works and nothing else broke.

Verification Checklist

# 1. Regression test passes
bun test <regression-test-file>

# 2. Original symptom gone
<manual verification or test>

# 3. No new failures
bun run test

# 4. Types and build
bun run check-types
bun run build

Iteration: Verify → RCA Loop

If fix doesn't work:

Test still fails after fix
    │
    ▼
Root cause was wrong or incomplete
    │
    ▼
BACK TO RCA:
• Eliminate current hypothesis
• Generate new hypotheses
• Update RCA Report with iteration

Verify → Impact Loop

If fix causes regressions:

New test failures after fix
    │
    ▼
Fix has unintended side effects
    │
    ▼
BACK TO IMPACT:
• Reassess blast radius
• Consider alternative fix approach

Loop Limits

Prevent infinite iteration:

| Loop | Soft Limit | Hard Limit | At Hard Limit | | ------------ | ---------- | ---------- | --------------------------- | | RCA → Repro | 2 | 4 | Escalate / pair debug | | RCA → Triage | 1 | 2 | Re-evaluate original report | | Verify → RCA | 2 | 3 | Oracle deep review |

Quick Reference

Tool Selection

| Need | Tool | | --------------------- | ------------------------------- | | Parse stack trace | Read + mcpgkgget_definition | | Find callers | mcpgkgget_references | | Recent changes | git log, git blame | | Binary search commits | git bisect | | Reasoning about cause | oracle | | Validate fix approach | Spike via MULTI_AGENT_WORKFLOW |

Common Mistakes

• Fixing symptom, not cause → Leads to recurrence
• Skipping reproduction → Can't verify fix
• No regression test → Bug returns later
• Ignoring impact → Fix breaks other things
• Not iterating → Wrong diagnosis persists