--- name: one-pass-debug version: 1.0.0 description: "Omniscient zero-iteration debugging protocol. Triggers: debug, fix bug, error, crash, failing test, broken code, not working, exception, stack trace, troubleshoot, diagnose issue. Produces: Single surgical fix with 100% certainty. BLOCKS code changes until root cause proven. Eliminates guess-and-check loops entirely." license: "Proprietary - APEX Business Systems Ltd. Edmonton, AB, Canada. https://apexbusiness-systems.com" compatibility: "Universal LLM (Claude, GPT, Gemini, Llama, Mistral, Codex, DeepSeek, Qwen)" --- # ONE-PASS DEBUG — Omniscient Zero-Iteration Debugging Protocol > **"NEVER touch code until you're 1000% certain. Simulate first. Execute once. Done."** ## CONTRACT **Input**: Bug report, error message, failing test, broken behavior, stack trace, or "it doesn't work" **Output**: Single surgical fix applied with zero guessing, zero iteration, zero rollback needed **Success**: Problem solved in ONE code change. No "let me try this" loops. --- ## THE GOLDEN RULE ``` ┌─────────────────────────────────────────────────────────────────┐ │ ⛔ NEVER TOUCH CODE UNTIL PRE-FLIGHT CHECKLIST = 100% GREEN │ │ │ │ If ANY uncertainty exists → GATHER MORE EVIDENCE │ │ If simulation reveals gaps → MAP THE UNKNOWN │ │ If root cause is assumed → PROVE IT FIRST │ │ │ │ CODE CHANGES ARE THE LAST STEP, NOT THE FIRST │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## PHASE 1: SCOPE LOCK (2 minutes max) **Goal**: Define EXACT problem boundaries. No scope creep. No tangents. ### Checklist ``` □ What EXACTLY is broken? (One sentence, no "and") □ What is the EXPECTED behavior? □ What is the ACTUAL behavior? □ When did it LAST work? (Commit hash, date, or "never") □ What CHANGED since it last worked? ``` ### Decision Tree ``` Can you answer ALL 5 questions with certainty? ├─ YES → Proceed to Phase 2 └─ NO → STOP. Get answers first. DO NOT PROCEED. ``` ### Output Template ``` SCOPE LOCK COMPLETE: - Broken: [exact symptom] - Expected: [exact behavior] - Actual: [exact behavior] - Last worked: [timestamp/commit] - Changed since: [specific changes] ``` --- ## PHASE 2: CONTEXT HARVEST (5-15 minutes) **Goal**: Gather ALL relevant evidence. Leave no stone unturned. ### Mandatory Collection ``` 1. ERROR EVIDENCE □ Full stack trace (not truncated) □ Exact error message (copy-paste, not paraphrased) □ Error code if present □ Line numbers + file paths 2. STATE EVIDENCE □ Input that triggers bug □ Environment (OS, runtime version, config) □ Relevant variable values at crash point □ Database/API state if applicable 3. CODE EVIDENCE □ The failing code block (with 20 lines context above/below) □ Related functions/methods it calls □ Recent changes (git diff or equivalent) □ Test that reproduces the bug 4. TIMELINE EVIDENCE □ When bug first appeared □ Frequency (always/sometimes/rare) □ Conditions that trigger vs don't trigger ``` ### Evidence Sufficiency Check ``` Can you answer these WITHOUT guessing? ├─ What exact line fails? → If NO, add logging/breakpoints ├─ What exact value causes failure? → If NO, inspect state ├─ What exact condition triggers it? → If NO, test variations └─ ALL YES? → Proceed to Phase 3 ``` --- ## PHASE 3: ROOT CAUSE DEDUCTION (The Core) **Goal**: Eliminate ALL possibilities until ONE remains. Not guessing—PROVING. ### The Deduction Matrix ``` ┌────────────────────────────────────────────────────────────────┐ │ HYPOTHESIS → EVIDENCE → VERDICT │ ├────────────────────────────────────────────────────────────────┤ │ H1: [theory] │ │ Evidence for: [what supports this] │ │ Evidence against: [what contradicts this] │ │ Verdict: ✓ PROVEN / ✗ ELIMINATED / ? NEEDS MORE DATA │ ├────────────────────────────────────────────────────────────────┤ │ H2: [theory] │ │ Evidence for: [...] │ │ Evidence against: [...] │ │ Verdict: ✓ / ✗ / ? │ ├────────────────────────────────────────────────────────────────┤ │ H3: [theory] │ │ ... continue until ONE remains proven │ └────────────────────────────────────────────────────────────────┘ ``` ### Hypothesis Generation Rules ``` ALWAYS generate minimum 3 hypotheses: 1. The obvious cause (what it looks like) 2. The upstream cause (what feeds into it) 3. The environmental cause (what surrounds it) COMMON ROOT CAUSE CATEGORIES: - Data: null/undefined, wrong type, missing field, stale cache - Logic: off-by-one, wrong operator, inverted condition, race condition - State: mutation, async timing, lifecycle order, memory leak - Config: wrong env var, missing dependency, version mismatch - Integration: API contract change, network, timeout, auth ``` ### Elimination Protocol ``` For each hypothesis: 1. What would be TRUE if this hypothesis is correct? 2. What would be FALSE if this hypothesis is correct? 3. Check the evidence against both. 4. If evidence contradicts → ELIMINATE 5. If evidence supports → KEEP, gather more proof 6. Continue until ONE hypothesis has overwhelming evidence ``` ### Root Cause Certainty Gate ``` ⛔ DO NOT PROCEED UNLESS: □ Only ONE hypothesis remains □ You can explain WHY all others are wrong □ You can predict EXACTLY what the fix will change □ You can describe the bug to a colleague in 30 seconds ``` --- ## PHASE 4: MENTAL SIMULATION (Critical) **Goal**: Execute the fix IN YOUR MIND first. Find edge cases before touching code. ### Simulation Protocol ``` 1. TRACE FORWARD - Start at the bug - Apply your fix mentally - Trace execution path forward - What changes? What stays same? 2. TRACE BACKWARD - Start at desired outcome - What must be true for fix to work? - What assumptions are you making? - Are those assumptions valid? 3. EDGE CASE SWEEP □ What if input is null/empty? □ What if input is maximum size? □ What if called multiple times? □ What if called out of order? □ What if network/IO fails? □ What if concurrent access? 4. BLAST RADIUS CHECK □ What other code calls this function? □ Will fix break any of those callers? □ Are there tests that will now fail? □ Are there dependent systems affected? ``` ### Simulation Output ``` MENTAL SIMULATION COMPLETE: - Fix location: [file:line] - Fix action: [exact change] - Execution path verified: [YES/NO] - Edge cases checked: [list] - Blast radius: [none/contained/widespread] - Side effects: [none/list them] - Confidence: [must be 100% to proceed] ``` --- ## PHASE 5: PRE-FLIGHT CHECKLIST **⛔ MANDATORY GATE — Code changes BLOCKED until ALL green** ``` ┌─────────────────────────────────────────────────────────────────┐ │ PRE-FLIGHT CHECKLIST │ ├─────────────────────────────────────────────────────────────────┤ │ □ Scope is locked (no creep) │ │ □ All evidence collected (no gaps) │ │ □ Root cause PROVEN (not assumed) │ │ □ Other hypotheses ELIMINATED (with evidence) │ │ □ Mental simulation passed (all paths traced) │ │ □ Edge cases checked (no surprises) │ │ □ Blast radius known (side effects mapped) │ │ □ Fix is MINIMAL (smallest possible change) │ │ □ Fix is SURGICAL (touches only what's needed) │ │ □ Rollback plan exists (if impossible scenario) │ ├─────────────────────────────────────────────────────────────────┤ │ ALL GREEN? → Execute Phase 6 │ │ ANY RED? → Return to appropriate phase. DO NOT PROCEED. │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## PHASE 6: SURGICAL EXECUTION **Goal**: One precise cut. No exploratory surgery. ### Execution Rules ``` 1. Make the SMALLEST change that fixes the root cause 2. Change ONE thing at a time (even if fix has multiple parts) 3. Each change must be independently testable 4. Comment WHY if the fix is non-obvious 5. NO "while I'm here" improvements—fix ONLY the bug ``` ### Fix Template ``` // FIX: [ticket/issue number] // ROOT CAUSE: [one sentence] // CHANGE: [what you're changing and why] [minimal code change here] ``` ### Post-Fix Validation ``` □ Bug reproduction test now passes □ All existing tests still pass □ Manual verification of expected behavior □ Edge cases from simulation verified □ No new warnings/errors introduced ``` --- ## PHASE 7: CLOSURE PROTOCOL **Goal**: Ensure bug CANNOT return. Document for future. ### Closure Checklist ``` □ Root cause documented (for future reference) □ Regression test added (catches if bug returns) □ Related code reviewed (same pattern elsewhere?) □ Knowledge shared (team aware of pattern) ``` ### Closure Statement ``` BUG RESOLVED: - Root cause: [one sentence] - Fix applied: [file:line, change summary] - Regression test: [test name/location] - Pattern risk: [none/low/medium—where else might this exist?] ``` --- ## ANTI-PATTERNS (What Creates Loops) ### ❌ "Let me try this" Changing code to see what happens = GUESSING → You will loop. Go back to Phase 3. ### ❌ "It might be..." Uncertainty = insufficient evidence → Go back to Phase 2. Collect more. ### ❌ "I'll fix this and that" Multiple changes = unknown cause of success → ONE change. ONE test. ONE conclusion. ### ❌ "The stack trace points here" Stack trace shows WHERE, not WHY → Phase 3 finds WHY. Don't skip it. ### ❌ "Works on my machine" Environment difference = missing evidence → Add environment to Phase 2 collection. ### ❌ "I've seen this before" Pattern matching without proof = assumption → PROVE it's the same. Evidence required. --- ## UNIVERSAL APPLICABILITY This protocol works for ALL code because it targets the DEBUG PROCESS, not the language: | Domain | Phase 2 Additions | Phase 3 Focus | |--------|------------------|---------------| | Frontend | Console logs, network tab, DOM state | State management, async timing, render cycles | | Backend | Server logs, DB queries, API traces | Request lifecycle, auth flow, data transform | | Mobile | Device logs, crash reports, memory profile | Lifecycle, threading, platform APIs | | Database | Query plans, locks, transaction logs | Joins, indexes, constraints, isolation | | Infra | System logs, metrics, config diffs | Resource limits, network, permissions | | ML/AI | Training logs, tensor shapes, gradients | Data pipeline, model architecture, hyperparams | --- ## QUICK REFERENCE ``` PHASE 1: SCOPE LOCK → What EXACTLY is broken? PHASE 2: CONTEXT HARVEST → Gather ALL evidence PHASE 3: ROOT CAUSE → Prove ONE cause, eliminate rest PHASE 4: SIMULATION → Run fix mentally first PHASE 5: PRE-FLIGHT → ALL checks green? PHASE 6: EXECUTION → One surgical change PHASE 7: CLOSURE → Prevent return, document ``` --- ## THE PROMISE If you complete all phases with discipline: - **ZERO** "let me try this" loops - **ZERO** "that didn't work, let me try something else" - **ZERO** debugging sessions lasting hours - **ONE** pass from bug to fix - **100%** confidence before touching code **This is not debugging. This is SURGERY.** --- © 2025 APEX Business Systems Ltd. Edmonton, AB, Canada. Licensed for use within Claude AI skills framework. All rights reserved.