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 0: Triage

Normalize different input types to a structured Issue Brief.

Input Types

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:

Issue Brief Template

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

markdown
1# Issue Brief: <Short Title>
2
3**Severity**: CRITICAL / HIGH / MEDIUM / LOW
4**Type**: Regression / Edge case / Race condition / UI / Performance / Other
5**Repro Required**: Failing test / Manual OK
6
7## Symptom
8
9<What is happening>
10
11## Expected Behavior
12
13<What should happen>
14
15## Reproduction
16
17<Steps, test command, or code path>
18
19## Evidence
20
21<Error message, stack trace, test output>
22
23## Affected Area
24
25<Files, modules, features involved>
26
27## Timeline
28
29<When started, recent changes if known>

Phase 1: Reproduction

Prove the bug exists and trace the code path.

If Failing Test Required

bash
1# Create test file
2# packages/<area>/src/__tests__/<feature>.regression.test.ts
3
4# Test should:
5# 1. Set up conditions that trigger bug
6# 2. Assert expected behavior (currently fails)
7# 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:

markdown
1# Reproduction Report: <Issue Title>
2
3## Reproduction Method
4
5☐ Failing test: `<test file and name>`
6☐ Manual: <steps>
7
8## Error/Behavior Captured
9
10<Exact error message, stack trace>
11
12## Code Path
13
141. Entry: `<file>:<line>` - <function>
152. Calls: `<file>:<line>` - <function>
163. Fails at: `<file>:<line>` - <reason>
17
18## Recent Changes (if relevant)
19
20- <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

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:

markdown
1# Root Cause Analysis: <Issue Title>
2
3## Iteration: <N>
4
5## Hypotheses Considered
6
7### Hypothesis A: <Description>
8
9- **Likelihood**: HIGH / MEDIUM / LOW
10- **Supporting evidence**: ...
11- **Refuting evidence**: ...
12- **Verdict**: ✓ CONFIRMED / ✗ ELIMINATED
13
14### Hypothesis B: ...
15
16## Root Cause (Confirmed)
17
18**Cause**: <Clear statement>
19
20**Causal chain**:
21
221. <Step> leads to
232. <Step> leads to
243. <Symptom>
25
26## Why This Happened
27
28<Underlying reason - missing validation, wrong assumption, etc.>
29
30## Fix Approach
31
32**Immediate**: <What to change>
33**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

Spike for Complex Fixes

If fix approach is uncertain:

bash
1bd 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:

markdown
1# Impact Assessment: <Issue Title>
2
3## Blast Radius
4
5### Direct Impact
6
7- <File/function directly changed>
8
9### Callers Affected
10
11- <List from mcp__gkg__get_references>
12
13### Related Code
14
15- <Similar patterns that may need same fix>
16
17## Regression Risk
18
19**Level**: HIGH / MEDIUM / LOW
20**Reason**: <Why this risk level>
21
22## Test Coverage
23
24- Existing tests: <list>
25- Tests to add: <list>
26
27## Fix Validation
28
29☐ Spike completed (if needed): `.spikes/<id>/`
30☐ Fix approach validated

Phase 4: Fix Decomposition

Break fix into beads.

Simple Fix (Single Bead)

bash
1bd 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)

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

Fix Bead Template

markdown
1# Fix: <Issue Title>
2
3**Type**: bug
4**Priority**: <0-4>
5**Fixes**: <issue reference>
6
7## Root Cause
8
9<From RCA report>
10
11## Fix Implementation
12
13<What to change and why>
14
15## Files to Modify
16
17- `<file>`: <change description>
18
19## Acceptance Criteria
20
21- [ ] Regression test passes
22- [ ] Original symptom no longer reproducible
23- [ ] No new test failures
24- [ ] `bun run check-types` passes
25- [ ] `bun run build` passes

Phase 5: Verification

Prove fix works and nothing else broke.

Verification Checklist

bash
1# 1. Regression test passes
2bun test <regression-test-file>
3
4# 2. Original symptom gone
5<manual verification or test>
6
7# 3. No new failures
8bun run test
9
10# 4. Types and build
11bun run check-types
12bun 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:

Quick Reference

Tool Selection

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