error-detective

Error Detective - Systematic Debugging and Error Resolution

Overview

Error Detective is a comprehensive debugging skill that applies systematic methodologies to identify, analyze, and resolve errors efficiently. Using the TRACE framework and structured analysis techniques, this skill guides you through debugging from initial error discovery to verified resolution.

Core Capabilities

Stack Trace Analysis

• Parse and interpret stack traces across multiple languages
• Identify root cause vs. symptom errors
• Extract relevant file paths and line numbers
• Understand call chains and error propagation

Error Pattern Recognition

• Categorize errors by type (syntax, runtime, logic, integration)
• Identify common error patterns and anti-patterns
• Recognize framework-specific errors
• Map errors to likely root causes

Root Cause Analysis

• Distinguish between symptoms and underlying issues
• Follow error chains to original source
• Identify environmental vs. code issues
• Detect configuration and dependency problems

Debugging Workflow Management

• Structured investigation process
• Hypothesis generation and testing
• Iterative refinement of understanding
• Documentation of findings and solutions

The TRACE Framework

TRACE is a systematic five-step approach to debugging any error:

T - Trace the Error

Objective: Capture complete error information and context

1. Collect the full error message
2. Complete stack trace (not just first few lines)
3. Error type and message
4. Timestamp and occurrence frequency
5. Environment where error occurred

1. Identify error location
2. Exact file and line number
3. Function or method where error occurred
4. Code context (surrounding lines)
5. Call stack from entry point to error

1. Gather reproduction steps
2. Minimal steps to reproduce
3. Input data or parameters used
4. Expected vs. actual behavior
5. Consistency of reproduction (always, intermittent, rare)

R - Read the Error Message

Objective: Extract all information from the error itself

1. Parse error components
2. Error type/class (TypeError, ValueError, etc.)
3. Error message content
4. Suggested fixes (if provided)
5. Related errors or warnings

1. Understand error semantics
2. What the error type means in this language/framework
3. What conditions trigger this error
4. What the error message is specifically telling you
5. Any error codes or status codes

1. Identify error category
2. Syntax error (code won't parse)
3. Runtime error (code crashes during execution)
4. Logic error (wrong results, no crash)
5. Integration error (external system failure)
6. Performance error (timeout, resource exhaustion)

A - Analyze the Context

Objective: Understand the broader context around the error

1. Code analysis
2. Review the failing line and surrounding code
3. Check recent changes to this code
4. Examine function/method signature and usage
5. Review related code that calls or is called by failing code

1. Data analysis
2. Inspect input values at point of failure
3. Check data types and structures
4. Verify data meets expected format/constraints
5. Identify edge cases or unexpected values

1. Environment analysis
2. Check dependencies and versions
3. Review configuration files
4. Verify environment variables
5. Confirm required resources are available (files, network, memory)

1. State analysis
2. Application state at time of error
3. Previous operations that led to this state
4. Shared state or global variables involved
5. Database or external system state

C - Check for Root Cause

Objective: Identify the underlying issue, not just symptoms

1. Follow the error chain
2. Start at bottom of stack trace (first error)
3. Work up to find originating cause
4. Distinguish between error origin and error handlers
5. Identify wrapped or re-thrown errors

1. Test hypotheses
2. Generate specific, testable hypotheses
3. Isolate variables (change one thing at a time)
4. Use logging/debugging tools to verify assumptions
5. Document which hypotheses are confirmed or rejected

1. Common root causes
2. Null/undefined values: Missing initialization or validation
3. Type mismatches: Incorrect data type passed or returned
4. Off-by-one errors: Array/loop boundary issues
5. Race conditions: Timing-dependent failures
6. Resource exhaustion: Memory, disk, connections depleted
7. Configuration errors: Wrong settings or missing config
8. Dependency issues: Version conflicts or missing libraries
9. Permission errors: Insufficient access rights
10. Network errors: Connectivity, timeout, DNS issues
11. Data corruption: Invalid or unexpected data format

E - Execute the Fix

Objective: Implement and verify the solution

1. Design the fix
2. Address root cause, not symptoms
3. Consider side effects and edge cases
4. Plan for backward compatibility if needed
5. Choose most maintainable solution

1. Implement carefully
2. Make minimal, targeted changes
3. Add validation and error handling
4. Include logging for future debugging
5. Document the fix and reasoning

1. Verify thoroughly
2. Confirm original error is resolved
3. Test with reproduction steps
4. Test edge cases and related functionality
5. Verify no new errors introduced

1. Document and prevent
2. Document what caused the error
3. Document the solution and why it works
4. Add tests to prevent regression
5. Update documentation or add warnings if needed

Debugging Workflow

Initial Assessment (5 minutes)

1. Read complete error message
2. Identify error type and severity
3. Check if error is reproducible
4. Assess impact (blocking, degraded, cosmetic)
5. Decide investigation priority

Deep Investigation (15-30 minutes)

1. Apply TRACE framework systematically
2. Use debugging tools (see scripts/debug_helper.py)
3. Generate and test hypotheses
4. Document findings as you go
5. Narrow down to root cause

Solution Implementation (varies)

1. Design fix addressing root cause
2. Implement with proper error handling
3. Add logging and validation
4. Test thoroughly
5. Document solution

Verification and Prevention (10 minutes)

1. Verify fix with original reproduction steps
2. Test related functionality
3. Add regression tests
4. Update documentation
5. Deploy and monitor

Common Error Patterns by Language

Python

AttributeError: 'NoneType' has no attribute 'X'

• Root cause: Variable is None when expecting object
• Check: Initialization, function return values, API responses
• Fix: Add null checks, ensure proper initialization

KeyError: 'key_name'

• Root cause: Dictionary missing expected key
• Check: Data source, parsing logic, key spelling
• Fix: Use .get() with default, validate data structure

ImportError / ModuleNotFoundError

• Root cause: Module not installed or not in path
• Check: requirements.txt, virtual environment, PYTHONPATH
• Fix: Install missing package, fix import path

IndentationError

• Root cause: Inconsistent spacing (tabs vs spaces)
• Check: Editor settings, copied code
• Fix: Standardize to spaces (PEP 8), use linter

JavaScript/TypeScript

TypeError: Cannot read property 'X' of undefined

• Root cause: Accessing property on undefined object
• Check: Object initialization, async timing, API responses
• Fix: Optional chaining (?.operator), null checks

ReferenceError: X is not defined

• Root cause: Variable used before declaration or out of scope
• Check: Variable declaration, scope, hoisting issues
• Fix: Declare variable, fix scope, check imports

Promise rejection / Uncaught (in promise)

• Root cause: Async operation failed without catch handler
• Check: API calls, file operations, async/await usage
• Fix: Add .catch(