@thierrynakoa/fire-flow 10.0.0 → 12.2.0

package/skills-library/_general/methodology/CONTEXT_ROTATION.md

@@ -0,0 +1,151 @@
+---
+name: CONTEXT_ROTATION
+category: methodology
+description: Fresh-eyes debugging science — when and how to rotate context to break fixation, with cognitive science backing and practical protocols for AI agent handoffs
+version: 1.0.0
+tags: [context-rotation, fresh-eyes, fixation, incubation, debugging, handoff]
+sources:
+  - "Duncker (1945) — Functional Fixedness"
+  - "Springer Memory & Cognition — Interrupted distributed effort and incubation"
+  - "Psychology Today — Rubber Duck Debugging Psychology"
+  - "Frontiers in Education — Functional Fixedness in Problem Solving"
+  - "The Decision Lab — Functional Fixedness bias"
+---
+
+# Context Rotation Protocol
+
+> **Core insight:** A stuck agent with degraded context is the worst possible solver. A fresh agent with full context and documented prior attempts is the best. Context window length is a fixation risk, not just a token limit.
+
+---
+
+## 1. The Science of Getting Stuck
+
+### Functional Fixedness (Duncker, 1945)
+Once a problem-solver commits to a conceptual framing, they become blind to alternative framings — even when the solution is obvious in retrospect. Five-year-olds solve certain problems faster than adults because they have less fixation on conventional uses.
+
+**For AI agents:** An agent that has spent 4+ exchanges approaching a bug as a data model issue will continue framing it as a data model issue even when symptoms clearly suggest concurrency. The longer the context window stays focused on one framing, the deeper the fixation.
+
+### Incubation Effect
+Research shows approaching problems "briefly and repeatedly" rather than continuously reduces fixation:
+- Stopping work BEFORE hitting a wall preserves the ability to restructure
+- Incubation specifically benefits **insight problems** (where the wrong approach actively blocks the right one)
+- Less effective for **analytical problems** (where grinding produces incremental progress)
+
+**Classification question before rotation:** Is this a grinding problem (try harder) or an insight problem (fixation is the enemy)? The answer determines whether iteration or rotation is correct.
+
+---
+
+## 2. When to Rotate Context
+
+| Signal | Type | Action |
+|--------|------|--------|
+| Same approach, 3+ syntax variations | Fixation | Rotate immediately |
+| Context compaction just happened | Degradation | Consider rotation |
+| Agent confidence dropping each attempt | Diminishing returns | Rotate after next failure |
+| "I've tried everything I can think of" | Exhaustion | Rotate with full dead-end map |
+| Different approach, same class of error | Deeper issue | Research first, then rotate if no resolution |
+
+### When NOT to Rotate
+- Transient errors (API timeout, build cache) — retry is cheaper
+- Missing information (credentials, config) — human input needed, not fresh eyes
+- Making steady progress — don't fix what isn't broken
+
+---
+
+## 3. What the Fresh Agent Receives
+
+**Critical rule:** Give the fresh agent the dead-end MAP, not the dead-end JOURNEY.
+
+### Give:
+```markdown
+## Problem Context for Fresh Instance
+
+**Goal:** {what needs to be accomplished}
+**Current state:** {what exists, what's working}
+
+**Approaches tried (outcome map):**
+1. {approach} → Failed because: {root cause}
+2. {approach} → Failed because: {root cause}
+3. {approach} → Failed because: {root cause}
+
+**Constraints identified:**
+- {constraint 1 — verified, not assumed}
+- {constraint 2 — verified, not assumed}
+
+**Untested hypotheses:**
+- {idea 1 — why it might work}
+- {idea 2 — why it might work}
+
+**Relevant files:** {specific paths}
+```
+
+### Do NOT give:
+- Full conversation history (propagates the original framing/fixation)
+- Emotional language ("this is really frustrating", "nothing works")
+- Vague descriptions ("I tried a bunch of things")
+
+**Why:** The fresh agent needs boundary knowledge (where NOT to walk) and starting context (where TO start). It does not need the journey narrative — that's what created the fixation in the first place.
+
+---
+
+## 4. Articulation Protocol (Rubber Duck Step)
+
+Before any rotation, require the stuck agent to produce a structured articulation:
+
+```markdown
+## Articulation (Pre-Rotation)
+
+1. What I was trying to do: {goal in one sentence}
+2. What I expected to happen: {specific expected behavior}
+3. What actually happened: {specific actual behavior}
+4. What I believe the constraint is: {my theory}
+5. What assumption am I making that might be wrong: {honest assessment}
+```
+
+**Why this works:** Explaining the problem forces sequential, explicit reconstruction of assumptions. The language encoding activates different cognitive pathways than pattern-matching. Research shows this catches 30-40% of stuck cases without needing rotation — the stuck agent solves it by articulating it.
+
+**Agent action:** Always run the articulation step BEFORE spawning a fresh agent. If the articulation reveals the issue, save the rotation cost.
+
+---
+
+## 5. Context Window as Fixation Accumulator
+
+Every exchange in a long session adds fixation weight:
+
+```
+Session start: fixation_risk = LOW
+  After 10 exchanges on same topic: fixation_risk = MEDIUM
+  After 20 exchanges on same topic: fixation_risk = HIGH
+  After context compaction: fixation_risk = ELEVATED
+    (compaction removes details but preserves framing bias)
+```
+
+**Mitigation strategies (in order of preference):**
+1. **Articulation protocol** — cheapest, catches 30-40%
+2. **Scope switch** — work on a different task, come back later
+3. **Research injection** — read external docs/code to introduce new framing
+4. **Fresh agent with dead-end map** — full context rotation
+5. **Human clarification** — the human may see what both agents missed
+
+---
+
+## 6. The Navigator Pattern (from Pair Programming)
+
+In pair programming research, the **navigator role** (observer, not typist) has the highest fresh-eyes effect — they see what the driver's fixation hides.
+
+**Applied to Dominion Flow:** The fire-verifier IS the navigator. It reads the executor's output from outside the execution context. This is why verifier isolation (separate instance, fresh context) is architecturally important — not just for objectivity, but for fixation prevention.
+
+**Role rotation frequency:**
+- Every task boundary = natural rotation point
+- Every phase boundary = mandatory rotation point (WARRIOR handoff)
+- Mid-task rotation = only when stuck signals detected
+
+---
+
+## When Agents Should Reference This Skill
+
+- **fire-executor:** Run articulation protocol when stuck, classify grinding vs. insight before retrying
+- **fire-verifier:** Leverage navigator advantage — flag issues the executor's fixation may hide
+- **fire-6-resume:** Fresh instance = natural context rotation. Read dead-end map, not prior session transcript
+- **fire-autonomous:** Monitor fixation risk in long sessions, trigger rotation at HIGH
+- **Any agent writing a WARRIOR handoff:** Structure handoff as a dead-end map (outcomes, not journey)

package/skills-library/_general/methodology/DEAD_ENDS_SHELF.md

@@ -0,0 +1,188 @@
+---
+name: DEAD_ENDS_SHELF
+category: methodology
+description: Tag unsolved problems in FAILURES.md for fresh Claude instances — stop burning tokens on dead ends, move on, let cleaner context solve it later
+version: 2.0.0
+tags: [dead-ends, autonomous, cost-optimization, shelving, context-rotation]
+---
+
+# Dead Ends Protocol (v11.3)
+
+When an agent hits a wall — code that won't compile, an API that won't respond, a logic puzzle that burns 3+ attempts — **tag it `[DEAD-END]` in FAILURES.md and move on**. A fresh Claude instance with clean context will attempt it on the next session start.
+
+> **Philosophy:** A stuck agent with degraded context is the worst possible solver. A fresh agent with full context and documented prior attempts is the best. Stop burning tokens on dead ends — rotate the problem to a fresh mind.
+
+> **v11.3 change:** Dead ends are now tagged entries in `breadcrumbs/FAILURES.md` instead of a separate `DEAD-ENDS.md` file. This reduces file count and aligns with the on-demand breadcrumb protocol.
+
+---
+
+## Location: `.planning/breadcrumbs/FAILURES.md`
+
+Dead-end entries live alongside regular failure entries, distinguished by the `[DEAD-END]` tag. They are:
+- **Written by:** Any agent that hits a dead end (executor, planner, verifier, researcher)
+- **Read by:** `/fire-6-resume` on session start — fresh Claude filters for `[DEAD-END]` entries and attempts solutions
+- **Cleared by:** The agent that solves the problem (move entry to `LESSONS.md` with `[DEAD-END-SOLVED]` tag, remove `[DEAD-END]` tag from FAILURES.md)
+
+---
+
+## When to Shelve (Trigger Rules)
+
+| Condition | Action |
+|-----------|--------|
+| **3+ failed attempts** at the same problem | Tag `[DEAD-END]` immediately |
+| **Blocked by missing info** (credentials, API keys, external dependency) | Tag with `[DEAD-END] [NEEDS-HUMAN]` |
+| **Context degradation detected** (compaction happened, losing details) | Tag before context loss |
+| **Confidence drops below 30%** after research | Tag — you're guessing |
+| **Circular dependency** (fix A breaks B, fix B breaks A) | Tag with both sides documented |
+| **Time sink** — 15+ minutes on a single non-critical issue | Tag and move to next task |
+
+### When NOT to Shelve
+
+- Critical path blockers (nothing else can proceed without this)
+- Security vulnerabilities (must fix now)
+- Data loss risks (must fix now)
+
+For critical blockers: escalate to the user via checkpoint, don't shelve.
+
+---
+
+## Dead-End Entry Format
+
+```markdown
+### [DEAD-END] {short title}
+
+**Shelved by:** {agent name} at {timestamp}
+**Phase:** {phase number} / **Plan:** {plan number}
+**Priority:** {critical | high | medium | low}
+**Tags:** {code-bug, api-integration, dependency, logic, config, performance, unknown}
+
+**Problem:** {What you were trying to do and what went wrong — be specific}
+
+**What Was Tried** (prevents next instance from repeating):
+1. {what you tried} → {what happened}
+2. {what you tried} → {what happened}
+3. {what you tried} → {what happened}
+
+**Relevant Files:**
+- `{file path}` — {what matters}
+
+**Error:** `{exact error message}`
+
+**Hypotheses Not Yet Tested:**
+- {idea 1 — why it might work}
+- {idea 2 — why it might work}
+
+**Impact if unsolved:** {what breaks or degrades}
+```
+
+---
+
+## Agent Integration
+
+### fire-executor (writes to FAILURES.md)
+
+When a task hits the shelve trigger:
+
+1. **Stop working on this task** — don't burn more tokens
+2. **Write a `[DEAD-END]` entry** to `.planning/breadcrumbs/FAILURES.md` using the format above
+3. **On first write:** If FAILURES.md doesn't exist, create it with a `# Failures` header first
+4. **Move to next task** — the agent continues with remaining work
+5. **Note in RECORD.md** — "Task X tagged [DEAD-END], moved to Task Y"
+
+### fire-planner (writes to FAILURES.md)
+
+When a planning problem can't be resolved:
+
+1. Write `[DEAD-END]` entry with `Tags: logic` or `Tags: dependency`
+2. Plan around the dead end — design alternative approach that doesn't depend on it
+3. Mark the plan with `dead_end_dependency: true` in frontmatter
+
+### fire-verifier (writes to FAILURES.md)
+
+When verification finds an unfixable issue:
+
+1. Write `[DEAD-END]` entry with exact failing test/check details
+2. Mark verification as CONDITIONAL PASS with `shelved_issues: N`
+
+### fire-researcher (reads + writes FAILURES.md)
+
+In recovery mode, read FAILURES.md and filter for `[DEAD-END]` entries:
+- If match found: include prior attempts in research context (avoid repeating)
+- If no match: tag `[DEAD-END]` if research fails after 3-tier cascade
+
+### fire-6-resume (reads FAILURES.md — THE KEY STEP)
+
+**On every session start, a fresh Claude instance:**
+
+1. Read `.planning/breadcrumbs/FAILURES.md` (if it exists)
+2. Filter for `[DEAD-END]` tagged entries
+3. For the highest-priority entry:
+   - Review the problem, prior attempts, and untested hypotheses
+   - With fresh context, attempt the top untested hypothesis
+   - If solved: move entry to `LESSONS.md` with `[DEAD-END-SOLVED]` tag, remove `[DEAD-END]` tag from FAILURES.md
+   - If still stuck: update the entry with new attempts, re-tag
+4. Then proceed with normal work
+
+> **Why this works:** A fresh Claude instance has full context window, no degradation from prior compactions, and zero emotional attachment to the failed approach. It sees the problem with completely new eyes.
+
+---
+
+## Autonomous Mode Integration
+
+In `/fire-autonomous`, dead-end tagging is critical for cost efficiency:
+
+```
+Agent hits dead end on Task 5
+  → Tags [DEAD-END] in FAILURES.md (30 seconds)
+  → Moves to Task 6, 7, 8 (continues productive work)
+  → Phase completes with 1 tagged dead end
+  → Handoff documents it
+  → Next session: fresh Claude reads FAILURES.md, solves Task 5 with clean context
+```
+
+**Without tagging:** Agent burns 15+ minutes on Task 5, context degrades, Tasks 6-8 suffer. Cost: HIGH, quality: LOW.
+
+**With tagging:** Agent spends 30 seconds documenting Task 5, full context preserved for Tasks 6-8. Cost: LOW, quality: HIGH.
+
+---
+
+## Hygiene
+
+- **Max dead-end entries:** 10 (if more accumulate, oldest low-priority entries get resolved or removed)
+- **Stale check:** If an entry is 5+ sessions old and low-priority, consider removing
+- **Dedup:** Before writing a new entry, grep FAILURES.md for `[DEAD-END]` entries with similar titles — update instead of duplicate
+- **Resolution celebration:** When solved, log to LESSONS.md with `[DEAD-END-SOLVED]` tag — document what the fresh context saw that the burned context missed
+
+---
+
+## Example: Real Dead-End Entry
+
+```markdown
+### [DEAD-END] Podcast feed XML parsing timeout on large feeds
+
+**Shelved by:** fire-executor at 2026-03-04
+**Phase:** 2 / **Plan:** 3
+**Priority:** medium
+**Tags:** api-integration, performance
+
+**Problem:** RSS feed parser hangs on podcast feeds with 500+ episodes.
+`podcastService.getFeed('live-teachings')` takes 45+ seconds and times out.
+
+**What Was Tried:**
+1. Increased timeout to 60s → Still times out on 800-episode feeds
+2. Added `{ limit: 100 }` parameter → Parameter ignored by xml2js parser
+3. Tried streaming parser (sax-js) → Import error, needs different build config
+
+**Relevant Files:**
+- `server/services/podcastService.js` — getFeed method, line 45
+- `server/config/podcast-feeds.json` — feed URLs
+
+**Error:** `TimeoutError: Request timed out after 60000ms at podcastService.getFeed`
+
+**Hypotheses Not Yet Tested:**
+- Use `fast-xml-parser` instead of `xml2js` (reportedly 10x faster)
+- Pre-fetch and cache feeds with a cron job instead of on-demand parsing
+- Paginate at the API level — only parse first N items from XML stream
+
+**Impact if unsolved:** Podcast dropdown shows loading spinner forever for large feeds. Workaround: hardcoded limit of 50 episodes.
+```

package/skills-library/_general/methodology/DESIGN_PHILOSOPHY_ENFORCEMENT.md

@@ -0,0 +1,152 @@
+---
+name: design-philosophy-enforcement
+category: methodology
+version: 1.0.0
+contributed: 2026-03-06
+contributor: dominion-flow
+last_updated: 2026-03-06
+contributors:
+  - dominion-flow
+tags: [architecture, audit, principles, enforcement, agents, meta-design]
+difficulty: hard
+usage_count: 0
+success_rate: 100
+---
+
+# Design Philosophy Enforcement
+
+## Problem
+
+Multi-agent systems document design principles (honesty, research-first, plan-before-execute) but fail to **structurally enforce** them. Principles live in philosophy docs while the actual agent wiring contradicts or ignores them. The gap between stated values and implemented behavior grows silently over versions until the system's behavior no longer matches its stated identity.
+
+Common symptoms:
+- Agents document uncertainty but don't route to research
+- "Plan right, execute once" is stated but execution can skip planning
+- Failure states escalate to the user instead of triggering the system's own research capabilities
+- One-size-fits-all processes (e.g., 70-point checklists) contradict "on-demand over ceremony"
+- Circuit breakers stop the system instead of routing to recovery paths
+
+## Solution Pattern
+
+Audit every principle against three dimensions, then wire missing enforcement into the architecture:
+
+### The Three-Dimensional Audit
+
+For each stated design principle, answer:
+
+1. **STRONG AT** — Where is this principle already structurally enforced? (file:section reference + why it works)
+2. **WEAK AT** — Where is it documented but not wired? (file:section reference + what's missing)
+3. **CONTRADICTED AT** — Where does the system accidentally work against it? (file:section reference + what conflicts)
+
+### Enforcement Categories
+
+Principles can be enforced at four levels (weakest to strongest):
+
+| Level | Name | Example | Strength |
+|-------|------|---------|----------|
+| 1 | **Documented** | "Agents should research when stuck" | Weakest — ignored under pressure |
+| 2 | **Prompted** | Honesty Gate asks "Am I tempted to rush?" | Medium — agent can answer dishonestly |
+| 3 | **Gated** | Plan-checker must approve before execution starts | Strong — blocks progress without compliance |
+| 4 | **Structural** | Executor literally cannot start without BLUEPRINT files existing | Strongest — architecturally impossible to violate |
+
+**The audit goal:** Identify principles stuck at Level 1-2 that should be at Level 3-4.
+
+### The Probe Questions
+
+Use these specific questions to find enforcement gaps:
+
+1. **Failure-path routing:** When an agent hits a wall, does the system route to its own research/recovery capabilities, or does it just stop/escalate?
+2. **Honesty reward loop:** When an agent admits "I don't know," does the architecture automatically trigger research, or just document the admission?
+3. **Ceremony detection:** Are there mandatory processes that run regardless of scope? Do small changes get the same heavyweight treatment as large features?
+4. **Skip-ability:** Can agents bypass stated requirements via flags (--skip-verify, --quick) that exist "for convenience" but undermine the principle?
+5. **Capability matching:** Do agents that encounter problems have the tools to solve them? (e.g., does the verifier have web search when it encounters unfamiliar failures?)
+6. **Cross-gap clustering:** Do enforcement gaps cluster in one area (e.g., all at failure-time transitions, all in one agent, all in one phase)?
+
+### The Fix Pattern
+
+For each gap found, apply the minimum enforcement level that closes it:
+
+```
+IF principle is violated because agents don't know about it:
+  → Level 2: Add to agent prompt/honesty gate
+
+IF principle is violated because agents can skip it:
+  → Level 3: Add a gate (file existence check, status field, approval step)
+
+IF principle is violated because the architecture allows bypass:
+  → Level 4: Remove the bypass, restructure the flow
+
+IF principle is contradicted by another mechanism:
+  → Resolve the contradiction: one must yield
+  → Usually the contradicting mechanism is older and was never updated
+```
+
+## Code Example
+
+```markdown
+// Before (principle documented but not enforced)
+
+## Design Philosophy
+- "Research when hitting a wall" — don't brute-force
+
+## Circuit Breaker (in executor)
+IF same error 5+ times:
+  → STOP. Escalate to user.
+  // Gap: system has a researcher agent but doesn't use it here
+
+// After (principle structurally enforced)
+
+## Circuit Breaker (in executor)
+IF same error 3+ times:
+  → WARNING: Spawn fire-researcher with error context
+  → Researcher returns 2-3 alternatives (ranked by confidence)
+  → Retry with top alternative
+
+IF same error 5+ times AND researcher exhausted:
+  → STOP. Escalate to user with research findings attached.
+  // Now the principle is enforced: research happens before escalation
+```
+
+## Implementation Steps
+
+1. **List all stated design principles** — extract from philosophy docs, READMEs, foundational documents
+2. **For each principle, audit all agents and commands** — use the STRONG/WEAK/CONTRADICTED framework
+3. **Identify enforcement level** for each principle in each location (Level 1-4)
+4. **Flag gaps** where enforcement level is below what the principle requires
+5. **Check for cross-gap patterns** — do gaps cluster in failure paths? in one agent? in one phase?
+6. **Prioritize fixes** by how many principles a single change reinforces simultaneously
+7. **Apply minimum viable enforcement** — don't over-gate; the lightest enforcement that closes the gap
+
+## When to Use
+
+- After major version releases of an agent framework (v11 audit before v12 work begins)
+- When users report that the system "doesn't feel like it follows its own rules"
+- When onboarding new agents or commands — verify they inherit all principle enforcement
+- When a post-mortem reveals the system had the capability to prevent a failure but didn't use it
+- Quarterly health checks on multi-agent architectures
+
+## When NOT to Use
+
+- On systems too small to have stated principles (single-script tools)
+- During active feature development — audit between milestones, not during sprints
+- When principles themselves need revision — update the principles first, then audit enforcement
+
+## Common Mistakes
+
+- **Auditing only the happy path** — most enforcement gaps appear at failure-time transitions (circuit breaker trips, low confidence, verification failures), not during successful execution
+- **Adding more documentation instead of structural gates** — if agents already ignore Level 1-2 enforcement, adding more docs won't help; move to Level 3-4
+- **Over-gating** — not every principle needs Level 4 enforcement; some are genuinely better as prompted guidelines
+- **Fixing symptoms not patterns** — if gaps cluster in one area (e.g., all failure-path routing), fix the systemic pattern rather than patching each gap individually
+
+## Related Skills
+
+- [EVIDENCE_BASED_VALIDATION](../../methodology/EVIDENCE_BASED_VALIDATION.md)
+- [INSTRUMENTATION_OVER_RESTRICTION](../../methodology/INSTRUMENTATION_OVER_RESTRICTION.md)
+- [CONFIDENCE_GATED_EXECUTION](../../methodology/CONFIDENCE_GATED_EXECUTION.md)
+
+## References
+
+- Dominion Flow v11.3 principles audit (2026-03-06) — first application of this methodology
+- The "Three Questions" honesty gate pattern — example of Level 2 enforcement done well
+- Recovery Research Mode (4-tier cascade) — example of Level 4 structural enforcement
+- ACE: Agentic Context Engineering (ICLR 2026) — adaptive playbooks as runtime principle enforcement