debugging

name	debugging
description	Systematically analyzes errors, identifies root causes, and suggests targeted fixes with regression safeguards.

Debugging Skill

When debugging issues, follow a systematic approach to identify root causes efficiently and propose safe fixes.

1. Understand the Problem

• Read the full error message, stack trace, and any associated logs
• Identify the exact file, line number, and function where the error originates
• Determine whether the issue is a compile-time error, runtime exception, or logic bug
• Reproduce the issue mentally by tracing the code path from entry point to failure
• Check if the error message is from application code, a framework, or a third-party library

2. Check Common Issues First

• Null/undefined references: Accessing properties on null, undefined, nil, or None values
• Type errors: Passing wrong types, missing type coercion, incorrect generics
• Race conditions: Concurrent access to shared state without synchronization
• Off-by-one errors: Array bounds, loop conditions, pagination offsets
• Import/dependency issues: Missing imports, circular dependencies, version conflicts
• Configuration errors: Wrong environment variables, missing config files, incorrect connection strings
• State management bugs: Stale state, mutation of supposedly immutable data, missing state updates

3. Analyze the Stack Trace

• Read the stack trace bottom-up to find the originating call
• Identify the boundary between application code and library/framework code
• Look for the last application-level frame — that is usually where the bug lives
• Check if the error is thrown directly or wrapped/re-thrown from a deeper call
• For async code, check if the stack trace includes async boundaries (some frameworks lose context)

4. Investigate the Context

• Read the function containing the error and its callers
• Check recent changes to the affected files (git blame, git log)
• Look for related issues or known bugs in the project's issue tracker
• Check if the error occurs only under specific conditions (certain inputs, environments, timing)
• Review test coverage for the affected code — missing tests often correlate with bugs

5. Identify the Root Cause

• Distinguish between the symptom (where the error appears) and the cause (where the bug is)
• Trace data flow backward from the failure point to find where the invalid state was introduced
• Check preconditions: are function inputs valid? Are required fields populated?
• For intermittent bugs, look for timing dependencies, caching issues, or non-deterministic behavior
• For regression bugs, identify what changed (new code, dependency update, config change)

6. Propose a Fix

• Fix the root cause, not just the symptom
• Explain why the fix works, not just what it changes
• Keep the fix minimal — change only what is necessary to resolve the issue
• Preserve existing behavior for all paths that are not affected by the bug
• If the fix requires a design change, explain the tradeoff and alternatives considered

7. Prevent Regressions

• Write a test that reproduces the bug and verifies the fix
• The test should fail without the fix and pass with it
• Check if similar patterns exist elsewhere in the codebase that might have the same bug
• Consider adding runtime validation or assertions at the boundary where the bug entered
• If the bug was caused by a missing null check, consider enabling stricter null checking project-wide

8. Communicate Findings

• Summarize: what was the error, what caused it, and how it was fixed
• Include the file paths and line numbers of the changes
• Note any follow-up tasks (e.g., refactoring to prevent similar issues, adding monitoring)
• If the fix is a workaround, document the ideal solution and create a follow-up ticket