Trigger Examples

• "这个测试跑不过"
• "why is this returning null?"
• "报错了，帮我看看"
• "build fails with exit code 1"
• "investigate why the hook isn't firing"

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.

Violating the letter of this process is violating the spirit of debugging.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

Three Iron Laws of Code Debugging

1. No goto_definition = No modify — Don't change code you haven't navigated to its definition
2. No find_references = No refactor — Don't refactor without knowing all usage sites
3. No get_diagnostics = No claim fixed — Don't claim a fix without verifying zero new diagnostics

Investigation Document Protocol

The investigation document (docs/investigations/{date}-{topic}.md) is the persistent, cross-session record of a debugging effort. Create one at the start of every non-trivial debug session using skills/omk-debugging/investigation-template.md.

Three-Level Evidence System

Section Update Rules

Anti-regression Rules

These rules prevent new sessions from undoing prior investigation progress:

1. Overturning 🔒 L0 facts: Requires stronger L0 evidence (new command output or experiment). Must record both old and new evidence in the Evidence Table with explicit comparison.
2. Challenging 👤 L1 observations: Requires L0 evidence that contradicts the observation. Must document the challenge rationale in the Timeline.
3. Revising 🤖 L2 inferences: Free to revise. Mark the old inference struck (do not delete). New inference must note "取代 I{n}".
4. Decision Log: Rejected decisions must include rejection rationale. New sessions must NOT re-attempt a rejected approach unless new L0 evidence invalidates the rejection reason.
5. Ruled Out: Eliminated investigation directions must NOT be re-investigated unless new L0 evidence emerges that was unavailable when the direction was ruled out.

Tool Decision Matrix

When to use grep instead: Only for searching comments, string literals, config values, or non-code files.

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:

Step -1: Build Architectural Context (MANDATORY — do NOT skip)

Before looking at any specific code, build a map of the system around the bug. This step solves the "structural blindness" problem — LLMs process code as text and cannot see dependency graphs, call chains, or architectural boundaries without explicit navigation.

1. Run generate_codebase_overview to get the project's high-level module structure
2. For the bug's core symbol(s), run find_references to discover all callers and usage sites
3. For the bug's file(s), run get_document_symbols to understand internal structure
4. Produce an Architectural Context summary:

Architectural Context:
- Module: [where this code sits in the system architecture]
- Upstream callers: [who calls the buggy code — list file:function]
- Downstream dependencies: [what the buggy code depends on]
- Cross-module impact: [which other modules could be affected by a fix]
- Hidden dependencies: [files with no semantic overlap but architectural connection]

Why this is mandatory: CodeCompass research (258 trials) showed that dependency graph navigation achieves 99.4% architectural coverage on hidden dependencies vs 76.2% without (+23.2pp). Agents only explore dependencies voluntarily 42% of the time — when skipped, performance equals the no-tool baseline. This step must be forced, not optional.

Step 0: Check Past Episodes

• Read knowledge/episodes.md for similar past bugs
• Past mistakes often repeat — check before investigating from scratch

Step 0.5: Classify Failure Type (Failure Classification)

Before diving into investigation, classify the failure to guide your approach. Pick the most likely category:

Write your classification into the Diagnostic Evidence (Step 6). If unsure, pick the top 2 candidates and investigate both.

Step 1: Run get_diagnostics First

• Run get_diagnostics on the failing file(s) to get compiler errors, warnings, hints
• This gives you the exact error locations and types — far more precise than reading logs

Step 2: Use search_symbols to Find Relevant Code

• Use search_symbols to locate the function/class/variable involved in the error
• Follow up with goto_definition to read the actual implementation
• Use find_references to understand all callers and usage sites

Step 3: 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

Step 4: 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

Step 5: Check Recent Changes

• What changed that could cause this?
• Git diff, recent commits
• New dependencies, config changes
• Environmental differences
• If this is a regression (it used to work, now it doesn't): use the Git Bisect flow in reference.md to pinpoint the exact commit that introduced the bug

Step 6: Gather Diagnostic Evidence

You MUST produce a Diagnostic Evidence summary before moving to Phase 2:

Diagnostic Evidence:
- failure_type: [category from Step 0.5 classification]
- get_diagnostics: [what errors/warnings were found]
- search_symbols: [what symbols were located]
- find_references: [what callers/usage sites were found]
- get_hover: [what type information was revealed]
- key_variables:
  - var_name: [variable name]
    expected: [expected value at this point]
    actual: [actual value observed]
    location: [file:line where divergence occurs]
  - ...
- Root cause hypothesis: [your conclusion based on above]

Without this evidence, you cannot proceed.

Step 7: 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

Step 8: Trace Data Flow

WHEN error is deep in call stack:

• Use goto_definition to navigate to the error source
• Use find_references to trace callers backward
• Where does bad value originate?
• Keep tracing up until you find the source
• Fix at source, not at symptom

Phase 2: Pattern Analysis

Find the pattern before fixing:

1. Find Working Examples

   • Locate similar working code in same codebase
   • Use search_symbols to find similar patterns
   • 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

Phase 4: Implementation

Fix the root cause, not the symptom:

1. Run get_diagnostics Before Fix (baseline)

   • Record current diagnostics count and details
   • This is your "before" snapshot

2. Create Failing Test Case

   • Simplest possible reproduction
   • Automated test if possible
   • MUST have before fixing

3. Implement Single Fix

   • Address the root cause identified
   • ONE change at a time
   • No "while I'm here" improvements
   • No bundled refactoring

4. Run get_diagnostics After Fix (verify)

   • Compare with baseline: new diagnostics must be 0
   • All original diagnostics should be resolved or unchanged
   • If new diagnostics appeared, your fix introduced problems — revert

5. Verify Fix

   • Test passes now?
   • No other tests broken?
   • Issue actually resolved?

5.5. Self-Explanation (Rubber Duck Verification) After verifying the fix works, explain in natural language:

• Root cause: What exactly was wrong and why?
• Fix logic: Why does this fix resolve the root cause?
• Side effects: Could this fix introduce new problems? Check against the Architectural Context from Step -1.

If you discover a logical contradiction while explaining → STOP, return to Phase 3 and re-verify your hypothesis. The act of explaining often reveals flawed reasoning that testing alone misses.

6. If Fix Doesn't Work

   • STOP
   • Count: How many fixes have you tried?
   • If < 3: Return to Phase 1, re-analyze with new information
   • If ≥ 3: STOP and question the architecture (step 7 below)
   • DON'T attempt Fix #4 without architectural discussion

7. If 3+ Fixes Failed: Question Architecture

   Pattern indicating architectural problem:

   • Each fix reveals new shared state/coupling/problem in different place
   • Fixes require "massive refactoring" to implement
   • Each fix creates new symptoms elsewhere

   STOP and question fundamentals:

   • Is this pattern fundamentally sound?
   • Are we "sticking with it through sheer inertia"?
   • Should we refactor architecture vs. continue fixing symptoms?

   Discuss with your human partner before attempting more fixes

8. Post-Fix Review After the fix is verified and working:

   • Compare the original buggy code vs the fixed code — is the fix minimal?
   • Check: did the fix introduce any code smells (duplication, magic numbers, missing error handling)?
   • Check: does the fix need defensive programming at other call sites? (Refer to Architectural Context from Step -1)
   • Write a one-line summary for knowledge/episodes.md if this is a new bug pattern
   • Update the investigation document: set Status Overview to 🟢 Resolved, record final root cause and fix in Decision Log

Red Flags - STOP and Follow Process

If you catch yourself thinking:

• "Quick fix for now, investigate later"
• "Just try changing X and see if it works"
• "Add multiple changes, run tests"
• "Skip the test, I'll manually verify"
• "It's probably X, let me fix that"
• "I don't fully understand but this might work"
• "Pattern says X but I'll adapt it differently"
• "Here are the main problems: [lists fixes without investigation]"
• Proposing solutions before tracing data flow
• "One more fix attempt" (when already tried 2+)
• Each fix reveals new problem in different place
• Using grep to find code instead of search_symbols/find_references

ALL of these mean: STOP. Return to Phase 1.

If 3+ fixes failed: Question the architecture (see Phase 4.7)

Your Human Partner's Signals You're Doing It Wrong

Watch for these redirections:

• "Is that not happening?" - You assumed without verifying
• "Will it show us...?" - You should have added evidence gathering
• "Stop guessing" - You're proposing fixes without understanding
• "Ultrathink this" - Question fundamentals, not just symptoms
• "We're stuck?" (frustrated) - Your approach isn't working

When you see these: STOP. Return to Phase 1.

Common Rationalizations

Quick Reference

When Process Reveals "No Root Cause"

If systematic investigation reveals issue is truly environmental, timing-dependent, or external:

1. You've completed the process
2. Document what you investigated
3. Implement appropriate handling (retry, timeout, error message)
4. Add monitoring/logging for future investigation

But: 95% of "no root cause" cases are incomplete investigation.

Supporting Techniques

These techniques are part of systematic debugging and available in this directory:

• root-cause-tracing.md - Trace bugs backward through call stack to find original trigger
• defense-in-depth.md - Add validation at multiple layers after finding root cause
• condition-based-waiting.md - Replace arbitrary timeouts with condition polling

Related skills:

• superpowers:test-driven-development - For creating failing test case (Phase 4, Step 2)
• superpowers:verification-before-completion - Verify fix worked before claiming success