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=Truefor 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