debugging-patterns

What this skill does

# Systematic Debugging

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

This skill is advisory in v10. It deepens investigation quality. It does not authorize local-only patches, guesswork, or "fix the line that crashed" thinking.

## Reference Files

Read only the references needed for the current investigation:

- `references/root-cause-playbooks.md` for build/type failures, flaky tests, runtime crashes, browser errors, git bisect, and boundary tracing
- `references/investigation-hygiene.md` for context discipline, evidence logging, hypothesis tracking, restart protocol, and architectural escalation

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

If you haven't completed Phase 1, you cannot propose fixes.

## Quick Five-Step Process (Reference Pattern)

For rapid debugging, use this concise flow:

```
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal general fix
5. Verify solution works
```

**Debugging techniques:**
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- **Add strategic debug logging**
- **Inspect variable states**

**Root Cause Tracing Technique:**
```
1. Observe symptom - Where does error manifest?
2. Find immediate cause - Which code produces the error?
3. Ask "What called this?" - Map call chain upward
4. Keep tracing up - Follow invalid data backward
5. Find original trigger - Where did problem actually start?
```
**Never fix solely where errors appear—trace to the original trigger.**
After root cause is identified, scan for the same signature nearby before declaring success.

## LSP-Powered Root Cause Tracing

**Use LSP to trace execution flow systematically:**

| Debugging Need | LSP Tool | Usage |
|----------------|----------|-------|
| "Where is this function defined?" | `lspGotoDefinition` | Jump to source |
| "What calls this function?" | `lspCallHierarchy(incoming)` | Trace callers up |
| "What does this function call?" | `lspCallHierarchy(outgoing)` | Trace callees down |
| "All usages of this variable?" | `lspFindReferences` | Find all access points |

**Systematic Call Chain Tracing:**
```
1. localSearchCode("errorFunction") → get file + lineHint
2. lspGotoDefinition(lineHint=N) → see implementation
3. lspCallHierarchy(incoming, lineHint=N) → who calls this?
4. For each caller: lspCallHierarchy(incoming) → trace up
5. Continue until you find the root cause
```

**CRITICAL:** Always get lineHint from localSearchCode first. Never guess line numbers.

**For each issue provide:**
- Root cause explanation
- Evidence supporting diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

## Scenario Playbooks

Read `references/root-cause-playbooks.md` when the failure matches one of these
shapes:
- build or type breakage
- failing tests
- runtime crashes
- browser or console errors
- intermittent async bugs
- regressions where "it worked before"
- multi-component handoff failures

Keep this `SKILL.md` focused on the four-phase investigation workflow. Use the
reference for concrete commands, boundary tracing patterns, and git-bisect
recipes.

## When to Use

Use for ANY technical issue:
- Test failures
- Bugs in production
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues

**Use this ESPECIALLY when:**
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand the issue

**Don't skip when:**
- Issue seems simple (simple bugs have root causes too)
- You're in a hurry (rushing guarantees rework)
- Manager wants it fixed NOW (systematic is faster than thrashing)

## The Four Phases

You MUST complete each phase before proceeding to the next.

### Phase 1: Root Cause Investigation

**BEFORE attempting ANY fix:**

1. **Read Error Messages Carefully**
   - Don't skip past errors or warnings
   - They often contain the exact solution
   - Read stack traces completely
   - Note line numbers, file paths, error codes

2. **Reproduce Consistently**
   - Can you trigger it reliably?
   - What are the exact steps?
   - Does it happen every time?
   - If not reproducible → gather more data, don't guess

3. **Check Recent Changes**
   - What changed that could cause this?
   - Git diff, recent commits
   - New dependencies, config changes
   - Environmental differences

4. **Gather Evidence in Multi-Component Systems**

   **WHEN system has multiple components (CI → build → signing, API → service → database):**

   **BEFORE proposing fixes, add diagnostic instrumentation:**
   ```
   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer

   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   ```
   For a concrete boundary-tracing recipe, read
   `references/root-cause-playbooks.md`.

5. **Trace Data Flow**

   **WHEN error is deep in call stack:**
   - Where does bad value originate?
   - What called this with bad value?
   - Keep tracing up until you find the source
   - Fix at source, not at symptom

6. **Trace configuration to its consumer (third-party SDKs, env, import time)**

   **BEFORE proposing replacements, migrations, or large refactors:**

   - **Option Zero:** Can this be fixed with **only** a configuration or environment change? State and test that hypothesis *before* you propose code rewrites. Many integration bugs are wiring problems, not architecture problems.
   - When an env var is validated in application config but **never passed into** library constructors, ask **who reads it?** Third-party SDKs often read `process.env` (or language equivalents) at **module import / load time**—not through your app's DI or config objects. The fix may be setting or correcting env, not changing application code.
   - **Before** proposing to replace a third-party SDK, spend a short cycle on **how** it is configured: package README, official docs, or the installed source under `node_modules` (or vendor path). The failure may be a wrong endpoint or flag, not a need for a different library.
   - When code comments describe **import-time** behavior or env-var dependencies, treat them as **investigation breadcrumbs**, not decoration—follow them to the real consumer.

### Phase 2: Pattern Analysis

**Find the pattern before fixing:**

1. **Find Working Examples**
   - Locate similar working code in same codebase
   - What works that's similar to what's broken?

2. **Compare Against References**
   - If implementing pattern, read reference implementation COMPLETELY
   - Don't skim - read every line
   - Understand the pattern fully before applying

3. **Identify Differences**
   - What's different between working and broken?
   - List every difference, however small
   - Don't assume "that can't matter"

4. **Understand Dependencies**
   - What other components does this need?
   - What settings, config, environment?
   - What assumptions does it make?

### Phase 3: Hypothesis and Testing

**Scientific method:**

1. **Form Single Hypothesis**
   - State clearly: "I think X is the root cause because Y"
   - Write it down
   - Be specific, not vague

2. **Test Minimally**
   - Make the SMALLEST possible change to test hypothesis
   - One variable at a time
   - Don't fix multiple things at once

3. **Verify Before Continuing**
   - Did it work? Yes → Phase 4
   - Didn't work? Form NEW hypothesis
   - DON'T add more fixes on top

4. **When You Don't Know**
   - Say "I don't understand X"
   - Don't pretend to know
   - Ask for help
   - Research more

### Hypoth