diegosouzapw Debugging Workflow Rules
Core Philosophy
Understand before you fix.
Debugging is not about quick patches - it's about:
- Deep understanding of the bug's manifestation
- Systematic tracing to root cause
- Strategic fix design considering side effects
- Thorough verification of the fix
6-Phase Debugging Workflow
| Phase | Name | Purpose | Agents |
|---|---|---|---|
| 1 | Discovery | Understand bug symptoms | - |
| 2 | Exploration | Trace execution paths | 2-3 debug-explorer |
| 3 | Root Cause | Identify true cause | Analysis synthesis |
| 4 | Strategy | Design fix approach | 2-3 debug-strategist |
| 5 | Implementation | Apply the fix | User-approved |
| 6 | Verification | Confirm fix works | 2-3 debug-verifier |
Phase Details
Phase 1: Bug Discovery
Gather complete information about the bug:
BugReport:
symptoms: What is happening?
expected: What should happen?
reproduction: Steps to reproduce
frequency: Always / Sometimes / Rare
context: Environment, version, user actions
error_output: Error messages, stack traces, logs
Key Questions:
- When did this start happening?
- What changed recently?
- Is it environment-specific?
- Can it be reliably reproduced?
Phase 2: Codebase Exploration
Launch 2-3 debug-explorer agents in parallel with different focuses:
| Focus | Investigation Target |
|---|---|
| Execution Path | Trace the failing code path step by step |
| Data Flow | Track data transformations and mutations |
| Dependencies | Check related components and integrations |
Serena MCP Integration:
# Symbol-level tracing
find_symbol: Locate relevant functions/classes
find_referencing_symbols: Find all callers
search_for_pattern: Search for error patterns
Phase 3: Root Cause Analysis
Synthesize exploration findings:
RootCauseAnalysis:
immediate_cause: What directly triggers the error?
underlying_cause: Why does this condition exist?
contributing_factors: What else enables this bug?
timeline: When was this introduced?
Common Root Cause Categories:
| Category | Examples |
|---|---|
| Logic Error | Wrong condition, off-by-one, null check missing |
| State Management | Race condition, stale data, unexpected mutation |
| Integration | API contract mismatch, version incompatibility |
| Resource | Memory leak, connection exhaustion, timeout |
| Configuration | Wrong settings, missing env vars, path issues |
Phase 4: Fix Strategy Design
Launch 2-3 debug-strategist agents with different approaches:
| Approach | Strategy |
|---|---|
| Minimal | Smallest change to fix the symptom |
| Comprehensive | Address root cause and prevent recurrence |
| Defensive | Add guards, validation, error handling |
Strategy Evaluation Criteria:
- Risk of regression
- Impact on related functionality
- Code quality improvement
- Testing feasibility
Phase 5: Implementation
Requires explicit user approval before proceeding.
Implementation checklist:
- Apply the chosen fix strategy
- Update related code if needed
- Add defensive checks where appropriate
- Document the fix rationale
Phase 6: Verification
Launch 2-3 debug-verifier agents with different focuses:
| Focus | Verification Target |
|---|---|
| Direct | Does the original bug no longer occur? |
| Regression | Are there any new issues introduced? |
| Edge Cases | Does it handle boundary conditions? |
Verification Methods:
- Manual reproduction attempt
- Related test execution
- Code review for side effects
- Static analysis check
Confidence Scoring
All agents use confidence scoring (0-100):
| Score | Meaning | Action |
|---|---|---|
| 0-25 | Speculation | Do not report |
| 26-50 | Possible | Mention if relevant |
| 51-79 | Likely | Report with caveats |
| 80-100 | Confident | Report as finding |
Only report findings with confidence ≥ 80%
Integration with Serena MCP
| Task | Serena Tool |
|---|---|
| Find function definition | find_symbol |
| Trace all callers | find_referencing_symbols |
| Search error patterns | search_for_pattern |
| Get file overview | get_symbols_overview |
| Read specific symbol | find_symbol with include_body=true |
Output Templates
Exploration Report
## Exploration: [Focus Area]
### Entry Points Found
- `file.ts:123` - `functionName` - [description]
### Execution Path
1. [Step 1 description]
2. [Step 2 description]
### Key Components
| Component | File | Responsibility |
|-----------|------|----------------|
### Architecture Insights
- [Insight 1]
- [Insight 2]
### Critical Files to Review
1. `path/to/file.ts` - [reason]
Strategy Report
## Fix Strategy: [Approach Name]
### Proposed Change
[Description of the fix]
### Files to Modify
| File | Change Type | Description |
|------|-------------|-------------|
### Risk Assessment
- Regression risk: Low/Medium/High
- Impact scope: [affected areas]
### Implementation Steps
1. [Step 1]
2. [Step 2]
Verification Report
## Verification: [Focus Area]
### Test Results
| Test | Status | Notes |
|------|--------|-------|
### Issues Found
- Severity: Critical/Important
- Confidence: [score]%
- Location: `file:line`
- Description: [issue]
- Suggested Fix: [fix]
### Final Assessment
[Pass/Fail with reasoning]
Detailed templates:
Read("references/debug-patterns.md")