Debug Mode

Recommended model tier: smart (opus) - this skill requires complex reasoning

Systematic approach to identifying and fixing bugs.

Prerequisites

Before starting:

• Get the exact error message or unexpected behavior description
• Identify the entry point or trigger for the bug
• Note any relevant environment details (Node version, OS, etc.)

Workflow

Step 1: Reproduce the Issue

Goal: Confirm the bug exists and understand its behavior.

# Run the failing code/test
npm test -- --grep "failing test"
# OR
node path/to/script.js

Document:

• Exact error message
• Steps to trigger
• Expected vs actual behavior
• Is it consistent or intermittent?

If cannot reproduce:

• Check environment differences
• Look for race conditions
• Check for cached state

Step 2: Locate the Relevant Code

Use tools to find code related to the error:

# Search for function mentioned in stack trace
mcp__plugin_aide_aide__code_search query="functionName" kind="function"

# Get a structural overview of the suspect file (signatures + line ranges)
mcp__plugin_aide_aide__code_outline file="path/to/file.ts"

# Get symbols in suspect file
mcp__plugin_aide_aide__code_symbols file="path/to/file.ts"

# Search for error message text in code
Grep for "error message text"

Step 3: Trace the Execution Path

Follow the code flow from entry to error:

1. Use code_outline on each file in the call chain to understand its structure
2. Use code_references to find callers of the failing function
3. Use Read with offset/limit to read specific functions in the execution path (use line numbers from the outline)
4. Check type definitions with code_search kind="interface"

Outlines help you identify which functions matter, so you can read just those sections.

Step 4: Form Hypotheses

Based on the error type, consider these causes:

Symptom	Likely Causes
"undefined is not a function"	Variable is null/undefined, wrong import
"Cannot read property of undefined"	Missing null check, async timing issue
"Type error"	Type mismatch, wrong function signature
"Maximum call stack"	Infinite recursion, circular reference
"Network error"	Bad URL, CORS, timeout, server down
"State not updating"	Mutation instead of new object, missing dependency

Step 5: Validate Hypotheses

Test each hypothesis systematically:

# Add temporary logging
console.log('DEBUG: variable =', JSON.stringify(variable));

# Check with debugger
node --inspect-brk script.js

# Run specific test
npm test -- --grep "test name"

Validation checklist:

• Check variable values at key points
• Verify assumptions about input data
• Test edge cases (null, empty, boundary values)
• Check async ordering

Step 6: Apply the Fix

Rules:

• Change only what's necessary to fix the bug
• Don't refactor unrelated code
• Match existing code patterns

Common fixes:

• Add null/undefined check
• Fix type annotation
• Correct async/await usage
• Fix variable scope
• Add missing initialization

Step 7: Verify the Fix

# Run the originally failing test/scenario
npm test -- --grep "failing test"

# Run related tests
npm test -- --grep "related feature"

# Run full test suite to check for regressions
npm test

Verification criteria:

• Original issue no longer occurs
• Related tests still pass
• No new errors introduced

Failure Handling

Situation	Action
Cannot reproduce	Check environment, add logging to narrow down
Multiple bugs intertwined	Fix one at a time, verify after each
Fix causes new failures	Revert, analyze dependencies, try different approach
Root cause is in dependency	Check for updates, file issue, implement workaround
Bug is in async code	Add proper await, check Promise chains

When abandoning an approach: If you try a fix direction and abandon it (e.g., revert because it causes regressions), record it as an abandoned approach so future sessions don't repeat it:

./.aide/bin/aide memory add --category=abandoned \
  --tags=reason:<why>,approach:<what>,project:<name>,session:<id>,source:discovered \
  "ABANDONED: <what was tried>. REASON: <why>. ALTERNATIVE: <new direction>. CONTEXT: <details>"

MCP Tools

• mcp__plugin_aide_aide__code_outline - Start here. Get collapsed file skeleton to understand structure before reading
• mcp__plugin_aide_aide__code_search - Find functions, classes, types involved in the bug
• mcp__plugin_aide_aide__code_symbols - List all symbols in a file
• mcp__plugin_aide_aide__code_references - Find all callers of a function
• mcp__plugin_aide_aide__memory_search - Check for related past issues

Output Format

## Debug Report: [Issue Title]

### Problem

[What was happening vs what should happen]

### Reproduction

[Steps to reproduce the issue]

### Root Cause

[Identified cause with file:line reference]
[Why the bug occurred]

### Fix Applied

[What was changed and why]

### Verification

- Original issue: FIXED
- Related tests: PASS
- Full suite: PASS

### Prevention

[Optional: How to prevent similar bugs]

Tips

• Always get the full error message and stack trace first
• Don't guess - trace the code path methodically
• One fix at a time - don't bundle unrelated changes
• Remove temporary logging before committing
• Consider if the bug could occur elsewhere

Memory Hygiene

When storing memories from this skill (abandoned approaches, blockers), always:

1. Include source: tag — Use source:discovered for things you found, source:inferred for deductions
2. Include scope tags — Add project:<name>,session:<id> (get project name from git remote or directory; session ID from $AIDE_SESSION_ID or $CLAUDE_SESSION_ID)
3. Verify codebase claims before storing — If a memory references a file, function, or path, confirm it exists first. See the memorise skill for the full verification workflow.
4. Never use scope:global unless storing a user preference