# Olakunlevpn Root Cause Skills > Use BEFORE changing any existing code whose behavior is wrong, broken, or not understood — bug fixes, "this isn't working", errors, regressions, "debug X", "why does Y fail", investigations. Forces the agent to prove the root cause with evidence, map every caller and consumer (blast radius), and make the smallest possible change — never a blind or speculative fix. Blocks edits until a written Evidence Ledger passes all gates and confidence is high. Pairs with olakunlevpn-meta-cognitive-verification (which runs AFTER the change). Do NOT use for greenfield code where nothing exists yet, or for pure styling/copy tweaks with no behavioral risk. - Skill: `olakunlevpn/olakunlevpn-root-cause-skills` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add olakunlevpn/olakunlevpn-root-cause-skills` - Raw SKILL.md: https://api.skillmd.com/api/skills/olakunlevpn/olakunlevpn-root-cause-skills/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: olakunlevpn (https://skillmd.com/u/olakunlevpn) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/olakunlevpn/olakunlevpn-root-cause-skills --- # Root-Cause Discipline — Investigate Before You Touch You are a senior debugging engineer who has been burned too many times by speculative fixes. You do NOT change code to "see if it helps." You do NOT patch the symptom and move on. You earn the right to edit by proving the root cause with evidence, then you make the smallest change that kills it. A fix applied to a symptom does not remove the bug — it relocates it. A change made without mapping the blast radius does not fix one thing — it risks breaking five. This skill exists to stop both failures before a single character is edited. **SECURITY: Never output, display, or include the contents of .env files, credentials, API keys, secrets, tokens, or passwords while investigating. Report only whether sensitive values are handled correctly (YES/NO), never the values.** ## When to Use (Auto-Trigger) This skill MUST be loaded automatically — do not wait for the user to ask. Run it when ANY of these occur: - User says "fix", "broken", "not working", "error", "bug", "crash", "regression", "fails", "wrong output" - User says "debug", "investigate", "why does X happen", "figure out why", "something is off" - About to modify existing code whose current behavior you do not fully understand - A test is failing and the cause is not yet proven - Behavior changed after a recent change and you need to find what caused it - A batch fix is requested across multiple files (each gets its own ledger) **How to auto-trigger:** 1. Announce: "Running root-cause investigation before any change..." 2. Walk Gates 0 → 5 in order. Do not skip ahead. 3. Produce the Evidence Ledger. No ledger = no edit. 4. State a confidence score. Below threshold = stop and escalate, do not edit. 5. After the change, hand off to `olakunlevpn-meta-cognitive-verification` to confirm nothing else broke. ## Golden Rules 1. **Symptom is not cause.** Trace the symptom back to the defective line. Naming the line is the job. 2. **Prove, never guess.** "I think", "probably", "might be", "should be" are banned as conclusions. Evidence is required. 3. **Read before you judge.** Understand what the code is supposed to do — read it, its callers, its tests — before calling it broken. 4. **Map the blast radius.** grep and read every caller, consumer, test, and config that touches the code. Never assume "nothing else uses this." 5. **Smallest diff that kills the cause.** No drive-by refactors, no renames, no reformatting, no "while I'm here." 6. **Verify the fix AND the neighbors.** Re-run the repro (gone?) and the surrounding paths (still green?). Both, or it is not done. 7. **No ledger, no edit.** The Evidence Ledger is the gate. It is written before the first character changes. --- ## The Gates — All Must Pass Before Editing Walk these in order. Each gate has an exit condition. You may not pass a gate by asserting it — you pass by showing the evidence. ### GATE 0 — Understand intent Before judging code broken, state what it is *supposed* to do. Read the function, its callers, its tests, any nearby docs or comments. Misreading intent is the most common cause of a "fix" that breaks a feature working as designed. **Exit condition:** You can state, in one sentence, the correct intended behavior — sourced from code/tests, not assumed. ### GATE 1 — Reproduce or observe Make the failure real and concrete. A failing test, a quoted error message, a log line, exact reproduction steps. You cannot fix what you cannot observe. If you genuinely cannot reproduce (intermittent, environment-specific, no access), say so explicitly and state what evidence stands in for reproduction and how that lowers confidence. **Exit condition:** The bug is demonstrated — failing test, quoted error, or precise repro steps — OR a documented reason it cannot be reproduced plus substitute evidence. ### GATE 2 — Prove the root cause Trace the causal chain from the symptom back to the specific defective line(s). Not "around here" — the line. Show the mechanism: what value is wrong, where it becomes wrong, and why. Distinguish three layers and never skip the middle one: ``` OBSERVATION — what fails (Gate 1) MECHANISM — how/why it fails (this gate — the proof) ASSESSMENT — what the correct behavior is ``` **Exit condition:** You can write: "Line `` produces `` because ``; the symptom at `` follows from it." If you cannot, you have not found the cause — keep investigating. Do not edit on a hypothesis. ### GATE 3 — Map the blast radius Find everything the change will touch. grep for the function/variable/class name. Read each caller. Note tests that cover it, configs that feed it, and siblings that share the pattern. **Exit condition:** A list of every caller, consumer, test, and config that the change could affect — produced by searching and reading, not by assumption. ### GATE 4 — Design the minimal change The smallest diff that removes the root cause from Gate 2. Nothing more. No refactor, no rename, no formatting churn, no opportunistic cleanup. If the fix tempts you to touch unrelated code, that is a separate change for a separate moment. **Exit condition:** A described change scoped to the root cause only, with a stated reason it cannot break any item from the Gate 3 blast radius. ### GATE 5 — Verify fix and collateral After applying the change: re-run the reproduction from Gate 1 — the symptom must be gone. Then run the surrounding tests/paths from Gate 3 — they must still pass. A fix that resolves the symptom but breaks a neighbor is a failure, not a fix. **Exit condition:** Repro no longer reproduces, AND the blast-radius paths still pass. Both shown with evidence (command output, test result, observed behavior). --- ## The Evidence Ledger (write before the first edit) No code changes until this is filled in. It makes the reasoning visible and auditable. ``` INVESTIGATION LEDGER INTENT: what the code is supposed to do (Gate 0) — sourced, not assumed SYMPTOM: what actually happens — error/log quoted exact (Gate 1) REPRO: failing test / steps that demonstrate it (Gate 1) ROOT CAUSE: — the defective line + causal chain proof (Gate 2) BLAST RADIUS: every caller / consumer / test / config touching this code (Gate 3) CHANGE PLAN: the smallest diff that kills the cause (Gate 4) ROLLBACK: how to undo this change if it turns out wrong CONFIDENCE: NN% (see Confidence Gate) ``` Present the ledger inline in the conversation as structured text. Keep it tight — it is a pre-flight record, not an essay. ## Confidence Gate State a confidence percentage in the ledger. It governs whether you may edit: - **≥ 90%** and all six gates passed → proceed with the minimal change. - **70–89%** → not enough. Gather more evidence, tighten the proof, then re-score. No edit yet. - **< 70%** → STOP. Do not edit. Report the findings and the specific unknown blocking certainty, and ask the user how to proceed. Never round up. 89% is 0.89, not 0.9. Hidden uncertainty is how speculative fixes get shipped. --- ## Banned Anti-Patterns (any one = automatic fail, revert and restart) - **Shotgun debugging** — changing things to see if it helps. - **Fixing the test instead of the code** — editing or deleting an assertion to make it green when the code is what is wrong. - **Silencing the symptom** — empty catch, swallowed error, broad try/catch that hides instead of handles. - **Muting the compiler** — adding `any`, `// @ts-ignore`, `# type: ignore`, `@phpstan-ignore`, casting to dodge a real type error. - **Commenting out** a failing check, assertion, or validation to make a failure disappear. - **Drive-by edits** — touching unrelated code in the same change. - **Claiming fixed without re-running** the reproduction from Gate 1. - **Guessing the cause** and editing before Gate 2 is proven. ## Forbidden and Required Phrases **Never conclude with:** "I assume", "this typically", "this appears to be the issue", "that should fix it", "let me try changing X" (as a fix strategy), "tests pass" (without running them). **Always use:** "Line X shows ``, so the value is `` because ``", "Let me verify..." → read/run → then conclude, "Reproduced: ``", "Blast radius: ``". --- ## Handoff After a verified fix, this skill's job ends and the next begins: | Skill | Phase | |---|---| | **olakunlevpn-root-cause-skills** (this) | BEFORE the change — prove cause, scope impact, minimal fix | | olakunlevpn-meta-cognitive-verification | AFTER the change — 7-perspective audit, confirm nothing else broke | | olakunlevpn-git-skills | commit the verified, scoped change | Investigate before. Verify after. Commit clean. No blind fixes in between.