when-debugging-code-use-debugging-assistant

Debugging Assistant Skill

Overview

Intelligent debugging workflow that systematically identifies symptoms, performs root cause analysis, generates fixes with explanations, validates solutions, and prevents regressions through comprehensive testing.

Metadata

• Skill ID: when-debugging-code-use-debugging-assistant
• Category: Development/Debugging
• Complexity: HIGH
• Agents Required: coder, code-analyzer, tester
• Prerequisites: Access to codebase, error logs, test environment

Trigger Conditions

Use this skill when encountering:

• Runtime errors or exceptions
• Unexpected behavior or incorrect output
• Performance degradation or memory leaks
• Race conditions or timing issues
• Integration failures
• Test failures requiring investigation

5-Phase Debugging Protocol (SOP)

Phase 1: Symptom Identification

Objective: Gather comprehensive information about the issue

Agent: code-analyzer

Actions:

1. Collect error messages, stack traces, and logs
2. Document expected vs actual behavior
3. Identify reproduction steps
4. Determine scope and frequency of occurrence
5. Classify issue severity and impact

Outputs:

• Symptom report with complete context
• Reproduction steps (manual or automated)
• Environmental context (OS, runtime version, dependencies)
• Issue classification (bug, regression, edge case)

Success Criteria:

• Issue can be consistently reproduced
• All relevant context is documented
• Scope of impact is clearly defined

Phase 2: Root Cause Analysis

Objective: Trace execution flow and identify the underlying cause

Agent: code-analyzer + coder

Actions:

1. Trace execution path from entry point to failure
2. Examine variable states and data transformations
3. Identify assumptions that may be violated
4. Check boundary conditions and edge cases
5. Review recent code changes that may have introduced the issue
6. Analyze dependencies and external system interactions

Techniques:

• Binary search debugging (narrow down location)
• Hypothesis-driven investigation
• Comparative analysis (working vs broken code paths)
• Temporal analysis (when did it start failing?)

Outputs:

• Root cause statement with evidence
• Affected code locations and line numbers
• Explanation of why the bug occurs
• Related issues or side effects

Success Criteria:

• Clear understanding of the mechanism causing the failure
• Reproducible test case that isolates the root cause
• Documented reasoning chain from symptom to cause

Phase 3: Fix Generation

Objective: Develop and explain solution options

Agent: coder

Actions:

1. Generate 2-3 solution approaches
2. Evaluate trade-offs for each approach
3. Select optimal solution based on:
4. Correctness and completeness
5. Performance impact
6. Code maintainability
7. Risk of side effects
8. Implement the fix with clear comments
9. Document why this approach was chosen

Fix Patterns:

• Null Safety: Add null checks, use optional chaining
• Race Conditions: Add synchronization, use promises properly
• Memory Leaks: Clean up listeners, break circular references
• Type Errors: Add runtime validation, improve type definitions
• Logic Errors: Correct conditions, fix off-by-one errors

Outputs:

• Implemented fix with explanation
• Alternative approaches considered
• Potential side effects documented
• Migration notes if API changes

Success Criteria:

• Fix addresses root cause, not just symptoms
• Code is clean and maintainable
• No new issues introduced
• Clear explanation provided

Phase 4: Validation Testing

Objective: Confirm the fix resolves the issue without breaking existing functionality

Agent: tester

Actions:

1. Create test case that reproduces original bug
2. Verify test fails before fix (proves test validity)
3. Apply fix and verify test passes
4. Run full regression test suite
5. Perform exploratory testing in affected areas
6. Test edge cases and boundary conditions
7. Validate in environment matching production

Test Coverage:

• Unit tests for isolated logic
• Integration tests for component interactions
• End-to-end tests for user workflows
• Performance tests if relevant
• Security tests if applicable

Outputs:

• Test case that validates the fix
• Regression test results
• Performance benchmarks (if applicable)
• Test coverage report

Success Criteria:

• Original issue is resolved
• No regression failures
• Test coverage increased
• Fix validated in realistic environment

Phase 5: Regression Prevention

Objective: Ensure the issue doesn't recur

Agent: tester + coder

Actions:

1. Add permanent test case to test suite
2. Document the bug and fix in code comments
3. Update architecture documentation if patterns exposed
4. Add monitoring or assertions to catch similar issues
5. Consider if similar bugs exist elsewhere in codebase
6. Update development guidelines if needed

Documentation:

• Add comments explaining non-obvious fixes
• Update CHANGELOG or bug tracking system
• Create knowledge base entry for complex issues
• Document lessons learned

Outputs:

• Automated test preventing recurrence
• Updated documentation
• Code review checklist items (if applicable)
• Monitoring/alerting improvements

Success Criteria:

• Test suite will catch this issue if reintroduced
• Knowledge is preserved for team
• Similar issues are preventable
• Monitoring is in place (if applicable)

Coordination Protocol

Agent Communication Flow

1. User reports issue → code-analyzer (Symptom Identification)
2. code-analyzer findings → coder (Root Cause Analysis)
3. coder diagnosis → coder (Fix Generation)
4. coder fix → tester (Validation Testing)
5. tester results → coder + tester (Regression Prevention)
6. Final report → User

Memory Coordination

Memory Keys:

• debug/[issue-id]/symptoms - Symptom analysis
• debug/[issue-id]/root-cause - RCA findings
• debug/[issue-id]/fix - Solution implementation
• debug/[issue-id]/validation - Test results
• debug/[issue-id]/prevention - Long-term measures

Hooks Integration

Pre-Debug Hook:

npx claude-flow@alpha hooks pre-task --description "Debug: [issue-description]"
npx claude-flow@alpha hooks session-restore --session-id "debug-[issue-id]"

Post-Fix Hook:

npx claude-flow@alpha hooks post-edit --file "[fixed-file]" --memory-key "debug/[issue-id]/fix"
npx claude-flow@alpha hooks notify --message "Fix applied: [description]"

Session End Hook:

npx claude-flow@alpha hooks post-task --task-id "debug-[issue-id]"
npx claude-flow@alpha hooks session-end --export-metrics true

Common Debugging Scenarios

Scenario 1: Null Pointer Exception

Symptom:

TypeError: Cannot read property 'name' of undefined
  at processUser (users.js:45)

Root Cause: User object not validated before property access

Fix:

// Before
function processUser(user) {
  return user.name.toUpperCase();
}

// After
function processUser(user) {
  if (!user || !user.name) {
    throw new Error('Invalid user object');
  }
  return user.name.toUpperCase();
}

Test:

test('processUser handles missing user gracefully', () => {
  expect(() => processUser(null)).toThrow('Invalid user object');
  expect(() => processUser({})).toThrow('Invalid user object');
  expect(processUser({name: 'john'})).toBe('JOHN');
});

Scenario 2: Async Race Condition

Symptom: Intermittent test failures, data corruption in production

Root Cause: Multiple async operations modifying shared state without synchronization

Fix:

// Before - Race condition
async function updateCart(userId, item) {
  const cart = await getCart(userId);
  cart.items.push(item);
  await saveCart(userId, cart);
}

// After - Using optimistic locking
async function updateCart(userId, item) {
  let attempts = 0;
  while (attem