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"

# Navigate an unfamiliar large suspect file when its structure is needed
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. Read the failing function or known stack-trace ranges directly
2. Use code_references to find callers of the failing function
3. Read the relevant execution path; use code_outline when unfamiliar large-file structure would help locate the next section, or batch known symbols with code_read_symbol
4. Check type definitions with code_search kind="interface"

Read the full file when it is small or most contents are needed. Extra navigation rounds can outweigh smaller responses; use outlines when they resolve missing context.

Step 4: Form Hypotheses

Based on the error type, consider these causes:

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

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 - Navigate unfamiliar large files when their structure is needed
• 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