Debug Error

Guided workflow for diagnosing errors/failures and producing a durable fix.

Usage

/debug

Use this after pasting an error message, log output, or describing a failure.

What It Does

1. Understand the Failure

• •Extracts error type, message, codes, stack trace, reproduction steps
• •Captures expected vs actual behavior and environment/context
• •Pinpoints failing module/function and triggering inputs
• •Notes execution context: service/container, working directory, env vars
• •Confirms environment is properly configured

2. Trace Root Cause

• •Walks call stack upward until finding first invalid state/data
• •Inspects inputs at each layer (params, config, environment, cwd)
• •Adds temporary instrumentation if unclear (prints context to stderr)
• •For test failures: narrows with pytest --collect-only, -k, etc.
• •Classifies issue (data, state, logic, integration, configuration)
• •Checks surrounding code and recent changes for regressions
• •Records original trigger and fixes at the source (not symptom)

Temporary instrumentation (Python):

import sys, traceback

def debug_context(note, **kwargs):
    print(f"DEBUG {note}: {kwargs}", file=sys.stderr)
    print(''.join(traceback.format_stack(limit=15)), file=sys.stderr)

3. Validate Root Cause

• •Explains how root cause produces observed failure
• •Scans for other paths that could hit same issue
• •Proves via minimal reproduction or targeted test

4. Plan the Fix

• •Addresses underlying bug, not symptom
• •Outlines candidate fixes, notes trade-offs
• •Provides step-by-step resolution plan
• •Suggests targeted tests or monitoring to prevent recurrence
• •Adds defense-in-depth: validates inputs at boundaries, fails fast

5. Apply Project Standards

• •Respects/updates existing AIDEV-* notes
• •Follows logging levels (warning for expected, error with exc_info=True for unexpected)
• •Keeps FastAPI code async-first
• •Scopes changes to the fix

Notes

• •Always trace to root cause before fixing
• •Add temporary instrumentation if needed, remove after
• •Validate the fix resolves the issue
• •Consider adding tests to prevent recurrence