/omk-debugging

name: omk-debugging
description: "Systematic debugging: reproduce → hypothesize → verify → fix. Trigger when encountering bugs, test failures, errors, crashes, unexpected behavior, or when user says 'debug', 'not working', 'broken', 'fails', 'error', 'exception', 'why does this happen', 'investigate'. Also trigger on stack traces, error logs, or non-zero exit codes."

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

| Level | Label | Meaning | Mutability | |-------|-------|---------|------------| | 🔒 L0 | Machine Facts | Command output, code analysis, API responses, experiment results | **Immutable** — cannot be overridden except by stronger L0 evidence | | 👤 L1 | Human Observations | User-reported operations and phenomena | **Protected** — need L0 evidence + documented rationale to challenge | | 🤖 L2 | Agent Inferences | AI deductions, hypotheses, analysis conclusions | **Mutable** — can be revised freely; mark old entry ~~struck~~, keep original |

Section Update Rules

| Section | Update Mode | Rule | |---------|-------------|------| | Status Overview | **Overwrite** | Refresh after every Stage completion — must reflect current state at all times | | Evidence Table | **Append-only** | Never delete or edit existing entries; add new rows only | | Investigation Tree | **Overwrite** | Update branch statuses (⬜→✅/❌) as investigation progresses | | Decision Log | **Append-only** | Superseded decisions stay; mark status as "❌ 被 D{n} 取代" | | Experiment Log | **Append-only** | Each experiment gets a unique EXP-{n} ID for cross-reference | | Ruled Out | **Append-only** | Eliminated directions stay permanently to prevent re-investigation | | Timeline | **Append-only** | Chronological milestones, never rewritten |

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

| Bug Type | Tool Sequence | Why | |----------|--------------|-----| | Compile/type error | `get_diagnostics` → `goto_definition` → `get_hover` | Diagnostics pinpoint error; definition shows context; hover reveals types | | Wrong behavior | `search_symbols` → `find_references` → `goto_definition` | Find the symbol, trace all callers, read implementation | | Unknown codebase | `get_document_symbols` → `goto_definition` → `get_hover` | Map file structure, navigate to definitions, understand types | | Refactor broke something | `find_references` → `get_diagnostics` → `search_symbols` | Find all usage sites, check for new errors, locate related symbols | | Test failure | `get_diagnostics` → `search_symbols` → `find_references` | Check compiler errors first, find test subject, trace dependencies |

**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