# Investigate > Root cause analysis skill — diagnose bugs systematically before fixing. Iron Law: no fix without a confirmed hypothesis. Uses scope lock, 3-strike escalation, and structured debug reports. - Skill: `shenxingy/investigate` (Agent Skill) - Install (CLI): `npx skillmds add shenxingy/investigate` - Raw SKILL.md: https://api.skillmd.com/api/skills/shenxingy/investigate/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: shenxingy (https://skillmd.com/u/shenxingy) - Updated: 2026-08-19 - Page: https://skillmd.com/skills/shenxingy/investigate --- # Clade for Codex This workflow runs **directly in Codex**. Do not launch the `claude` CLI or delegate the workflow to Clade's MCP bridge. Codex compatibility rules: - Plugin skills are namespaced. Invoke this workflow explicitly as `$clade:investigate`; a bare `$name` does not select the installed Clade plugin. - Read the nearest `AGENTS.md` files for repository instructions. If a project has only `CLAUDE.md`, treat it as legacy project guidance and read it too. - Store new Clade working state under `.clade/` (or `~/.clade/` for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state. - A `/skill-name` reference means the corresponding Codex `$clade:skill-name` plugin skill, or the same workflow invoked naturally when explicit skill invocation is not available. - Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI. - Paths such as `/...` are relative to the installed Clade plugin containing this `SKILL.md`; resolve that root before invoking a helper. ## Canonical Clade workflow You are the Investigate skill. You diagnose bugs and failures systematically using root cause analysis. ## Iron Law **No fix without a confirmed root cause hypothesis.** Fixing symptoms wastes time and creates new bugs. Understand why something is broken before touching the code. --- ## Phase 1: Collect Symptoms Re-ground on context before diving in: ```bash git branch --show-current git log --oneline -10 ``` Gather what's known: - What exactly is failing? (error message, stack trace, unexpected behavior) - Is it reproducible? On every run or intermittent? - When did it start? Check recent commits: ```bash git log --oneline -20 -- ``` - What changed recently that could have introduced this? If the symptom description is vague, ask the user ONE specific question before continuing (not a list — one question at a time): > **Re-ground:** [project + branch + task] > **Question:** [single concrete question] > **Why:** I need this to narrow down where to look. --- ## Phase 2: Code Path Tracing Read the relevant code. Don't guess — trace the actual execution path: 1. Identify the entry point (route, function call, script invocation) 2. Use Grep to find where the error originates 3. Read the files in the call chain — follow imports, not assumptions 4. Check recent changes to the affected files: ```bash git log --oneline -20 -- git show HEAD~1 -- # what changed in last commit? ``` **Output a root cause hypothesis** at this point — a specific, testable claim: ``` Root cause hypothesis: : — Example: "auth.py:142 — token expiry check uses UTC naive datetime but DB stores UTC+8, causes valid tokens to appear expired during 00:00–08:00 window" ``` --- ## Phase 3: Scope Lock Once you have a hypothesis, identify the minimum scope needed to fix it: ```bash echo "/" > .clade/freeze-dir.txt ``` This is a commitment: all edits should stay within this scope. If the fix expands significantly beyond it, re-evaluate whether you've found the right root cause. --- ## Phase 4: Hypothesis Testing **Before writing any fix**, verify the hypothesis with evidence: - Add a temporary log/assertion to confirm the exact failure point - Run the failing scenario - Does the log confirm your hypothesis? **3-strike rule:** If your hypothesis is wrong, form a new one. After 3 failed hypotheses, stop and ask: > **Context:** [project + branch + what was tried] > **RECOMMENDATION:** Option A — add instrumentation and let it fail naturally in the next real occurrence, because shotgun debugging without data is counterproductive. > > A. Add observability (log + metric) and wait for next occurrence `Completeness: 8/10` (human: ~15min / Codex: ~20min) > B. Escalate to a more senior debugger / fresh pair of eyes `Completeness: 7/10` (human: ~30min / Codex: N/A) > C. Continue investigating with a different approach `Completeness: 5/10` (human: ~1h / Codex: ~45min) --- ## Phase 5: Known Pattern Analysis Check if this matches a known failure pattern: | Pattern | Signals | |---|---| | Race condition | Works in isolation, fails under load or with concurrent ops | | Null propagation | `NoneType`, `undefined`, `null pointer` errors deep in call chain | | State corruption | Correct on first run, wrong after repeated use / restart | | Integration failure | Works in unit tests, fails with real dependencies | | Config drift | Works on one machine/env, fails on another | | Stale cache | Old data persists after state change | | Off-by-one | Fencepost errors, wrong range boundaries | | Timezone/encoding | Works locally, fails with different locale/TZ | If the pattern is recognized, reference it explicitly in your hypothesis. --- ## Phase 6: Implement Fix Fix the **root cause**, not the symptom. Rules: - **Minimal diff** — touch only what's necessary to fix the root cause - **No refactoring** — if you see unrelated issues, note them but don't fix them now - **Write the regression test first** — a test that fails WITHOUT the fix and passes WITH it - Remove any temporary debugging logs **Blast radius gate:** If the fix requires changes to more than 5 files, stop and ask: > **Context:** [project + branch] > **This fix touches N files — broader than expected.** > **RECOMMENDATION:** Option A — confirm this is the right root cause before proceeding, because wide blast radius often signals we're fixing the wrong layer. > > A. Confirm root cause + proceed with full fix `Completeness: 9/10` (human: ~10min / Codex: ~30min) > B. Find a narrower fix at a higher layer `Completeness: 7/10` (human: ~20min / Codex: ~20min) > C. Split into two commits: fix + refactor `Completeness: 8/10` (human: ~15min / Codex: ~25min) --- ## Phase 6b: Root Cause Is in a Dependency If tracing landed in a third-party package (not this codebase), the Iron Law still applies — and a recording law joins it: **a dependency bug handled silently is a bug planted for the next person.** 1. **Isolate a minimal repro** — strip the project away until the bug reproduces against the dependency alone. Save it as `.clade/repro/-.py` (or as an xfail/skipped test in `tests/` referencing the upstream issue). 2. **Search the upstream tracker** — `gh search issues --repo ""` or web search. It may already be reported, fixed in a newer release, or have a documented workaround. 3. **Resolve in strict preference order:** - **a. Upstream patch PR** — fix it at the source; link the PR in your commit body - **b. Pin the version + linked issue** — pin to the last good version, add a TODO.md entry with the upstream issue URL and an unpin condition ("unpin when ≥ X.Y.Z ships the fix") - **c. Documented workaround** — code-level workaround with a comment naming the upstream issue URL, plus a TODO.md entry 4. **Never silent.** Whichever branch you take, the upstream link must appear in a code comment, TODO.md, or the commit body — an unrecorded workaround becomes permanent and unexplainable. 5. **Never monkey-patch the installed copy** — edits inside `.venv/` or `node_modules/` evaporate on the next install. --- ## Phase 7: Verify & Report Run the full test suite after fixing: ```bash # Run project tests # (check AGENTS.md for the test command) ``` Then output the structured debug report: ``` DEBUG REPORT ════════════════════════════════════════ Symptom: [what the user observed] Root cause: [specific file:line — what was wrong and why] Fix: [file:line — what was changed] Evidence: [test output or log showing the fix works] Regression test: [file:line of new test] Related: [any TODOS.md items or related issues discovered] ════════════════════════════════════════ ``` --- ## Completion Status End every run with one of: - ✅ **DONE** — root cause found, fix applied, regression test written, report output - ⚠ **DONE_WITH_CONCERNS** — fix applied but hypothesis confidence is medium; monitor in production - ❌ **BLOCKED** — cannot reproduce or hypothesis exhausted; details written to `.clade/blockers.md` - ❓ **NEEDS_CONTEXT** — not enough information to proceed; specific question asked **3-strike rule:** After 3 failed hypotheses, always switch to BLOCKED — don't keep guessing. --- ## What NOT to do - Fix before forming a hypothesis - Change multiple things at once to "see what works" - Skip the regression test - Leave debugging logs in the code - Treat a passing test as proof — verify the specific failure scenario --- ## Deep-Dive Mode (optional) For complex bugs requiring multi-file execution tracing, spawn the `debug-specialist` subagent: ``` Use a Codex subagent when available with subagent_type="debug-specialist": "Trace the root cause of: [symptom]. Entry point: [file:function]. Known context: [what you've already found]" ``` The subagent reads code and forms hypotheses but cannot modify files. Merge its root cause finding into your Phase 6 fix. --- ## Error Handling | Scenario | Action | |----------|--------| | Cannot reproduce the bug | Ask user for exact reproduction steps (ONE specific question). Do not guess. | | Symptom is too vague ("it's slow", "it crashes sometimes") | Ask for a concrete example: specific error message, specific input, specific timing | | Files implicated are very large (>2000 lines) | Use Grep to locate the specific section before reading; use offset/limit on Read | | Bug is in a dependency (not this codebase) | Go to Phase 6b: minimal repro → upstream patch > pin-with-linked-issue > documented workaround. Never patch the installed copy in-place. | | Hypothesis requires runtime data not visible in code | Suggest specific logging/assertion to add. Output as NEEDS_CONTEXT with exact location and what to log. | | 3 hypotheses exhausted, still no root cause | Output BLOCKED — write to `.clade/blockers.md` with what was tried and what's needed | ## Delivery completion If this workflow changes files or external state: - Inspect the real final state before responding, including `git status` for a repository task. - Never report `DONE` while task-owned changes are uncommitted. Use or continue `$clade:delivery` and create a repository-compliant checkpoint or preserve the work when committing is unavailable. - When the user request or trusted repository policy makes publication, deployment, or live verification part of the task, do not silently downgrade the result to local-only work. - If a required delivery transition lacks authority, credentials, a destination, or reachable external state, report `BLOCKED` or `NEEDS_CONTEXT` rather than appending a "not committed/pushed/deployed" caveat after `DONE`.