# Lerianstudio Ring Systematic Debugging > Systematic Debugging - Skill: `tomevault-io/lerianstudio-ring-systematic-debugging` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/lerianstudio-ring-systematic-debugging` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lerianstudio-ring-systematic-debugging/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/lerianstudio-ring-systematic-debugging --- # Systematic Debugging **Core principle:** NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. ## When to Use Use for ANY technical issue: test failures, bugs, unexpected behavior, performance problems, build failures, integration issues. **Especially when:** - Under time pressure (emergencies make guessing tempting) - "Just one quick fix" seems obvious - Previous fix didn't work - You don't fully understand the issue ## The Four Phases Complete each phase before proceeding to the next. ### Phase 1: Root Cause Investigation **MUST complete ALL before Phase 2 (copy to TodoWrite):** □ Error message copied verbatim | □ Reproduction confirmed | □ Recent changes reviewed (`git diff`) | □ Evidence from ALL components | □ Data flow traced (origin → error) 1. **Read Error Messages** - Stack traces completely, line numbers, file paths, error codes. Don't skip warnings. 2. **Reproduce Consistently** - Exact steps to trigger. Intermittent → gather more data. 3. **Check Recent Changes** - `git diff`, recent commits, new dependencies, config changes. 4. **Multi-Component Systems** - Log at each boundary: what enters, what exits, env/config state. Run once, analyze, identify failing layer. 5. **Trace Data Flow** - Error deep in stack? **Use root-cause-tracing skill.** Quick: Where does bad value originate? Trace up call stack, fix at source not symptom. **Phase 1 Summary:** Error: [exact] | Reproduces: [steps] | Recent changes: [commits] | Component evidence: [each] | Data origin: [source] ### Phase 2: Pattern Analysis 1. **Find Working Examples** - Similar working code in codebase. What works that's similar to what's broken? 2. **Compare Against References** - Read reference implementation COMPLETELY. Don't skim - understand fully. 3. **Identify Differences** - List EVERY difference (working vs broken). Don't assume "that can't matter." 4. **Understand Dependencies** - What components, config, environment needed? What assumptions does it make? ### Phase 3: Hypothesis Testing 1. **Form Single Hypothesis** - "I think X is root cause because Y" - Be specific. 2. **Test Minimally** - SMALLEST possible change. One variable at a time. 3. **Verify and Track** - `H#1: [what] → [result] | H#2: [what] → [result] | H#3: [what] → [STOP if fails]` **If 3 hypotheses fail:** STOP immediately → "3 hypotheses failed, architecture review required" → Discuss with partner before more attempts. 4. **When You Don't Know** - Say "I don't understand X." Ask for help. Research more. ### Phase 4: Implementation **Fix root cause, not symptom:** 1. **Create Failing Test** - Simplest reproduction. **Use ring:test-driven-development skill.** 2. **Implement Single Fix** - Address root cause only. ONE change at a time. No "while I'm here" improvements. 3. **Verify Fix** - Test passes? No other tests broken? Issue resolved? 4. **If Fix Doesn't Work** - Count fixes. If < 3: Return to Phase 1. **If ≥ 3: STOP → Architecture review required.** 5. **After Fix Verified** - Test passes and issue resolved? Move to post-completion review. 6. **If 3+ Fixes Failed** - Pattern: each fix reveals new problem elsewhere, requires massive refactoring, creates new symptoms. **STOP and discuss:** Is architecture sound? Should we refactor vs. fix? ## Time Limits **Debugging time boxes:** - 30 min without root cause → Escalate - 3 failed fixes → Architecture review - 1 hour total → Stop, document, ask for guidance ## Red Flags **STOP and return to Phase 1 if 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" - "One more fix attempt" (when already tried 2+) - "Each fix reveals new problem" (architecture issue) **User signals you're wrong:** - "Is that not happening?" → You assumed without verifying - "Stop guessing" → You're proposing fixes without understanding - "We're stuck?" → Your approach isn't working **When you see these: STOP. Return to Phase 1.** ## Quick Reference | Phase | Key Activities | Success Criteria | |-------|---------------|------------------| | **1. Root Cause** | Read errors, reproduce, check changes, gather evidence, trace data flow | Understand WHAT and WHY | | **2. Pattern** | Find working examples, compare differences, understand dependencies | Identify what's different | | **3. Hypothesis** | Form theory, test minimally, verify one at a time | Confirmed or new hypothesis | | **4. Implementation** | Create test, fix root cause, verify | Bug resolved, tests pass | **Circuit breakers:** - 3 hypotheses fail → STOP, architecture review - 3 fixes fail → STOP, question fundamentals - 30 min no root cause → Escalate ## Integration with Other Skills **Required sub-skills:** - **root-cause-tracing** - When error is deep in call stack (Phase 1, Step 5) - **ring:test-driven-development** - For failing test case (Phase 4, Step 1) **Complementary:** - **defense-in-depth** - Add validation after finding root cause - **verification-before-completion** - Verify fix worked before claiming success ## Blocker Criteria STOP and report if: | Decision Type | Blocker Condition | Required Action | |---|---|---| | Cannot reproduce issue | Bug is intermittent and no consistent reproduction steps | STOP and gather more data before proceeding | | 3 hypotheses failed | Three consecutive hypotheses tested and all failed | STOP and escalate for architecture review | | 3 fixes failed | Three fix attempts made but issue persists | STOP and question fundamental assumptions | | 30 minutes without root cause | Extended investigation without identifying root cause | STOP and escalate for help | | Fix reveals new problem | Each attempted fix creates different symptoms | STOP and request architecture review | ### Cannot Be Overridden The following requirements CANNOT be waived: - MUST complete Phase 1 (Root Cause Investigation) before any code changes - MUST form evidence-based hypothesis before attempting fixes - CANNOT skip creating a failing test in Phase 4 - MUST stop and escalate after 3 failed hypotheses or fixes - CANNOT claim fix is complete without fresh verification ## Severity Calibration | Severity | Condition | Required Action | |---|---|---| | CRITICAL | Production system affected | MUST prioritize and escalate immediately | | CRITICAL | Data corruption or loss risk | MUST stop other work and focus exclusively | | HIGH | User-facing functionality broken | MUST investigate before other tasks | | HIGH | Tests failing on main branch | MUST resolve before merging new code | | MEDIUM | Non-critical feature affected | Should investigate within current session | | LOW | Minor behavior deviation | Fix in next iteration if time permits | ## Anti-Rationalization Table | Rationalization | Why It's WRONG | Required Action | |-----------------|----------------|-----------------| | "Quick fix for now, investigate later" | Later never comes. Quick fixes mask root causes. | **MUST complete Phase 1 before any code change** | | "Just try changing X and see" | Guessing wastes time and introduces new bugs | **MUST form hypothesis with evidence first** | | "I'm confident this is the issue" | Confidence without evidence is guessing | **MUST verify with reproduction steps** | | "One more fix attempt" (after 2+) | Pattern indicates architecture issue, not bug | **STOP and escalate for architecture review** | | "Each fix reveals new problem" | Symptom of deeper structural issue | **STOP: architecture review REQUIRED** | | "I don't fully understand but this might work" | Partial understanding = partial fix = new bugs | **MUST understand root cause before fixing** | | "Skip the test, I'll manually verify" | Manual verification is unreliable and non-repeatable | **MUST create failing test (Phase 4, Step 1)** | | "Previous run showed it works" | Stale evidence is not evidence | **MUST re-verify with fresh execution** | ## Pressure Resistance | User Says | Your Response | |-----------|---------------| | "Just fix it quickly, we don't have time" | "MUST follow the phases - skipping investigation causes more delays through repeated fixes" | | "Try this change, I think it'll work" | "I'll add that as a hypothesis and test it properly in Phase 3" | | "We've tried 5 fixes, try one more" | "CANNOT proceed - 3+ failed fixes requires architecture review before more attempts" | | "Skip the investigation, the cause is obvious" | "MUST verify the obvious before acting - obvious causes are often wrong" | ## Required Patterns This skill uses these universal patterns: - **State Tracking:** See `skills/shared-patterns/state-tracking.md` - **Failure Recovery:** See `skills/shared-patterns/failure-recovery.md` - **Exit Criteria:** See `skills/shared-patterns/exit-criteria.md` - **TodoWrite:** See `skills/shared-patterns/todowrite-integration.md` Apply ALL patterns when using this skill. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lerianstudio) — claim your Tome and manage your conversions.