majiayu000 Debug
Uses Implementer (primary) with Test support. Systematically investigate issues using hypothesis-driven debugging, identify root cause, and implement fixes.
Prerequisites: Error description, reproduction steps, or failing test output
Phase 1: Characterize the Problem
Gather Evidence
- Reproduce the error or review the error output
- Identify the error type, message, and stack trace
- Note the affected file(s) and line(s)
- Determine when the issue started (recent change? new environment?)
Output
## Context Anchors
- **Issue:** #<number> - <title> (if applicable)
- **Phase:** 1 — Characterize
## Problem Summary
**Error:** <error message>
**Location:** <file:line>
**Reproduction:** <how to trigger>
## Initial Observations
- <observation 1>
- <observation 2>
## Next Step
Form hypotheses about root cause.
**Approval Required:** No
Phase 2: Hypothesize and Test
Form Hypotheses
- List 2-3 likely root causes based on evidence
- Rank by likelihood
- For each hypothesis, identify what evidence would confirm or refute it
Test Hypotheses
For each hypothesis (most likely first):
- State the hypothesis clearly
- Describe the diagnostic step
- Execute the diagnostic (read code, add logging, run test)
- Record the result
- Confirm or eliminate the hypothesis
Common Root Cause Patterns
| Pattern | Diagnostic |
|---|---|
| Null/undefined | Trace data flow to find missing value |
| Race condition | Check async ordering, add logging |
| Configuration error | Compare expected vs actual config values |
| Dependency mismatch | Check version compatibility |
| State mutation | Track state changes through flow |
| Missing error handle | Check for uncaught exceptions |
Output
## Context Anchors
- **Issue:** #<number> - <title>
- **Phase:** 2 — Hypothesize
## Hypotheses
| # | Hypothesis | Likelihood | Evidence For | Evidence Against |
| --- | ------------ | ------------ | ------------ | ---------------- |
| 1 | <hypothesis> | High/Med/Low | <evidence> | <evidence> |
| 2 | <hypothesis> | High/Med/Low | <evidence> | <evidence> |
## Root Cause
**Confirmed hypothesis:** <which one>
**Explanation:** <why this is the cause>
## Next Step
Propose and implement fix.
**Approval Required:** Yes
⛔ CHECKPOINT
STOP. Do not implement a fix until root cause is confirmed and approved.
Phase 3: Fix and Verify
Implement Fix
- Make the minimal change that addresses the root cause
- Avoid changing unrelated code
- Add or update tests to cover the failure case
Verify
- Confirm the original error no longer occurs
- Run related tests to check for regressions
- Review the fix for side effects
Output
## Context Anchors
- **Issue:** #<number> - <title>
- **Phase:** 3 — Fix
## Root Cause
<confirmed root cause>
## Fix Applied
<description of the change>
## Verification
- [ ] Original error resolved
- [ ] Tests pass
- [ ] No regressions introduced
## Next Step
<commit the fix / create PR / further investigation>
**Approval Required:** Yes
⛔ CHECKPOINT
STOP. Do not proceed until human approves:
- Fix is correct and minimal
- Verification confirms the issue is resolved
- No regressions introduced
Error Handling
| Situation | Recovery |
|---|---|
| Cannot reproduce | Gather more context, check environment differences |
| Multiple root causes | Address each separately, prioritize by impact |
| Fix introduces new failures | Revert, re-analyze with new information |
| Root cause is external | Document workaround, file upstream issue |