majiayu000 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