kaimingwan/oh-my-kiro/omk-debugging

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?

1. Compare Against References

• If implementing pattern, read reference implementation COMPLETELY
• Don't skim - read every line
• Understand the pattern fully before applying

1. Identify Differences

• What's different between working and broken?
• List every difference, however small
• Don't assume "that can't matter"

1. 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

1. Test Minimally

• Make the SMALLEST possible change to test hypothesis
• One variable at a time
• Don't fix multiple things at once

1. Verify Before Continuing

• Did it work? Yes → Phase 4
• Didn't work? Form NEW hypothesis
• DON'T add more fixes on top

1. When You Don't Know

• Say "I don't understand X"
• Don't pretend to know
• Ask for help
• Research more