debugging · diff
git:20260314.a3b7738 to git:20260519.40bb110
107 added, 93 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: debugging
- description: >-
- A systematic approach to debugging complex issues — from reproducing the problem to
- identifying root cause. Use this skill when investigating errors, stack traces, or
- unexpected behavior, when the cause of a bug is not immediately obvious, when dealing
- with intermittent or hard-to-reproduce issues, or when standard debugging approaches
- have failed. This complements autonomous-bug-fix with deeper diagnostic techniques.
+ description: Systematic root-cause investigation for hard bugs.
+ tier: practical
+ category: workflow
+ created_by: human
+ platforms: [windows, macos, linux]
+ tags: [debugging, diagnostics, root-cause]
+ author: Andreas Wasita (@andreaswasita)
---
- # Debugging
+ # Debugging Skill
- When the cause isn't obvious, be systematic. Debugging is investigation, not guessing.
+ Investigates hard or non-obvious bugs by gathering evidence, forming a hypothesis, and narrowing the search space — never by guessing or shotgun-changing code. Complements `autonomous-bug-fix` with deeper diagnostic technique. Does NOT replace running the failing test and reading the actual error.
## When to Use
- - The cause of a bug is not immediately obvious
- - Dealing with intermittent or hard-to-reproduce issues
- - Complex issues spanning multiple components
- - Standard approaches (read the error, fix the obvious) have failed
- - Performance issues, memory leaks, race conditions
+ - The cause of a bug is not immediately obvious.
+ - Intermittent or hard-to-reproduce failures.
+ - Bugs spanning multiple components or layers.
+ - Standard approaches ("read the error, fix the obvious") have failed.
+ - Performance regressions, memory leaks, race conditions.
+ - NOT when the failing test message already states the problem — just fix it.
- ## How to Use
+ ## Prerequisites
- ### The Debugging Mindset
+ - Ability to reproduce the failure (or evidence captured from production).
+ - The `view`, `grep`, `glob`, and `powershell` Copilot tools.
+ - `git` for history and bisect.
+ - A test or repro script that exhibits the bug.
- Two rules:
- 1. **The computer is not lying to you.** If the behavior is unexpected, your mental model is wrong.
- 2. **Every bug has a cause.** If you can't find it, you're not looking in the right place.
+ ## How to Run
- ### Step 1: Gather Evidence
+ ```text
+ 1. Reproduce the failure. Capture the exact error and stack.
+ 2. Gather evidence: recent commits, environment, inputs, logs.
+ 3. Form ONE hypothesis based on evidence.
+ 4. Test the hypothesis with the cheapest technique that disproves it.
+ 5. Narrow the layer, then the line.
+ 6. Write a regression test BEFORE the fix.
+ 7. Fix the root cause, not the symptom.
+ ```
- Before hypothesizing:
- ```bash
- # Read the actual error — all of it
- cat logs/error.log | tail -50
+ ## Quick Reference
- # Get the full stack trace
- # Check recent changes
- git log --oneline -10
+ | Technique | Use when |
+ |---|---|
+ | `git bisect` | Bug appeared recently, clean commit history |
+ | Print / log tracing | Need to see execution flow |
+ | Minimal repro | Complex system, need to isolate the variable |
+ | Breakpoint debugging | Need to inspect state at a specific point |
+ | Diff analysis (`git log`, `git diff`) | "It worked before" — something changed |
+ | Input shrinking | Test with smaller inputs until the failure stops |
- # Check if the issue is new or old
- git bisect start
- git bisect bad HEAD
- git bisect good <last-known-good-commit>
- ```
+ | Bug shape | First place to look |
+ |---|---|
+ | Race condition | Shared mutable state, missing `await`, missing lock |
+ | Memory leak | Growing collections, unclosed resources, retained refs |
+ | Performance | Database (N+1, missing index), network (uncached calls) |
+ | Intermittent | Timing, external dependencies, ordering assumptions |
- ### Step 2: Form a Hypothesis
+ ## Procedure
- Based on evidence, not hunches:
- - What changed recently? (`git log`, `git diff`)
- - What's different about the failing case? (input, environment, timing)
- - Where in the execution path does behavior diverge from expectation?
+ ### Step 1: Reproduce
- ### Step 3: Test the Hypothesis
+ Capture the exact failing command and full error output via the `powershell` tool. If you cannot reproduce locally, debugging is guessing. Stop and build a repro first.
- **Narrow down the cause systematically:**
+ ### Step 2: Gather Evidence
- | Technique | When to Use |
- |-----------|-------------|
- | **Binary search (git bisect)** | Bug appeared recently, clean commit history |
- | **Print/log debugging** | Need to trace execution flow |
- | **Minimal reproduction** | Complex system, need to isolate the variable |
- | **Breakpoint debugging** | Need to inspect state at a specific point |
- | **Diff analysis** | "It worked before" — find what changed |
- | **Input manipulation** | Test with simpler inputs to find the failing condition |
+ Inspect:
- ### Step 4: Apply Divide and Conquer
+ - Recent commits with `git log --oneline -10`.
+ - The diff of any commit touching the failing path.
+ - The full stack trace, including the "caused by" chain.
+ - Environment differences if it works elsewhere.
- For complex issues, isolate the layer:
+ Use `view` to read the offending code path. Use `grep` to locate related call sites.
- ```
- Request → Middleware → Controller → Service → Database
- ↑
- Narrow it down to this layer,
- then narrow within the layer
- ```
+ ### Step 3: Form a Hypothesis
- 1. **Is the input correct?** — Check what reaches each layer
- 2. **Is the output correct?** — Check what leaves each layer
- 3. **Find the gap** — The bug is where correct input produces incorrect output
+ Based on evidence — not intuition — write down a single hypothesis:
- ### Step 5: Fix and Prevent
+ > "The cache is stale because invalidation runs before the write completes."
- Once root cause is found:
- 1. Write a test that reproduces the bug
- 2. Fix the root cause (not the symptom)
- 3. Verify the fix resolves the original issue
- 4. Check for the same pattern elsewhere in the codebase
- 5. Log a lesson in `tasks/lessons.md` if the debugging technique was non-obvious
+ If you cannot articulate a hypothesis, you do not have enough evidence yet. Gather more.
- ## Debugging Specific Issues
+ ### Step 4: Disprove It Cheaply
- ### Race Conditions
- - Add logging with timestamps to trace execution order
- - Look for shared mutable state
- - Check for missing locks, missing `await`, or unguarded concurrent access
+ Choose the cheapest technique that would falsify the hypothesis:
- ### Memory Leaks
- - Profile memory over time, not just at one point
- - Look for growing collections, unclosed resources, or retained references
- - Event listeners and subscriptions are common culprits
+ - Add one print/log at the suspected divergence point.
+ - Run `git bisect` if a recent commit is suspect.
+ - Construct a minimal repro that isolates the variable.
- ### Performance Issues
- - Profile first, optimize second — never guess at bottlenecks
- - Check the database (N+1 queries, missing indexes, full table scans)
- - Check the network (unnecessary requests, missing caching)
+ ### Step 5: Narrow Layer → Line
- ### Intermittent Failures
- - Look for timing-dependent code (timeouts, race conditions)
- - Check for external dependencies (network, third-party APIs)
- - Run the failing test in a loop to gather more data
+ Walk the request through the system:
- ## Guidelines
+ ```text
+ Input → Layer A → Layer B → Layer C → Output
+ ```
- - **Read the error message.** Completely. Including the "caused by" chain.
- - Let evidence guide you, not intuition — intuition is wrong more often than you think
- - When stuck for >15 minutes, change your approach entirely
- - Subagents are excellent for parallel investigation of hypotheses
- - Document non-obvious debugging sessions in `tasks/lessons.md`
+ At each boundary, check: correct input in? correct output out? The bug lives at the boundary where correct input produces incorrect output.
- ## Anti-Patterns
+ ### Step 6: Regression Test First, Then Fix
- - **Shotgun debugging** — Changing random things and hoping something sticks
- - **Skipping the reproduction** — You can't fix what you can't see
- - **Blaming the framework** — It's almost always your code. Check your code first.
- - **Debugging in production** — Reproduce locally whenever possible
- - **Fixing without understanding** — If you can't explain why the fix works, you haven't found the root cause
+ Before changing code:
+
+ 1. Write a test that reproduces the bug. It must fail.
+ 2. Implement the fix.
+ 3. Run the test. It must pass.
+ 4. Run the full suite. No regressions.
+ 5. Search the codebase with `grep` for the same anti-pattern elsewhere.
+
+ ### Step 7: Log the Lesson
+
+ If the technique was non-obvious, append to `tasks/lessons.md`:
+
+ ```yaml
+ - date: 2026-05-19
+ error_type: stale-cache
+ trigger: "Test passed alone, failed in suite"
+ root_cause: "Cache invalidated before write committed"
+ fix: "Made invalidation await the write"
+ rule: "All cache invalidations follow the source mutation, not lead it"
+ ```
+
+ ## Pitfalls
+
+ - **DO NOT** shotgun-change code hoping something sticks.
+ - **DO NOT** skip the reproduction step. You cannot fix what you cannot see.
+ - **DO NOT** blame the framework first. It is almost always your code.
+ - **DO NOT** debug in production when local reproduction is possible.
+ - **DO NOT** ship a fix you cannot explain. If you cannot articulate why it works, you have patched a symptom.
+
+ ## Verification
+
+ - [ ] Failure was reproduced locally before any code change.
+ - [ ] A regression test exists and failed prior to the fix.
+ - [ ] The regression test now passes.
+ - [ ] The full test suite is green.
+ - [ ] The root cause is written down (commit message or `tasks/lessons.md`).