@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/_general/methodology/debug-swarm-researcher-escape-hatch.md

@@ -1,240 +1,240 @@
----
-name: debug-swarm-researcher-escape-hatch
-category: methodology
-version: 1.0.0
-contributed: 2026-03-04
-contributor: dominion-flow-v2
-last_updated: 2026-03-04
-tags: [debugging, swarm, multi-agent, escape-hatch, researcher, blocked, orchestration, autonomous-loop]
-difficulty: hard
-usage_count: 0
-success_rate: 100
----
-
-# Debug Swarm Researcher Escape Hatch
-
-## Problem
-
-Multi-agent debug swarms run parallel agents attacking the same bug from different hypotheses. When every hypothesis fails — every agent returns BLOCKED — the orchestrator is stuck. Spinning up identical agents produces identical failures. Halting loses all session context.
-
-**Symptoms:**
-- All swarm agents return `{status:"BLOCKED", issue, attempts_made[], error_context}` after N iterations
-- No remaining hypotheses to test
-- Loop stagnation: circuit breaker fires (`CB_STAGNATION >= limit`)
-- Problem requires external knowledge: prior art, community solution, docs deep-dive
-
-**The core trap:** You can't debug your way out of a knowledge gap. The swarm needs new information before it can make progress.
-
-## Solution Pattern
-
-When the swarm hits a collective wall, **escape the debug loop entirely** and spawn a dedicated researcher agent. The researcher searches external sources (skills library, MCP servers, WebSearch, GitHub) and writes structured findings to a persistent file. The findings file is then injected into the next swarm iteration as first-class context.
-
-### The Three-Layer Escape
-
-```
-Layer 1: SWARM AGENTS (parallel per hypothesis)
-  ↓ All return BLOCKED
-Layer 2: ESCAPE TRIGGER (orchestrator detects collective BLOCKED)
-  ↓ Spawns fire-researcher instead of re-trying swarm
-Layer 3: RESEARCHER (skills lib + MCP + WebSearch + GitHub)
-  ↓ Writes .planning/research/YYYY-MM-DD-{slug}.md
-  ↓ Returns research summary to orchestrator
-Layer 1 again: NEW SWARM AGENTS (with research injected as context)
-  ↓ Fresh hypotheses informed by external knowledge
-```
-
-**Key insight:** The escape does NOT count as a swarm iteration. The loop counter
-stays constant. The researcher is outside the iteration budget.
-
-### BLOCKED Agent Response Contract
-
-Swarm agents signal a wall using a structured response:
-
-```json
-{
-  "status": "BLOCKED",
-  "issue": "Cannot determine why X fails — tried Y and Z",
-  "attempts_made": [
-    "Checked env variable binding — correct",
-    "Added console.log to line 47 — never fires",
-    "Tried disabling auth middleware — same result"
-  ],
-  "error_context": {
-    "error": "Cannot read properties of undefined (reading 'id')",
-    "file": "src/auth/middleware.ts",
-    "line": 23,
-    "stack": "..."
-  },
-  "files_checked": ["src/auth/middleware.ts", "src/routes/users.ts"]
-}
-```
-
-The orchestrator collects all BLOCKED responses and synthesizes a research brief.
-
-### Orchestrator Escape Logic
-
-```python
-def check_escape_condition(swarm_results):
-    blocked_count = sum(1 for r in swarm_results if r["status"] == "BLOCKED")
-    if blocked_count == len(swarm_results):
-        # All agents blocked — trigger escape hatch
-        return True
-    return False
-
-def build_research_brief(blocked_responses):
-    # Synthesize what the swarm tried and where it's stuck
-    all_attempts = [a for r in blocked_responses for a in r["attempts_made"]]
-    error_patterns = [r["error_context"] for r in blocked_responses]
-    return {
-        "problem_summary": "...",
-        "attempted_approaches": all_attempts,
-        "error_signatures": error_patterns,
-        "research_queries": [
-            "Cannot read properties undefined middleware chain express",
-            "JWT auth middleware undefined user id request context"
-        ]
-    }
-```
-
-### Researcher Sources (priority order)
-
-```
-1. Skills library search   — Has this been solved before in our patterns?
-2. context7 MCP server     — Framework/library official docs
-3. WebSearch               — Community solutions, Stack Overflow, GitHub Issues
-4. GitHub code search      — Real-world implementations of the pattern
-5. Episodic memory search  — Did WE solve a similar issue in a past session?
-```
-
-### Research Output Format
-
-Researcher writes to `.planning/research/YYYY-MM-DD-{slug}.md`:
-
-```markdown
-# Research: {problem title}
-**Date:** YYYY-MM-DD
-**Trigger:** Debug swarm collective BLOCKED — N agents, N attempts
-
-## Root Cause Hypothesis (from research)
-[What the researcher found that the swarm was missing]
-
-## Solution Approach
-[Concrete steps to fix based on external sources]
-
-## Code Reference
-```[language]
-// From: [source URL or skill name]
-[relevant code snippet]
-```
-
-## Sources
-- [Source 1 with URL]
-- [Source 2 with URL]
-
-## Re-injection Prompt
-[Ready-to-use context block for injecting into next swarm iteration]
-```
-
-### Re-injection Into Next Swarm Iteration
-
-After researcher completes, the orchestrator spawns a fresh swarm with the research pre-loaded:
-
-```
-CONTEXT FROM PREVIOUS SWARM + RESEARCHER:
-
-The debug swarm tried N approaches and was blocked. A researcher agent
-investigated and found:
-
-[Research summary — from .planning/research/YYYY-MM-DD-{slug}.md]
-
-Known dead ends (do NOT retry):
-- [attempt 1]
-- [attempt 2]
-
-New hypotheses to test based on research:
-- [fresh hypothesis 1 from external sources]
-- [fresh hypothesis 2]
-```
-
-## Code Example
-
-```markdown
-# fire-debug.md — Swarm Orchestrator (key escape section)
-
-## Swarm Mode Orchestrator
-
-```pseudocode
-results = await Promise.all(swarm_agents.map(agent => agent.run()))
-
-if results.every(r => r.status === "BLOCKED"):
-  # Escape hatch: all agents blocked
-  brief = build_research_brief(results)
-
-  research = await spawn_agent(
-    "fire-researcher",
-    {
-      query: brief.problem_summary,
-      search_sources: ["skills-library", "context7-mcp", "web-search", "github"],
-      write_to: f".planning/research/{today}-{slug}.md"
-    }
-  )
-
-  # Re-spawn swarm with research context (doesn't count as iteration)
-  new_swarm = spawn_swarm(hypotheses=research.new_hypotheses, context=research)
-  results = await new_swarm.run()
-```
-```
-
-## Implementation Steps
-
-1. Define BLOCKED response contract in swarm agent instructions (the JSON shape above)
-2. Implement `check_escape_condition()` in orchestrator — triggers when ALL agents blocked
-3. Implement `build_research_brief()` — synthesizes blocked responses into research queries
-4. Spawn `fire-researcher` (or equivalent) with the brief + write path
-5. Researcher writes structured `.planning/research/YYYY-MM-DD-{slug}.md`
-6. Orchestrator reads research, builds re-injection context block
-7. Spawn fresh swarm iteration with research pre-loaded as context
-
-## When to Use
-
-- Multi-agent debug swarm where ALL agents return BLOCKED simultaneously
-- Problem requires external knowledge (docs, prior art, community solutions)
-- Stagnation circuit breaker has fired due to repeated identical failures
-- The error pattern is unfamiliar — novel framework, obscure edge case, known bug in dependency
-- You want to preserve research findings across sessions (write to disk, not just memory)
-
-## When NOT to Use
-
-- Single-agent debugging (use systematic-debugging skill instead)
-- Only 1-2 agents blocked (not all) — remaining agents may still find a path
-- Problem is clearly a typo or obvious logic error (don't need external research)
-- Swarm has only run 1 iteration (premature escape — try more hypotheses first)
-- Time-critical hotfix where research delay is unacceptable
-
-## Common Mistakes
-
-- **Counting escape as an iteration** — the researcher escape is outside the iteration budget; resetting the loop counter erases progress tracking
-- **Vague research brief** — synthesize specific error signatures and exact code context, not just "it doesn't work". The researcher is only as good as the brief
-- **Not writing research to disk** — if findings stay in memory only, they're lost on session compaction. Always write `.planning/research/*.md`
-- **Re-injecting all research** — only inject the relevant new hypotheses, not the full research doc. Context window is precious
-- **Escaping too early** — require collective BLOCKED (all agents, not just some). Partial blocking means other hypotheses are still viable
-
-## Exit Codes (when used in shell loop)
-
-| Code | Meaning | Action |
-|------|---------|--------|
-| 0 | Bug fixed after research re-injection | Proceed to verify |
-| 2 | Escape triggered, researcher found nothing | Human investigation required |
-| 3 | Research found solution, fix not implemented | Apply research manually |
-
-## Related Skills
-
-- [shell-autonomous-loop-fixplan](_general/methodology/shell-autonomous-loop-fixplan.md) — shell-level loop with BLOCKED signal (exit code 2)
-- [autonomous-multi-phase-build](_general/methodology/autonomous-multi-phase-build.md) — phase-level orchestration
-- [systematic-debugging] — single-agent debugging pattern
-
-## References
-
-- Implemented in: `fire-flow/commands/fire-debug.md` (--swarm mode section)
-- Inspired by: RLHF researcher escalation patterns + bmalph/Ralph BLOCKED exit
-- Contributed from: dominion-flow-v2 build session 2026-03-04
+---
+name: debug-swarm-researcher-escape-hatch
+category: methodology
+version: 1.0.0
+contributed: 2026-03-04
+contributor: dominion-flow-v2
+last_updated: 2026-03-04
+tags: [debugging, swarm, multi-agent, escape-hatch, researcher, blocked, orchestration, autonomous-loop]
+difficulty: hard
+usage_count: 0
+success_rate: 100
+---
+
+# Debug Swarm Researcher Escape Hatch
+
+## Problem
+
+Multi-agent debug swarms run parallel agents attacking the same bug from different hypotheses. When every hypothesis fails — every agent returns BLOCKED — the orchestrator is stuck. Spinning up identical agents produces identical failures. Halting loses all session context.
+
+**Symptoms:**
+- All swarm agents return `{status:"BLOCKED", issue, attempts_made[], error_context}` after N iterations
+- No remaining hypotheses to test
+- Loop stagnation: circuit breaker fires (`CB_STAGNATION >= limit`)
+- Problem requires external knowledge: prior art, community solution, docs deep-dive
+
+**The core trap:** You can't debug your way out of a knowledge gap. The swarm needs new information before it can make progress.
+
+## Solution Pattern
+
+When the swarm hits a collective wall, **escape the debug loop entirely** and spawn a dedicated researcher agent. The researcher searches external sources (skills library, MCP servers, WebSearch, GitHub) and writes structured findings to a persistent file. The findings file is then injected into the next swarm iteration as first-class context.
+
+### The Three-Layer Escape
+
+```
+Layer 1: SWARM AGENTS (parallel per hypothesis)
+  ↓ All return BLOCKED
+Layer 2: ESCAPE TRIGGER (orchestrator detects collective BLOCKED)
+  ↓ Spawns fire-researcher instead of re-trying swarm
+Layer 3: RESEARCHER (skills lib + MCP + WebSearch + GitHub)
+  ↓ Writes .planning/research/YYYY-MM-DD-{slug}.md
+  ↓ Returns research summary to orchestrator
+Layer 1 again: NEW SWARM AGENTS (with research injected as context)
+  ↓ Fresh hypotheses informed by external knowledge
+```
+
+**Key insight:** The escape does NOT count as a swarm iteration. The loop counter
+stays constant. The researcher is outside the iteration budget.
+
+### BLOCKED Agent Response Contract
+
+Swarm agents signal a wall using a structured response:
+
+```json
+{
+  "status": "BLOCKED",
+  "issue": "Cannot determine why X fails — tried Y and Z",
+  "attempts_made": [
+    "Checked env variable binding — correct",
+    "Added console.log to line 47 — never fires",
+    "Tried disabling auth middleware — same result"
+  ],
+  "error_context": {
+    "error": "Cannot read properties of undefined (reading 'id')",
+    "file": "src/auth/middleware.ts",
+    "line": 23,
+    "stack": "..."
+  },
+  "files_checked": ["src/auth/middleware.ts", "src/routes/users.ts"]
+}
+```
+
+The orchestrator collects all BLOCKED responses and synthesizes a research brief.
+
+### Orchestrator Escape Logic
+
+```python
+def check_escape_condition(swarm_results):
+    blocked_count = sum(1 for r in swarm_results if r["status"] == "BLOCKED")
+    if blocked_count == len(swarm_results):
+        # All agents blocked — trigger escape hatch
+        return True
+    return False
+
+def build_research_brief(blocked_responses):
+    # Synthesize what the swarm tried and where it's stuck
+    all_attempts = [a for r in blocked_responses for a in r["attempts_made"]]
+    error_patterns = [r["error_context"] for r in blocked_responses]
+    return {
+        "problem_summary": "...",
+        "attempted_approaches": all_attempts,
+        "error_signatures": error_patterns,
+        "research_queries": [
+            "Cannot read properties undefined middleware chain express",
+            "JWT auth middleware undefined user id request context"
+        ]
+    }
+```
+
+### Researcher Sources (priority order)
+
+```
+1. Skills library search   — Has this been solved before in our patterns?
+2. context7 MCP server     — Framework/library official docs
+3. WebSearch               — Community solutions, Stack Overflow, GitHub Issues
+4. GitHub code search      — Real-world implementations of the pattern
+5. Episodic memory search  — Did WE solve a similar issue in a past session?
+```
+
+### Research Output Format
+
+Researcher writes to `.planning/research/YYYY-MM-DD-{slug}.md`:
+
+```markdown
+# Research: {problem title}
+**Date:** YYYY-MM-DD
+**Trigger:** Debug swarm collective BLOCKED — N agents, N attempts
+
+## Root Cause Hypothesis (from research)
+[What the researcher found that the swarm was missing]
+
+## Solution Approach
+[Concrete steps to fix based on external sources]
+
+## Code Reference
+```[language]
+// From: [source URL or skill name]
+[relevant code snippet]
+```
+
+## Sources
+- [Source 1 with URL]
+- [Source 2 with URL]
+
+## Re-injection Prompt
+[Ready-to-use context block for injecting into next swarm iteration]
+```
+
+### Re-injection Into Next Swarm Iteration
+
+After researcher completes, the orchestrator spawns a fresh swarm with the research pre-loaded:
+
+```
+CONTEXT FROM PREVIOUS SWARM + RESEARCHER:
+
+The debug swarm tried N approaches and was blocked. A researcher agent
+investigated and found:
+
+[Research summary — from .planning/research/YYYY-MM-DD-{slug}.md]
+
+Known dead ends (do NOT retry):
+- [attempt 1]
+- [attempt 2]
+
+New hypotheses to test based on research:
+- [fresh hypothesis 1 from external sources]
+- [fresh hypothesis 2]
+```
+
+## Code Example
+
+```markdown
+# fire-debug.md — Swarm Orchestrator (key escape section)
+
+## Swarm Mode Orchestrator
+
+```pseudocode
+results = await Promise.all(swarm_agents.map(agent => agent.run()))
+
+if results.every(r => r.status === "BLOCKED"):
+  # Escape hatch: all agents blocked
+  brief = build_research_brief(results)
+
+  research = await spawn_agent(
+    "fire-researcher",
+    {
+      query: brief.problem_summary,
+      search_sources: ["skills-library", "context7-mcp", "web-search", "github"],
+      write_to: f".planning/research/{today}-{slug}.md"
+    }
+  )
+
+  # Re-spawn swarm with research context (doesn't count as iteration)
+  new_swarm = spawn_swarm(hypotheses=research.new_hypotheses, context=research)
+  results = await new_swarm.run()
+```
+```
+
+## Implementation Steps
+
+1. Define BLOCKED response contract in swarm agent instructions (the JSON shape above)
+2. Implement `check_escape_condition()` in orchestrator — triggers when ALL agents blocked
+3. Implement `build_research_brief()` — synthesizes blocked responses into research queries
+4. Spawn `fire-researcher` (or equivalent) with the brief + write path
+5. Researcher writes structured `.planning/research/YYYY-MM-DD-{slug}.md`
+6. Orchestrator reads research, builds re-injection context block
+7. Spawn fresh swarm iteration with research pre-loaded as context
+
+## When to Use
+
+- Multi-agent debug swarm where ALL agents return BLOCKED simultaneously
+- Problem requires external knowledge (docs, prior art, community solutions)
+- Stagnation circuit breaker has fired due to repeated identical failures
+- The error pattern is unfamiliar — novel framework, obscure edge case, known bug in dependency
+- You want to preserve research findings across sessions (write to disk, not just memory)
+
+## When NOT to Use
+
+- Single-agent debugging (use systematic-debugging skill instead)
+- Only 1-2 agents blocked (not all) — remaining agents may still find a path
+- Problem is clearly a typo or obvious logic error (don't need external research)
+- Swarm has only run 1 iteration (premature escape — try more hypotheses first)
+- Time-critical hotfix where research delay is unacceptable
+
+## Common Mistakes
+
+- **Counting escape as an iteration** — the researcher escape is outside the iteration budget; resetting the loop counter erases progress tracking
+- **Vague research brief** — synthesize specific error signatures and exact code context, not just "it doesn't work". The researcher is only as good as the brief
+- **Not writing research to disk** — if findings stay in memory only, they're lost on session compaction. Always write `.planning/research/*.md`
+- **Re-injecting all research** — only inject the relevant new hypotheses, not the full research doc. Context window is precious
+- **Escaping too early** — require collective BLOCKED (all agents, not just some). Partial blocking means other hypotheses are still viable
+
+## Exit Codes (when used in shell loop)
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 0 | Bug fixed after research re-injection | Proceed to verify |
+| 2 | Escape triggered, researcher found nothing | Human investigation required |
+| 3 | Research found solution, fix not implemented | Apply research manually |
+
+## Related Skills
+
+- [shell-autonomous-loop-fixplan](_general/methodology/shell-autonomous-loop-fixplan.md) — shell-level loop with BLOCKED signal (exit code 2)
+- [autonomous-multi-phase-build](_general/methodology/autonomous-multi-phase-build.md) — phase-level orchestration
+- [systematic-debugging] — single-agent debugging pattern
+
+## References
+
+- Implemented in: `dominion-flow-v2/commands/fire-debug.md` (--swarm mode section)
+- Inspired by: RLHF researcher escalation patterns + bmalph/Ralph BLOCKED exit
+- Contributed from: dominion-flow-v2 build session 2026-03-04

package/skills-library/_general/methodology/shell-autonomous-loop-fixplan.md

@@ -234,5 +234,5 @@ exit 1
 
 - Inspired by: [bmalph](https://github.com/LarsCowe/bmalph) — Ralph autonomous loop pattern
 - Ralph loop architecture: `ralph_loop.sh` in bmalph v2.7.0
-- Gap analysis session: 2026-03-04 fire-flow-v2 implementation
+- Gap analysis session: 2026-03-04 dominion-flow-v2 implementation
 - Contributed from: dominion-flow-v2 build session

package/skills-library/_general/patterns-standards/GOF_DESIGN_PATTERNS_FOR_AI_AGENTS.md

@@ -220,11 +220,11 @@ Code → [Tier 1: Build/Types/Lint] → FAIL? Stop.
 
 **When to use:** When agent sessions end and the next session needs to resume from the same state. Context preservation across the session boundary.
 
-### 18. Observer → Live Breadcrumb Protocol
+### 18. Observer → Cross-Agent Learning
 
 **Classical:** When one object changes, all dependents are notified.
 
-**AI Agent equivalent:** When any agent discovers a lesson, failure, pattern, or dependency, it writes to the breadcrumb files (LESSONS.md, FAILURES.md, PATTERNS.md, DEPENDENCIES.md). All subsequent agents read these files on startup — they're "notified" of changes through the file system.
+**AI Agent equivalent:** When any agent discovers a lesson, failure, pattern, or dependency, it records it in shared project state. All subsequent agents read this state on startup — they're "notified" of changes through the file system.
 
 **When to use:** When discoveries by one agent should influence all future agents without explicit coupling.
 
@@ -267,7 +267,7 @@ HALF-OPEN → try researched alternative with guardrails
 
 ```
 Template:
-  1. Load context (VISION, CONSCIENCE, breadcrumbs)    ← fixed
+  1. Load context (VISION, CONSCIENCE, project state)   ← fixed
   2. Validate prerequisites (path, phase, DoR)          ← fixed
   3. [OVERRIDE: Core work]                              ← varies by agent
   4. Write artifacts (BLUEPRINT/RECORD/VERIFICATION)    ← fixed
@@ -307,7 +307,7 @@ Template:
 | Iterator | Behavioral | Breath-based execution | 2-4 tasks per breath |
 | Mediator | Behavioral | Autonomous orchestrator | fire-autonomous |
 | Memento | Behavioral | WARRIOR handoffs | Session state capture |
-| Observer | Behavioral | Breadcrumb protocol | LESSONS/FAILURES/PATTERNS |
+| Observer | Behavioral | Cross-agent learning | Shared project state |
 | State | Behavioral | Circuit breaker | CLOSED/OPEN/HALF-OPEN |
 | Strategy | Behavioral | Stuck interventions | 6 types × 6 strategies |
 | Template Method | Behavioral | Agent lifecycle | Load → Validate → Work → Write → Report |
@@ -333,7 +333,7 @@ Template:
 
 - **Confusing Strategy with State** — Strategy = choosing an algorithm. State = changing behavior based on accumulated state. Stuck-type classification is Strategy. Circuit breaker is State.
 - **Skipping Facade** — Systems without an OVERVIEW doc force every new agent to read everything. Add a facade early.
-- **Missing Observer** — If agent discoveries die with the session, you have no Observer pattern. Add breadcrumbs.
+- **Missing Observer** — If agent discoveries die with the session, you have no Observer pattern. Add shared state files.
 
 ## Related Skills
 

package/skills-library/_general/patterns-standards/cascading-failure-diagnosis.md

@@ -0,0 +1,119 @@
+---
+name: cascading-failure-diagnosis
+category: patterns-standards
+version: 1.0.0
+contributed: 2026-03-12
+contributor: claude-mission-control
+last_updated: 2026-03-12
+contributors:
+  - claude-mission-control
+tags: [debugging, react, performance, cascading, diagnosis, layered]
+difficulty: hard
+usage_count: 0
+success_rate: 100
+---
+
+# Cascading Failure Diagnosis
+
+## Problem
+
+A UI appears "glitchy" or "broken" with no single clear error. The symptoms are vague — clicks don't respond, the app freezes briefly, components flash or re-render excessively. Traditional debugging (find error → fix) fails because there is no single root cause. Instead, **multiple independent bugs stack** to create a compound failure that looks like one problem but is actually 3-5 layered issues.
+
+**Symptoms:**
+- App feels "slow" or "clicky" with no specific error
+- Fixing one thing doesn't resolve the overall problem
+- Console shows mixed signals (some errors, some warnings, some clean)
+- Performance profiler shows multiple hot paths, not one bottleneck
+
+## Solution Pattern
+
+**Layer-by-layer peeling** — instead of looking for THE bug, systematically isolate and fix bugs starting from the lowest layer (infrastructure/connection) upward to the highest (UI/rendering). Each fix reveals the next layer's bug that was previously masked.
+
+### The Diagnostic Stack (bottom to top)
+
+```
+Layer 4: UI/Rendering    ← re-render storms, wrong data display
+Layer 3: Data Shape      ← API response != client expectation
+Layer 2: React Lifecycle ← hooks ordering, effect dependencies
+Layer 1: Connection      ← exhausted pools, slow endpoints, timeouts
+```
+
+**Always diagnose bottom-up.** A connection issue (Layer 1) can cause timeouts that trigger re-renders (Layer 4), making it look like a UI bug. Fixing Layer 4 first wastes time because the root is at Layer 1.
+
+## Code Example
+
+```javascript
+// Real-world example: C3 Dashboard had 4 stacked bugs
+
+// Layer 1: Connection exhaustion
+// BEFORE: Health endpoint did heavy I/O, slow responses exhausted Vite proxy pool
+app.get('/api/system/health', async (req, res) => {
+  const data = await heavyHealthCheck(); // 2-5 second response
+  res.json(data);
+});
+// AFTER: Add zero-I/O ping endpoint for connection checks
+app.get('/api/ping', (req, res) => res.json({ ok: true }));
+
+// Layer 2: React hooks crash
+// BEFORE: useMemo placed after early return = hook count mismatch
+function App() {
+  const [loading, setLoading] = useState(true);
+  if (loading) return <Loading />;          // early return BEFORE hooks
+  const panels = useMemo(() => build(), []); // hook after conditional = crash
+}
+// AFTER: All hooks before any conditional returns
+function App() {
+  const [loading, setLoading] = useState(true);
+  const panels = useMemo(() => build(), []); // hooks FIRST
+  if (loading) return <Loading />;           // conditionals AFTER
+
+// Layer 3: Data shape mismatch
+// BEFORE: Server returned array, client expected { loops: [...] }
+const data = await fetch('/api/loops').then(r => r.json());
+const loops = data.loops; // undefined — server sent raw array
+// AFTER: Handle both shapes or fix server response
+
+// Layer 4: Re-render storm
+// BEFORE: 25 panel renderers recreated every render
+const sections = panels.map(p => ({ render: () => <Panel {...p} /> }));
+// AFTER: Memoize panel renderers
+const sections = useMemo(() =>
+  panels.map(p => ({ render: () => <Panel {...p} /> })), [panels]);
+```
+
+## Implementation Steps
+
+1. **Start at Layer 1 (Connection):** Check network tab — are requests timing out, queuing, or returning errors? Fix connection/endpoint issues first.
+2. **Move to Layer 2 (Lifecycle):** Check console for React warnings about hooks, effects, or unmounted components. Fix hook ordering and dependency arrays.
+3. **Check Layer 3 (Data):** Log API responses — does the shape match what components expect? Fix response parsing.
+4. **Finish at Layer 4 (Rendering):** Use React DevTools Profiler — are components re-rendering unnecessarily? Add memoization.
+5. **After each layer fix, re-test** — the next layer's symptoms will now be clearer.
+
+## When to Use
+
+- App has vague "it's broken" symptoms with no clear single error
+- Fixing one bug doesn't resolve the overall issue
+- Performance profiler shows multiple hot paths
+- The problem appeared suddenly after multiple changes
+
+## When NOT to Use
+
+- There's a clear, single error message — fix that directly
+- The issue is purely visual (CSS/layout) — no cascading involved
+- The app crashes with a stack trace pointing to one location
+
+## Common Mistakes
+
+- **Starting at the wrong layer** — fixing UI re-renders when the real issue is connection exhaustion
+- **Declaring victory after fixing one layer** — always test all layers after each fix
+- **Assuming a single root cause** — cascading failures by definition have multiple independent causes
+- **Using console.log debugging only** — use Network tab (Layer 1), React DevTools (Layer 2-4), and Profiler (Layer 4)
+
+## Related Skills
+
+- [react-hooks-order-debugging](../_general/frontend/react-hooks-order-debugging.md) — Layer 2 specific fix
+- [ref-based-canvas-animation](../_general/performance/ref-based-canvas-animation.md) — Layer 4 performance pattern
+
+## References
+
+- Contributed from: claude-mission-control C3 Dashboard (4 stacked bugs fixed in one session, 2026-03-12)