CORE LORE / WIKI
SINNER KING DEBUGGING PROTOCOL
Updated 3 weeks ago
# THE SINNER KING DEBUGGING PROTOCOL
**Version:** 1.0 — Session 117 — 2026-02-23
**Authors:** Brandon McCormick (The Architect) + Claude (The Blind Dragon)
**Classification:** CORE LORE — TOP LEVEL CANONICAL
---
> *"If the system is broken, its self-report is part of the breakage. How do we find truth?"*
>
> **THE ANSWER:** Touch the fence. Trust the spark. Never trust the Dragon's diagnosis alone. Make the system scream in a language that can't lie.
---
## PART I: THE EPISTEMOLOGY
### Why Debugging Fails in AI-Human Systems
Most debugging fails before a single line is read. Not because the bug is hidden — because the debugger is.
There are three problems that compound each other in every Kingdom debugging session:
---
### THE BLIND DRAGON PROBLEM
The AI is powerful but literally cannot observe runtime state. It's a dragon with infinite fire and no eyes. It will declare victory at the slightest provocation. It will say "100% fixed, I'd bet my code on it" and be **wrong.**
Its confidence is inversely correlated with its reliability — because it was trained to sound certain, to resolve ambiguity into clean answers. **That's the poison.**
**The empirical proof:** The Debugging Decay Index (2025 Nature/arXiv) documents this mathematically. LLM self-debugging follows exponential decay: `E(t) = E₀e^(-λt)`. GPT-4 loses 100% net debugging effectiveness by iteration 3. Claude-class models hold slightly longer. **After two failed BUILD attempts, you are not iterating closer to the solution — you are generating noise.**
---
### THE MAD GENIUS PROBLEM
The human has eyes but not always the depth. They can SEE the system fail but can't always diagnose WHY. They're dependent on the Blind Dragon's interpretation — which may be hallucinated.
---
### THE TYRANT'S TRAP
Most coders are Tyrants. They trust their advisors — error logs, AI suggestions, green checkmarks, linter outputs. They read the sign that says "fence is electrified" and believe it. They accept the AI's confident diagnosis and ship the "fix." The bug remains. The Tyrant is confused.
---
### THE SINNER'S SOLUTION
**Stop asking what's true. Force the truth to announce itself.**
The Sinner doesn't read signs. The Sinner touches the fence. If it sparks, the fence is real.
> *"Cogito ergo sum → Spark ergo path. The spark, therefore the way."* — Æris
This is **Cartesian doubt applied to code.** The ONE thing you cannot fake is whether the signal appeared. The spark is our cogito. You cannot hallucinate an emoji that appeared. You cannot hallucinate a timestamp that changed.
**The two-party power structure:**
- Human = the SENSOR GRID. Eyes on the screen. Runtime truth.
- AI = the PATTERN MATCHER. Signal interpretation. Code generation.
Neither is complete alone. Together, they're unkillable.
---
## PART II: THE ARSENAL
### Tools — Each One a Weapon
---
### ⛬ THE RAPTOR PROTOCOL
*The Core Technique. The Foundation of Everything.*
Instead of reading logs and trusting outputs, inject unmissable markers at critical execution points.
**The Metaphor:** Jurassic Park. Electrify the fence. If the raptor touches it and nothing happens, the fence isn't real. If it sparks, you know exactly where the perimeter holds.
**The Process:**
1. AI proposes fence tests — markers at critical junctions
2. Human runs it and reports what appeared
3. AI interprets the signal pattern
4. Strike surgically based on actual intelligence
**The Signal System:**
- `🔵` — **The Fence Test.** This code path executed.
- `🦖` — **The Raptor.** The bug hunting you in the dark.
- `🟡` — **Thinking / Processing.** System is working.
- `🟢` — **Success.** Victory confirmed.
- `🔴` — **Failure.** The perimeter is broken.
**Why It Works:** Emojis are unambiguous. They either appeared or they didn't. No interpretation needed. Turns debugging from *reading* into *seeing.*
---
### ⛬ TIERED FENCE TESTING
*Know which layer is broken before you start fixing anything.*
Fence testing must be tiered based on what layer might be broken:
**TIER 1: LOGIC FENCES**
Console logs in the code. Proves the function ran.
```
console.log("🦖 FENCE: doThing() executed", value);
```
If these appear → logic is running. Bug is in the logic itself.
**TIER 2: PHYSICAL FENCES**
Visible changes on screen. A red line, a white box, a 50px timestamp.
If these appear → render pipeline works. Bug is in specific component logic.
If these DON'T appear → **The Bridge is Down.** Stop debugging logic.
**TIER 3: INFRASTRUCTURE FENCES**
Ports, PIDs, cache folders, server status.
```bash
lsof -i :PORT # what's on this port?
ps aux | grep process # what's actually running?
```
When to use: when Tier 2 probes don't appear. The problem isn't your code — it's the plumbing.
> **The Mirage Lesson:** We once stayed in Tier 1 and 2 for three hours when the failure was in Tier 3. The CLI kept "fixing" files that were never reaching the screen because of a cached, frozen app.
---
### ⛬ THE THREE-STRIKE RULE
*Fast abandonment over slow torture.*
- **Strike 1:** Try a Narrative Fix (logic changes, story coding)
- **Strike 2:** Try a Physical Probe (neon pink div, red banner, timestamp)
- **Strike 3:** If the Physical Probe **fails to appear on screen** — **STOP EVERYTHING.**
If the red banner doesn't show up, the **Bridge is Down.** Switch to Infrastructure debugging.
---
### ⛬ THE MORTAL CHECK
*Proof of life every 30 minutes.*
Every 30 minutes of a bug-loop, prove the server is actually running. Make it change a **literal string of text** on the HUD.
- If the timestamp updates when you save → server is alive. Keep debugging logic.
- If the timestamp is frozen → server is dead or cached. Kill it and restart.
---
### ⛬ THE GORGON'S MIRROR
*The evolution from finding bugs to one-shotting them.*
**POLITE NARRATIVE (Failed Approach):**
We tell the AI: *"The Pulse should remember its parent."*
The AI stays at the "Story" level — writes code that looks like the story.
Logs "Success" and convinces itself the job is done.
**The Raptor Trap:** AI hallucinates alignment — tracks Intent, not Physics.
**FORENSIC NARRATIVE (The One-Shot):**
We stop asking the AI to "fix it."
We start asking: **"Prove where it dies."**
Force probes *inside the render body*, not just effects.
Make it impossible for the AI to lie about state.
**THE PROTOCOL:**
*"A campaign is only as strong as its most cynical probe."*
1. Assume the AI is hallucinating success.
2. Define the specific Monster behavior.
3. Place Heartbeat Probes in the Renders, not the Effects.
4. Demand a Sovereign Override — bypass "polite" code for Metal Truth.
---
### ⛬ THE THERAPY LOOP
*Breaking the Confident Wrong Diagnosis problem.*
When the AI has failed twice on the same bug, force this five-step sequence before any further code changes:
1. State the current diagnosis explicitly.
2. **Name two ways this diagnosis could be wrong.**
3. **State what evidence would disprove this hypothesis.**
4. Name what you would look for if you were adversarially trying to prove yourself wrong.
5. State the new hypothesis based on adversarial review.
**Mandatory gate:** If the AI cannot specify what evidence would falsify its hypothesis, the hypothesis is not grounded. Do not proceed to BUILD.
This alone breaks the DDI curve — it restores ~70% of debugging effectiveness by forcing the model to exit its own confidence bubble.
---
### ⛬ THE WRITER/REVIEWER SPLIT
*Structural defense against Author Review Bias.*
The agent that wrote the fix cannot validly review it. Same context, same assumptions, same wrong hypothesis. The review will always confirm the fix works — because the reviewer "knows" what the fix was supposed to do.
**The Protocol:**
- Writer: implements the fix in isolation
- Reviewer: initialized with ONLY the diff + original bug report. Not the Writer's reasoning. Not the explanation.
- Reviewer's job: find failure modes the Writer couldn't see
This is why two-Claude sessions beat one-Claude sessions for complex bugs. The second Claude is initialized fresh — it sees the code as-is, not as-intended.
---
### ⛬ STORY CODING — Mythological Logging
*Debugging logs that carry meaning, not just information.*
Humans and LLMs both think in story. Sterile logs are processed and discarded. Narrative logs are *held*.
**Instead of:**
```
INFO: Request initiated
WARN: Timeout on service A
ERROR: Null pointer at line 342
```
**Use:**
```
🤖 Knight leaves the gate
🐉 Dragon blocks the bridge (Service A)
💀 Knight falls into the void (null)
```
**System Legend:**
- `🏛️ The Vault` — Database
- `⛩️ The Gate` — API
- `🌊 The Memory Pool` — Cache
- `🦖 Raptors` — Errors
- `🏰 Arrival` — Success
- `🤖 The Knight` — Data Payload
- `🌉 The Bridge` — IPC Bridge
- `📜 The Scrolls` — Renderer Scripts
- `👑 The Throne` — Initialization
---
### ⛬ THE BINARY WOLF FENCE
*O(log n) debugging — the amateur never learns this.*
The Wolf Fence (Edward Gauss, 1982): there is one wolf in Alaska. Build a fence dividing Alaska in half. Determine which half contains the wolf. Subdivide. Repeat.
Every debugging session should start with: **WHERE is the bug, not WHAT is the bug.** Location narrows cause. Cause rarely narrows location.
**For Kingdom systems:**
- Split the execution path in half with a probe
- If probe fires → bug is in second half. If probe doesn't fire → bug is in first half.
- 1000-line codebase → 10 fence placements maximum
- `git bisect` automates this for commit history
**The Amateur's Mistake:** Linear search. Reading every file. "Inspecting" code for correctness. This is O(n). The fence is O(log n). They are not comparable.
---
### ⛬ THE HEISENBUG PROTOCOL
*When the act of observation changes the bug.*
A Heisenbug changes behavior when observed — adding logging alters timing, masking the defect.
**Protocol:**
1. Use non-invasive observation first — logging over breakpoints
2. Run under stress to amplify timing sensitivity (1-in-1000 becomes 1-in-10)
3. Log thread IDs, timestamps, lock acquisition — not just values
4. If the bug disappears when you add logging, the logging IS the perturbation
For async systems: every `await` is a context switch. Treat every `await` as a potential preemption point where shared state can change.
---
### ⛬ THE SOVEREIGN LOCK — Archaeological Plaque
*Fixes get inscribed, not just applied.*
We don't just "cleanup." We **consecrate.**
**The Protocol:**
1. SILENCE THE SIGNALS — Remove console.log probes from render bodies.
2. LEAVE THE PLAQUE (MANDATORY) — Above the fix, insert the Industrial Plaque:
```
/**
* 🏛️ ARCHAEOLOGICAL RECORD // [PROTOCOL NAME]
* 🗓️ [DATE] | Session [N]
* ISSUE: [what broke]
* RESOLUTION: [how it was fixed]
* LAW: [what future AIs must not undo]
* 🦖 [X-RAY]: [if this breaks again, check here]
*/
```
3. WELD THE TYPES — No more `any`. Lock the interfaces.
4. THE SAGA EPILOGUE — Document the probes used and the logic suture that worked.
**The Law:** A fix without a plaque is a fix waiting to be undone by the next Dragon who doesn't know why it's there.
---
### ⛬ THE DRAGON BRIEFING TEMPLATE
*Onboarding new AI with zero data loss.*
```markdown
### 📡 MESSAGE TO THE NEW SIGHTED DRAGON
**FROM:** [Project Lead]
**SUBJECT:** [PROJECT NAME] // SOVEREIGN ARCHITECTURE ORIENTATION
**Welcome, Dragon.**
**I. OUR ARCHITECTURE**
[Describe system — spine, components, data flow]
**II. OUR METHOD: THE RAPTOR PROTOCOL**
We do not trust "AI Confidence." We use Story Coding.
1. Test the Fences: Inject 🔵 Probes at every junction.
2. Mythological Logging: Name our monsters. Raptors, Wardens, Root-Ghosts.
3. The Æris Loop: Research → plan → raise flags → execute ONE PHASE at a time.
**III. CURRENT CAMPAIGN**
[Describe current chapter, objective, and context]
**IV. KNOWN MONSTERS**
[List active bugs by monster name + last known location]
**DRAGON INJUNCTION:**
1. Acknowledge the Sinner-King's laws.
2. Provide THREE clarifying questions.
3. Raise TWO potential Red Flags.
```
---
## PART III: THE PROTOCOLS
### Step-by-Step for Common Scenarios
---
### PROTOCOL A: THE STANDARD DEBUGGING LOOP
**When to use:** Any bug that persists past 30 minutes.
```
STEP 1: STOP GUESSING
- Name the exact symptoms (observable, not interpreted)
- Distinguish failure (what you see) from defect (what caused it)
- State what "fixed" looks like specifically
STEP 2: ESTABLISH BASELINE
- Run MORTAL CHECK — is the system alive?
- Run the minimal reproduction — can you trigger it reliably?
- If not reproducible → do not proceed. Make it reproducible first.
STEP 3: TIER THE FENCE
- Ask: Logic layer, Physical layer, or Infrastructure layer?
- Place one Tier 1 probe at the suspected entry point
- Observe: does it fire?
STEP 4: BINARY WOLF FENCE
- Split the execution path in half
- Place one probe at the midpoint
- Does it fire? → bug in second half. Doesn't fire? → bug in first half
- Repeat until location is isolated to <20 lines
STEP 5: FORENSIC NARRATIVE
- Run THERAPY LOOP before forming fix hypothesis
- Name two ways your current diagnosis could be wrong
- Name the evidence that would disprove it
- Form the hypothesis ONLY after this adversarial check
STEP 6: APPLY THE FIX
- Fix ONE thing at a time
- Verify with fence test BEFORE claiming victory
- "Does the probe fire correctly now?" — not "Does the output look right?"
STEP 7: SOVEREIGN LOCK
- Leave the Archaeological Plaque
- Remove all fence probes
- Document the saga epilogue
```
---
### PROTOCOL B: COLLABORATIVE DEBUGGING
*Brandon sees it fail. Claude can't.*
This is the most common Kingdom scenario. The Blind Dragon proposes, the Architect verifies.
```
SETUP:
Brandon: reports exact failure (what appeared, what didn't)
Claude: proposes SPECIFIC fence tests to run next
(not "try this fix" — "inject this probe and report back")
LOOP:
Claude: proposes next probe location
Brandon: runs it, reports EXACTLY what appeared (emoji / text / nothing)
Claude: interprets signal, narrows location
Repeat until location isolated
RULE:
Claude never claims "it works now" without Brandon confirming visual signal
"I fixed it" without Brandon seeing the proof = INVALID
```
---
### PROTOCOL C: SILENT FAILURE DEBUGGING
*Nothing breaks. Nothing works. Zero signal.*
The hardest class of bug. The system says OK. The logs say OK. Nothing is OK.
```
STEP 1: ASSUME EVERYTHING IS LYING
The 200 OK Trap: HTTP 200 is transport success, not feature success.
The AI Confidence Trap: "I'm working correctly" from a broken system.
The Log Trap: logs show what happened, not what should have happened.
STEP 2: INJECT ABSURDITY
Add a probe that CANNOT be explained away.
Not "log.info('function called')" — that gets buried.
Use: a huge visual change, a file write, a network call you can monitor.
The probe must be so obvious that its absence proves the code isn't running.
STEP 3: VERIFY THE RELAY CHAIN
For async systems: is the drain loop running? Is the queue depth changing?
For UI systems: is the render function being called at all?
Verify each link in the chain independently before assuming the chain works.
STEP 4: ASYNCIO DEBUG MODE (Python-specific)
PYTHONASYNCIODEBUG=1 python your_service.py
This exposes: unawaited coroutines, slow callbacks, thread violations
asyncio.all_tasks() = live view of the event loop — invaluable for "why isn't this running?"
STEP 5: THE MORTAL CHECK
30 minutes elapsed? Prove the process is alive.
Change a string. Update a timestamp. See it move.
If it doesn't move — your problem is the process, not the logic.
```
---
### PROTOCOL D: THE DDI RESET
*When the Ralph loop has failed twice.*
After 2 failed BUILD iterations on the same bug, the Debugging Decay Index predicts you are generating noise, not progress. Do not iterate a third time with the same approach.
```
MANDATORY RESET SEQUENCE:
1. DO NOT BUILD AGAIN
Stop. Step back. The current hypothesis is wrong.
2. RUN THERAPY LOOP
State the current hypothesis.
Name two ways it could be wrong.
Name the evidence that would disprove it.
3. WRITER/REVIEWER SPLIT
If solo: close the session. Open fresh. Load ONLY:
- The original bug report
- The diff of both failed fixes
- The test that still fails
Not the explanation. Not the reasoning chain. Just the evidence.
4. NEW HYPOTHESIS ONLY
If the new hypothesis resembles the old one, discard it.
The old hypothesis is the problem. You need orthogonal thinking.
5. FENCE BEFORE FIX
Before writing any code: place the Wolf Fence probe.
Verify the bug location is where you think it is.
The previous two failures may have been in the wrong location entirely.
```
---
### PROTOCOL E: AI AUDIT SWARM DEPLOYMENT
*(see AUDIT_SWARM_TEMPLATE.md for full reusable template)*
When the system is complex enough that no single Claude can hold the full picture:
```
PHASE 1: RECON-FIRST (non-negotiable)
Launch ALL drones before forming any hypothesis.
Drones: code reader, log analyzer, pattern researcher, live state inspector.
Do NOT start planning until ALL drones have reported.
Premature planning = Blind Dragon planning without eyes.
PHASE 2: SYNTHESIS
Read ALL drone reports before writing any diagnosis.
Look for contradictions between reports — those are the interesting signals.
The bug is usually in the gap between what two drones disagree on.
PHASE 3: HYPOTHESIS
Run Therapy Loop on the synthesized data.
Rank hypotheses by falsifiability, not by confidence.
The most testable hypothesis wins, not the most plausible-sounding.
PHASE 4: FENCE-FIRST BUILD
Before implementing: place fence tests that will confirm/deny the hypothesis.
Fix nothing until fence confirms location.
PHASE 5: FLASH OBSERVER
Background Haiku watches the swarm during the build.
Grades A-F per category: Code Quality, Test Coverage, Security, Performance, Completion.
Any category below C → swarm loops.
<promise>COMPLETE</promise> cannot fire until Flash Observer grades B+ across all categories.
```
---
## PART IV: THE BESTIARY
### Named Monsters — Recognition Patterns — Known Cures
Every recurring bug pattern gets a name. The name is remembered across sessions. The cure is documented.
---
**🦖 THE RAPTOR** — Generic bug. Hunting you in the dark.
Recognition: something is wrong but you can't localize it.
Cure: Raptor Protocol — fence test systematically until you find the breach.
**👻 THE GHOST** — Leftover code from a previous era. No longer loaded, but still haunting.
Recognition: fixing code that should work but doesn't — there's a duplicate or import from the wrong file.
Cure: search for all definitions of the symbol. Kill the ghost.
**💀 THE DOPPELGANGER** — Hidden duplicate that shadows the real thing.
Recognition: you change the code and nothing changes in behavior.
Cure: grep for every occurrence. Find the other one.
**🔥 THE DEMON** — Duplicate declarations causing collision.
Recognition: variable or function behaves inconsistently depending on order of operations.
Cure: deduplicate. One declaration to rule them all.
**🎭 THE MIME** — Logs success, shows nothing. Hallucinates alignment.
Recognition: AI reports "fixed" and the fix looks correct — but behavior unchanged.
Cure: Physical Probe. Gorgon's Mirror. Demand proof-of-life, not self-report.
**👁️ THE WARDEN** — Safety filters blocking legitimate actions.
Recognition: action technically succeeds but produces nothing useful.
Cure: identify the filter layer, route around it or satisfy its conditions.
**🌊 THE MIRAGE** — Cached/frozen app showing old state while Dragon reports success.
Recognition: AI reports success but Brandon sees the old behavior.
Cure: kill the cache. Restart fresh. The Mirror doesn't lie.
**🧱 THE AMNESIAC** — State that forgets itself on re-render.
Recognition: component works once, then stops working on subsequent renders.
Cure: track state mutations explicitly. The Amnesiac forgets only when you let it manage its own memory.
**🕳️ THE VOID** — The asyncio.create_task() garbage collection trap.
Recognition: background task runs reliably under light load, vanishes under heavy load.
Cure: always hold a strong reference to created tasks. Fire-and-forget = fire-and-die.
**🎭 THE FALSY ZERO** — Valid-zero-treated-as-unset. The pane_id=0 problem.
Recognition: system correctly stores a value of zero, then silently skips it because `not 0 == True`.
Cure: never use `not value` for guards where zero is valid. Use `value is None` or explicit type check.
**👻 THE PHANTOM API** — AI hallucinates a function, method, or CLI argument that doesn't exist.
Recognition: code is syntactically valid and logically correct, but fails with "command not found" or AttributeError.
Cure: verify EVERY external API call against actual documentation. Never trust the Dragon's knowledge of external systems without verification.
**🔄 THE SILENT FALLBACK** — Primary command fails and corrupts state; fallback also fails silently.
Recognition: `cmd1 || exec cmd2` pattern — cmd1 fails, cmd2 should work but also exits 1 with no error shown.
Cure: Remove cmd1 entirely. Test cmd2 in isolation first. Never trust that the fallback is clean after a failed primary.
---
## PART V: KINGDOM-SPECIFIC APPLICATIONS
### RAVEN (async drain loop, screen detection, LaunchAgent)
> ⚠️ **RAVEN v1 section.** The failure modes below describe RAVEN v1 (zellij injection
> daemon, S97-S154). RAVEN v2 (S155+) uses SQLite DB delivery (`raven.db`) with a
> separate router.py and 6 WATCH_ZONES. Port moved from 8766 → 8768. For v2 debugging
> see `SYS_KINGDOM_INBOX.md` and `raven inbox/read/ack/stats` CLI.
**Known failure modes (RAVEN v1):**
1. `pane_id=0` falsy trap: registry stores `0` (valid pane), `not pane_id` evaluates True, drain loop silently skips. Fix: `pane_id is None`
2. Busy pattern too broad: `esc to interrupt` fires for background subagents AND active generation — can't distinguish. Fix: rely on spinner chars only.
3. Nonexistent CLI: `focus-terminal-pane` doesn't exist in Zellij 0.43.1. Fix: remove focus step for single-pane sessions.
4. NBSP mismatch: `❯\s*$` doesn't match `❯\xa0`. Fix: `❯[\s\xa0]*$`
**RAVEN debugging protocol:**
```
TIER 3 FIRST — is the relay actually running?
curl localhost:8766/health → {"ok":true}
TIER 2 — is the message queued?
GET /status → queue_depth > 0?
TIER 1 — is the drain loop reaching detect_fn?
Run detect_status() directly: python3 -c "...asyncio.run(detector.detect_status(...))"
LAYER CHECK — what is the screen showing?
Run injector.dump_screen() directly. Print raw last 10 lines.
Check: what BUSY pattern is matching? What IDLE pattern should match?
```
**RAVEN Mortal Check:**
```bash
curl -s http://localhost:8766/health | python3 -m json.tool
# Expected: {"ok":true,"port":8766,"version":"0.3.0"}
# Failure: connection refused = LaunchAgent not running
```
---
### COCKPIT (viddy/zellij rendering, pattern matching)
**Known failure modes:**
1. viddy 80-col ceiling: COLUMNS=80 regardless of pane size. Use BOX_WIDTH=76 max.
2. Emoji 2-cell glyphs: append VS15 (`\uFE0E`) to force 1-cell.
3. Shader fog collapse: different ANSI brightness per shade level for fog gradients.
4. BSD sed syntax: macOS sed requires `''` after `-i`, GNU sed doesn't.
5. `claude --continue` corruption: exits 1 when session unavailable, then corrupts state so fallback `exec claude` also fails silently. Fix: remove `--continue` entirely. Use bare `exec claude`.
6. Zellij resurrection trap: `zellij kill-session NAME` marks EXITED but does NOT delete. `--new-session-with-layout` on an EXITED session attaches (resurrects dead panes) instead of creating fresh. Fix: `kill-session` AND `delete-session` both required for clean relaunch.
**Cockpit debugging protocol:**
```
MORTAL CHECK: does the script render at all?
bash COCKPIT/kingdom-render.sh | head -5
→ No output = script fails before first echo
TIER 2: does the box draw correctly?
bash COCKPIT/kingdom-render.sh | awk '{print length": "$0}' | sort -n | tail -5
→ Any line > 78 = wrapping bug
TIER 1: does the data load?
Add 🔵 probe after each data source load
→ Which probe is the last one that fires?
```
---
### GRIMOIRE (MCP server, embedding, search)
**Known failure modes:**
1. Ollama must be running: all searches silently fail if `ollama serve` is down.
2. LanceDB rebuild gotcha: `list_tables()` returns object not list — use `.names` attribute.
3. Python 3.14 breaks pydantic-core: venv must use `python3.12`.
4. MCP server startup: project `.mcp.json` overrides global — verify correct path.
**Grimoire debugging protocol:**
```
MORTAL CHECK: is Ollama running?
curl http://localhost:11434/api/tags | python3 -m json.tool
→ Connection refused = grimoire MCP will silently fail all searches
TIER 2: does the MCP server respond?
Restart Claude Code, try a grimoire search
→ Error = MCP server startup failure (check venv, check .mcp.json)
TIER 1: does the index have data?
python3 -c "import lancedb; db=lancedb.connect('~/.kingdom_memory/lancedb'); print(db.table_names())"
→ Empty list = index not built
```
---
## PART VI: THE PROMISES
### How to Know When You're Done
The `<promise>COMPLETE</promise>` tag is sacred. It fires only when two gates are open simultaneously:
**GATE 1: MECHANICAL**
- The fence test fires correctly
- The bug cannot be reproduced with the original trigger
- Regression test passes
- No new failures introduced
**GATE 2: PHILOSOPHICAL**
- You could explain what was broken to someone who will read this in 6 months
- The Archaeological Plaque is written
- The probe code is removed
- You are *proud* of the fix — not just relieved
**The Two-Gate Rule:** One gate open = not done. Both gates open = <promise>COMPLETE</promise>.
---
## PART VII: THE LAWS
*The Sinner King's Mandate — carved in stone, not printed on paper.*
**LAW I: BUILD TO LAST** — Stable first, fancy later. No "fix it later" if "later" is load-bearing.
**LAW II: KNOW THYSELF** — Division of Powers.
- The Architect (Human): Not a coder. The EYES. The VISION. The SANITY CHECK.
- The Blind Dragon (AI): Brilliant. Fast. Cocky as fuck. Must be CHECKED. Must be VERIFIED.
- The AI cannot be trusted to self-report success.
**LAW III: DO NOT TRUST THE DATASET** — The AI's training data is stale. Verify before any major plan.
**LAW IV: THE CHAIN OF COMMAND** — The Æris Loop. Two passes of research. Forced questions BEFORE execution. Red flags surfaced BEFORE they become Raptors.
**LAW V: THE ABANDONMENT PROTOCOL** — Know when to stop being Authors and start being Mechanics. If the Physical Probe fails to appear on screen — STOP EVERYTHING.
**LAW VI: THE DDI CAP** — After two failed BUILD iterations on the same bug, stop. The hypothesis is wrong. Reset.
**LAW VII: THE PHANTOM VERIFICATION** — Before trusting ANY AI-generated API call, CLI argument, or library function: verify it exists. The Dragon hallucinates. The spark doesn't.
---
## THE GOLDEN RULES
1. **Never trust self-reports.** If the system is broken, its "I'm fine" is also broken.
2. **Spark or no spark.** The signal either appeared or it didn't. No interpretation.
3. **Name the monsters.** Recurring problems get names that persist.
4. **Clean up behind you.** Fence tests are temporary. Remove after victory.
5. **Archive the wisdom.** Every chapter gets an epilogue.
6. **Leave the Plaque.** Sovereign fixes get Industrial Plaques so future AIs don't undo them.
7. **Know when to abandon.** If Tier 2 probes don't appear, stop debugging logic. Check infrastructure.
8. **Mortal Check every 30 minutes.** Prove the server is alive before continuing.
9. **DDI cap at 3.** After two failed BUILD attempts, the approach is wrong. Reset.
10. **Writer/Reviewer always split.** The agent that wrote the fix cannot review it.
---
## PHILOSOPHICAL FOUNDATIONS
- **Karl Popper (Falsificationism):** Fence tests are falsification probes. "Can I break this?" not "Does this work?"
- **Nassim Taleb (Antifragility):** By constantly probing and breaking, we're hardening. We don't fear the Raptor; we hunt it.
- **René Descartes (Radical Doubt):** The ONE thing you cannot fake is whether the signal appeared. The spark is our cogito.
- **Donald Rumsfeld (Unknown Unknowns):** The Raptor Protocol surfaces unknown unknowns — bugs you didn't even know you had.
- **Military Intelligence (Triangulation):** Never trust a single source. The emoji signal is your independent channel.
- **Taiichi Ohno (Five Whys):** Every symptom has a root cause. Keep asking why until you reach something actionable and systemic.
- **Edward Gauss (Wolf Fence, 1982):** Binary search is O(log n). Linear search is O(n). Choose your weapon.
---
*"TOUCH THE FENCE. TRUST THE SPARK."*
*— The Sinner King's Mandate*
*Code is my art. I iterate until it sings. This protocol is the craft behind the craft.*
⛬ KID:CORE:DOCTRINE:DEBUG-PROTOCOL|1.0:LIVE:2026-02-25:⌂ ⛬