# Systematic Debugging > Methodical problem-solving approach for diagnosing and resolving code issues in any stack before attempting a fix Use when this capability is needed. - Skill: `tomevault-io/systematic-debugging-38` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/systematic-debugging-38` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/systematic-debugging-38/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/systematic-debugging-38 --- # Systematic Debugging Skill A structured approach to debugging that ensures thorough diagnosis before attempting fixes. The discipline is stack-agnostic and applies equally to TypeScript/Node, Python, Go, or any other language and runtime. ## When to Use This Skill Use this skill when: - An implementation agent fails with an error - Tests are failing unexpectedly - Runtime behavior does not match expectations - Build or compilation errors occur ## The Debugging Protocol ### Phase 1: Error Capture **DO NOT** attempt to fix anything until you understand: ```markdown ## Error Analysis ### Exact Error ``` [paste exact error message] ``` ### Error Location - File: [path/to/file] - Line: [line number] - Function: [function name] ### Error Type - [ ] Compilation error - [ ] Runtime error - [ ] Test failure - [ ] Build failure - [ ] Infrastructure error ### Trigger What action caused this error? ``` ### Phase 2: Context Gathering Before diagnosing, gather context: ```bash # Recent changes git log --oneline -10 # Changes in affected file git diff HEAD~5 -- [file_path] # Related files grep -r "[error_pattern]" --include="*.ts" ``` ### Phase 3: Root Cause Analysis Use the "5 Whys" technique: ```markdown ## Root Cause Analysis 1. **Why did the error occur?** [Direct cause, e.g., "Property 'x' does not exist on type 'Y'"] 2. **Why does property 'x' not exist?** [e.g., "The type definition was changed"] 3. **Why was the type definition changed?** [e.g., "A schema migration removed the field"] 4. **Why wasn't the code updated?** [e.g., "The dependent service wasn't identified"] 5. **Why wasn't it identified?** [ROOT CAUSE, e.g., "No automated dependency check"] ``` ### Phase 4: Impact Assessment ```markdown ## Impact Assessment ### Direct Impact - [File/component directly affected] ### Cascade Impact - [Other components that depend on the affected code] ### Test Impact - [Tests that will fail due to this issue] ### User Impact - [How this affects end users if deployed] ``` ### Phase 5: Fix Strategy **Only after completing phases 1-4:** ```markdown ## Fix Strategy ### Approach [Description of the fix approach] ### Files to Modify 1. `path/to/file1.ts` - [what to change] 2. `path/to/file2.ts` - [what to change] ### Code Changes ```typescript // BEFORE [problematic code] // AFTER [fixed code] ``` ### Verification Steps 1. [Step to verify fix works] 2. [Step to verify no regressions] ``` ### Phase 6: Prevention ```markdown ## Prevention ### Why This Happened [Brief explanation] ### How to Prevent - [ ] Add test case for this scenario - [ ] Add type check - [ ] Add documentation - [ ] Update dependency tracking ``` ## Common Error Patterns ### TypeScript Compilation Errors | Error | Likely Cause | Investigation | |-------|--------------|---------------| | Property 'x' does not exist | Type changed, typo | Check interface definition | | Cannot find module | Missing import, path error | Check tsconfig paths | | Type 'X' is not assignable | Type mismatch | Check both type definitions | | Argument of type 'X' | Function signature changed | Check function definition | ### ORM / Data-Layer Errors These examples use a generic ORM pattern. [CUSTOMIZE: replace with your ORM's error vocabulary, e.g., Drizzle, TypeORM, SQLAlchemy, or similar.] | Error | Likely Cause | Investigation | |-------|--------------|---------------| | Unknown field | Schema changed after last code-gen | Re-run schema generation | | Invalid model call | Model renamed or removed | Check the schema file | | Foreign key constraint | Data integrity issue | Check relation definitions | ### Runtime Errors | Error | Likely Cause | Investigation | |-------|--------------|---------------| | Cannot read property of undefined | Null reference | Add null checks | | Maximum call stack exceeded | Infinite recursion | Check recursive calls | | Connection refused | Service down | Check infrastructure | ## Debugger Agent Output Format ```markdown ## Debugging Report ### Error Summary [One sentence description] ### Root Cause [Identified root cause from 5 Whys analysis] ### Affected Components | Component | Impact Level | Fix Required | |-----------|--------------|--------------| | [file/service] | HIGH/MED/LOW | Yes/No | ### Recommended Fix #### Files to Modify 1. `[path]` - [change description] #### Code Changes ```typescript // File: [path] // Line: [n] // Replace: [old code] // With: [new code] ``` #### Verification ```bash [verification commands] ``` ### Prevention [How to prevent this in future] ``` ## Integration with Multi-Agent System When called by the supervisor agent, the debugger agent receives an error payload and returns a structured diagnosis. [CUSTOMIZE: adjust field names to match your work-package and agent naming conventions.] ``` supervisor -> debugger: { "error": "[error message]", "context": { "workPackage": "WP-01", "agent": "impl-agent", "files": ["path/to/file.ts"], "recentChanges": "[git diff output]" } } debugger -> supervisor: { "status": "DIAGNOSED", "rootCause": "[explanation]", "fix": { "files": ["path/to/file.ts"], "changes": "[code changes]", "verification": ["npx tsc --noEmit"] }, "prevention": "[suggestion]" } ``` ## Anti-Patterns ### DON'T: - Jump to fixing without understanding the error - Make multiple changes at once - Assume the error message is the root cause - Skip verification after fix - Ignore prevention analysis ### DO: - Follow the phases in order - Isolate the exact error location - Understand the full impact - Fix one thing at a time - Verify thoroughly - Document for future reference --- > Source: [mnzralee/claude-multi-agent-architecture](https://github.com/mnzralee/claude-multi-agent-architecture) — distributed by [TomeVault](https://tomevault.io).