@thierrynakoa/fire-flow 10.0.0

package/skills-library/methodology/REFLEXION_MEMORY_PATTERN.md

@@ -0,0 +1,183 @@
+# Reflexion Memory Pattern — Cross-Session Failure Learning
+
+## The Problem
+
+AI agents repeat the same mistakes across sessions because failure context is lost. Debug sessions resolve issues, but the knowledge dies with the session. The next agent encountering the same symptoms starts from scratch.
+
+### Why It Was Hard
+
+- Debug sessions produce rich context (symptoms, hypotheses, evidence, root causes) but it's trapped in `.planning/debug/` files that are project-specific and not searchable cross-project
+- Failed approaches are the most valuable learning — but agents only record what *worked*, not what *didn't*
+- Finding the right granularity: too detailed = noise, too abstract = useless
+- Integration requires modifying multiple command flows (debug, loop, execute)
+
+### Impact
+
+- Same bugs debugged repeatedly across sessions (hours wasted)
+- Silent failures re-investigated from scratch every time
+- No institutional memory of "this library is broken on Python 3.14"
+- Debug sessions take 3x longer than necessary when prior knowledge exists
+
+---
+
+## The Solution
+
+### Root Cause
+
+Agent systems store *conclusions* (handoffs, skills) but not *journeys* (what was tried, what failed, why). Reflexion research shows that storing the journey as linguistic self-reflection dramatically improves future performance (91% pass@1 vs baselines).
+
+### The Reflection File Format
+
+```markdown
+---
+type: reflection
+date: 2026-02-20
+project: claude-voice-bridge
+trigger: debug-resolution | test-failure | approach-rotation | stalled-loop
+severity: minor | moderate | critical
+tags: [pynput, keyboard, hotkeys, python-3.14]
+---
+# What I tried and why it failed
+
+## The Problem
+Hotkeys stopped responding. No errors — completely silent failure.
+
+## What I Tried (and why each failed)
+1. **Checked keyboard library hooks** — hooks installed, listener alive,
+   but zero callbacks. Root cause: keyboard 0.13.5 broken on Python 3.14.
+2. **Switched to pynput with char matching** — pynput works, but Ctrl+M
+   sends '\r' not 'm'. Silent mismatch.
+
+## What Actually Worked
+Used `KeyCode.from_vk(ord(name.upper()))` — VK codes are stable
+regardless of modifier state.
+
+## The Lesson
+When a library installs without errors but produces no output, suspect
+Python version incompatibility. Always match keyboard keys by VK code,
+never by char when modifiers are involved.
+
+## Future Self: Search For This When
+- Hotkeys stop working silently
+- Keyboard hooks fire zero events
+- Ctrl+letter combinations fail to match
+```
+
+### Three Integration Points
+
+**1. Pre-Investigation Search (Step 2.5 in debug flow):**
+```
+Before investigating any issue:
+  Search reflections: /fire-remember "{symptoms}" --type reflection
+
+  If match found with >0.75 similarity:
+    "I've seen this before — {lesson}. Applying directly."
+    Offer: [Apply same fix] [Investigate fresh] [Compare differences]
+```
+
+**2. Post-Resolution Capture (Step 7.5 in debug flow):**
+```
+After root cause found and fix verified:
+  Auto-generate reflection from debug file
+  Extract: symptoms → failed hypotheses → root cause → fix → lesson
+
+  Severity classification:
+    critical: 5+ eliminated hypotheses OR 10+ files changed
+    moderate: 2-4 eliminated hypotheses OR multi-file fix
+    minor: 1 hypothesis OR single-file fix
+```
+
+**3. Loop Failure Capture (Step 9 in loop):**
+```
+On STALLED (3+ iterations no progress):
+  Save reflection with trigger: "stalled-loop"
+  Include: what was attempted, measurements, why no progress
+
+On SPINNING (same error repeated):
+  Save reflection with trigger: "approach-rotation"
+  Include: each failed approach with error hash
+```
+
+### Storage & Search
+
+```
+Location:     ~/.claude/reflections/
+Indexed in:   Qdrant as sourceType: 'reflection'
+Search:       /fire-remember "{query}" --type reflection
+Command:      /fire-reflect capture|search|list|review
+```
+
+---
+
+## Testing the Fix
+
+### Verification Steps
+
+1. Create a reflection file manually in `~/.claude/reflections/`
+2. Run `npm run consolidate` to index it
+3. Search: `npm run search -- "hotkeys silent failure" --type reflection`
+4. Confirm the reflection appears in results with correct sourceType
+
+### Quality Checklist
+
+A good reflection has:
+- [ ] Specific symptoms (error messages, observed behaviors)
+- [ ] Multiple failed approaches with *reasons* they failed
+- [ ] Concrete solution (code, command, config change — not vague advice)
+- [ ] One-sentence lesson useful without context
+- [ ] Search triggers matching how you'd describe the problem naturally
+
+A bad reflection:
+- "Something was wrong with the API" (too vague)
+- Only records the solution without the journey
+- Lesson is "be more careful" (not actionable)
+
+---
+
+## Prevention
+
+1. Make reflection generation **automatic** after debug resolution — don't rely on manual capture
+2. Keep reflections **concise** — the lesson and search triggers are most important
+3. Review reflections periodically — merge duplicates, update outdated ones
+4. Tag with specific technologies and error patterns for better search
+
+---
+
+## Related Patterns
+
+- [AGENT_SELF_IMPROVEMENT_LOOP](./AGENT_SELF_IMPROVEMENT_LOOP.md) - Full 6-upgrade blueprint
+- [CONFIDENCE_GATED_EXECUTION](./CONFIDENCE_GATED_EXECUTION.md) - Reflections feed confidence scoring
+- [WARRIOR_WORKFLOW_DEBUGGING_PROTOCOL](./WARRIOR_WORKFLOW_DEBUGGING_PROTOCOL.md) - Debug flow where reflections integrate
+
+---
+
+## Common Mistakes to Avoid
+
+- Capturing reflections for trivial issues (typo fixes, config changes) — noise overwhelms signal
+- Writing the "lesson" as a platitude ("always test thoroughly") instead of a specific takeaway
+- Not including search triggers — the reflection exists but is unfindable
+- Storing reflections per-project instead of globally — defeats cross-session learning
+- Skipping the "what I tried" section — the failed approaches are the most valuable part
+
+---
+
+## Resources
+
+- Reflexion (NeurIPS 2023): https://arxiv.org/abs/2303.11366
+- "Language Agents with Verbal Reinforcement Learning" — Shinn et al.
+- Dominion Flow implementation: `/fire-reflect` command, `fire-debug.md` Steps 2.5 and 7.5
+
+---
+
+## Time to Implement
+
+**2-3 hours** — Create reflection directory, write command, modify debug/loop flows, add to vector index
+
+## Difficulty Level
+
+Stars: 2/5 — Conceptually simple. The hard part is building the discipline to actually search reflections before investigating and to capture them after resolution.
+
+---
+
+**Author Notes:**
+The most surprising finding from implementing this: the "Future Self: Search For This When" section is the single most valuable field. It's the bridge between how you describe the problem *now* (with full context) and how a future agent will describe it (with zero context, just symptoms). Writing good search triggers is an act of empathy toward your future self.

package/skills-library/methodology/RESEARCH_BACKED_WORKFLOW_UPGRADE.md

@@ -0,0 +1,263 @@
+# Research-Backed Workflow Upgrade Pattern - Methodology & Implementation
+
+## The Problem
+
+AI agent workflows (WARRIOR, Dominion Flow, etc.) evolve through manual intuition — someone notices a gap, proposes a fix, implements it. This works for small changes but misses systemic improvements that academic research and community patterns have already solved.
+
+### Why It Was Hard
+
+- Academic papers (ACL, NeurIPS, ICML) contain breakthrough findings but use jargon that's hard to map to practical workflow changes
+- Community patterns (Manus AI, Replit Agent, Bolt.new) are scattered across blog posts, tweets, and GitHub repos — no single source
+- Internal gap analysis requires stepping back from the code to see structural blind spots (cross-phase contradictions, context drift, broken handoff chains)
+- Synthesizing 50+ findings from different domains into a coherent upgrade plan is overwhelming without structure
+
+### Impact
+
+Without systematic research-backed upgrades:
+- Workflows reinvent solutions that papers already proved effective
+- Known failure modes (context drift, assumption contradictions) repeat across projects
+- Improvements are reactive (fix after failure) instead of proactive (prevent before failure)
+- Agent performance plateaus because upgrades are incremental rather than informed by state-of-the-art
+
+---
+
+## The Solution
+
+### The 4-Agent Parallel Research Sweep
+
+Launch 4 specialized research agents in parallel, each covering a different knowledge domain. They work independently and return findings that you synthesize into a prioritized upgrade plan.
+
+### Step 1: Define Research Scopes
+
+Split the research into 4 non-overlapping domains:
+
+```
+Agent 1: Academic Papers (2024-2026)
+  - Search: AI agent papers, multi-agent systems, code generation, debugging
+  - Sources: ACL, NeurIPS, ICML proceedings, arXiv
+  - Goal: Find proven techniques with measurable results (pass@1, accuracy, etc.)
+
+Agent 2: Community Workflow Patterns
+  - Search: AI coding tool blogs, developer experience posts, open-source agents
+  - Sources: Manus AI, Replit, Cursor, Bolt.new, Devin, SWE-Agent
+  - Goal: Find practical patterns already working in production
+
+Agent 3: Testing & Verification Research
+  - Search: AI testing frameworks, automated verification, quality assurance
+  - Sources: SWE-Bench, METR studies, CI/CD integration patterns
+  - Goal: Find ways to verify agent work more reliably
+
+Agent 4: Internal Gap Analysis
+  - Search: Your own workflow files, past handoffs, known failure modes
+  - Sources: The actual workflow documentation being upgraded
+  - Goal: Find structural gaps, contradictions, missing features
+```
+
+### Step 2: Launch All 4 Agents Simultaneously
+
+```javascript
+// Launch in a SINGLE message (parallel execution):
+
+// Agent 1: Academic research
+Task({
+  subagent_type: "general-purpose",
+  description: "Research AI agent papers 2024-2026",
+  prompt: "Search for recent AI papers on: multi-agent code generation, " +
+          "debugging with plan context, context window management, " +
+          "task recitation, agent evaluation. For each paper found, " +
+          "extract: title, key finding, measurable result, and how it " +
+          "could improve [YOUR WORKFLOW NAME]. Return top 15 findings."
+});
+
+// Agent 2: Community patterns
+Task({
+  subagent_type: "general-purpose",
+  description: "Research community AI workflow patterns",
+  prompt: "Search for blog posts and docs from Manus AI, Replit Agent, " +
+          "Bolt.new, Cursor, Devin about: context engineering, " +
+          "decision-time guidance, agent loops, workflow structure. " +
+          "For each pattern, extract: source, pattern name, how it works, " +
+          "and how it could improve [YOUR WORKFLOW NAME]. Return top 15."
+});
+
+// Agent 3: Testing & verification
+Task({
+  subagent_type: "general-purpose",
+  description: "Research AI testing and verification",
+  prompt: "Search for: SWE-Bench results, METR studies, AI agent " +
+          "evaluation frameworks, automated code review patterns. " +
+          "Focus on: what makes agent verification reliable, common " +
+          "failure modes, confidence calibration. Return top 10 findings."
+});
+
+// Agent 4: Internal gap analysis
+Task({
+  subagent_type: "Explore",
+  description: "Analyze current workflow gaps",
+  prompt: "Read all workflow files in [YOUR WORKFLOW PATH]. Identify: " +
+          "structural gaps (missing features), contradictions between " +
+          "files, assumptions that aren't tracked, handoff points that " +
+          "could break, areas where agents lack guidance. Return top 10 gaps."
+});
+```
+
+### Step 3: Synthesize Into Priority Tiers
+
+When all 4 agents return, synthesize findings into 3 tiers:
+
+```markdown
+## Tier 1: High Impact, Low Risk (implement now)
+- Findings with proven results (papers with measurable improvements)
+- Patterns already working in production elsewhere
+- Internal gaps that are straightforward to fix
+- Changes that don't break existing functionality
+
+## Tier 2: Medium Impact, Medium Risk (implement next version)
+- Findings that require architectural changes
+- Patterns that need adaptation to your workflow
+- Improvements that depend on Tier 1 being complete
+
+## Tier 3: High Impact, High Risk (plan for future)
+- Fundamental architectural changes
+- Patterns that require new infrastructure
+- Research findings that need more validation
+```
+
+### Step 4: Implement With Inline Citations
+
+For every change, add a comment citing the research basis:
+
+```markdown
+> **Research basis (v3.2):** MapCoder (ACL 2024) achieved 93.9% pass@1
+> by feeding the Debugging Agent the original plan alongside buggy code.
+> See: references/research-improvements.md (PLAN-DEBUG-1)
+```
+
+This creates a traceable chain: **inline comment -> reference doc -> original source**.
+
+### Step 5: Create a Reference Document
+
+Create a `research-improvements.md` that indexes all sources:
+
+```markdown
+| ID | Source | Key Finding | Applied In |
+|----|--------|-------------|------------|
+| PLAN-DEBUG-1 | MapCoder (ACL 2024) | Plan-aware debugging: 93.9% pass@1 | fire-debug.md |
+| RECITATION-1 | Manus AI (2025) | Task recitation prevents context drift | fire-loop.md |
+| GAP-1 | Internal analysis | No decision log across phases | DECISION_LOG.md |
+```
+
+---
+
+## Real-World Results: Dominion Flow v3.2
+
+This pattern was used to upgrade Dominion Flow from v3.1 to v3.2:
+
+**Research Phase:**
+- 4 agents ran in parallel (~5 minutes total)
+- Returned 50+ findings across all domains
+- Synthesized into 10 improvements across 3 tiers
+
+**Tier 1 Implemented (same session):**
+
+| Enhancement | Research Source | Impact |
+|-------------|---------------|--------|
+| Task Recitation Pattern | Manus AI (context engineering) | Prevents drift after ~50 tool calls in loops |
+| Plan-Aware Debugging | MapCoder ACL 2024 (93.9% pass@1) | Debugger compares intended vs actual behavior |
+| Decision Log | Internal gap analysis (GAP-1) | Prevents cross-phase decision contradictions |
+| Assumptions Registry | Internal gap analysis (GAP-2) | Phase-gate validation catches stale assumptions |
+| Handoff Completeness Validator | Internal gap analysis (GAP-10) | 17-point checklist prevents broken context chains |
+| Code Comments Standard | User request + best practices | All agent-written code includes maintenance comments |
+
+**Files changed:** 8 files across Dominion Flow
+**Time:** ~2 hours from research launch to full implementation
+**Traceability:** Every change has inline citation -> reference doc -> original source
+
+---
+
+## Testing the Pattern
+
+### How to Verify It Worked
+
+1. **Citation coverage:** Every modified file should have at least one research citation
+2. **Reference doc exists:** `references/research-improvements.md` with full index
+3. **Tier separation:** Changes should be clearly separated into implementation tiers
+4. **No orphan citations:** Every inline citation tag (e.g., GAP-1) exists in the reference doc
+5. **Version bump:** Plugin version reflects the upgrade (e.g., 3.1.0 -> 3.2.0)
+
+### Quality Checks
+
+```bash
+# Verify all citations resolve
+grep -r "See:.*research-improvements" [workflow-files] | \
+  sed 's/.*(\(.*\))/\1/' | sort -u
+# Then check each tag exists in research-improvements.md
+
+# Verify no placeholder text remains
+grep -r "{.*}" [modified-files] | grep -v "^Binary"
+# Should return only intentional template markers
+```
+
+---
+
+## Prevention (Avoiding Stale Workflows)
+
+1. **Schedule quarterly research sweeps** — technology moves fast
+2. **Track Tier 2/3 items** — don't lose future improvements
+3. **Update reference doc** — keep the citation chain intact
+4. **Re-run gap analysis** after major changes — new code creates new gaps
+5. **Version your upgrades** — clear version history for rollback
+
+---
+
+## Common Mistakes to Avoid
+
+- **Implementing everything at once** — Tier separation exists for a reason. Tier 1 first.
+- **Skipping citations** — Without inline comments, nobody knows WHY a change was made. Future agents will undo your work.
+- **Research without synthesis** — 50 raw findings are useless. The synthesis step (Tier sorting) is where value is created.
+- **Ignoring internal gaps** — Agent 4 (gap analysis) often finds the most impactful improvements because they're specific to YOUR workflow.
+- **Not creating the reference doc** — Inline citations without a backing document are dead links.
+- **Changing too many files without testing** — Even documentation changes can break workflows if agents read those docs at runtime.
+
+---
+
+## Related Patterns
+
+- [Breath-Based Parallel Execution](./BREATH_BASED_PARALLEL_EXECUTION.md) — Breath pattern used for agent parallelism
+- [Advanced Orchestration Patterns](./ADVANCED_ORCHESTRATION_PATTERNS.md) — Multi-agent coordination
+- [WARRIOR Workflow Debugging Protocol](./WARRIOR_WORKFLOW_DEBUGGING_PROTOCOL.md) — Debugging with plan context
+
+---
+
+## Resources
+
+- MapCoder (ACL 2024): Multi-Agent Code Generation through Planning
+- Manus AI: Context Engineering for AI Agents (2025)
+- Mason (2026): Judge Agent Separation pattern
+- MIT RLCR (2025): Confidence-Based Escalation
+- SWE-Bench Pro (2025): Single agent + retries vs multi-agent swarms
+- METR Study (2025): AI Impact on Developer Productivity
+- CNCF Four Pillars (2025): Golden Paths, Guardrails, Safety Nets, Manual Review
+- Full citation index: `~/.claude/plugins/dominion-flow/references/research-improvements.md`
+
+---
+
+## Time to Implement
+
+**Research phase:** ~10 minutes (4 parallel agents)
+**Synthesis:** ~15 minutes (read findings, sort into tiers)
+**Tier 1 implementation:** ~2 hours (depends on scope)
+**Total:** ~2.5 hours for a major workflow upgrade
+
+## Difficulty Level
+
+Difficulty: 3/5 — The parallel research pattern is straightforward, but the synthesis step requires judgment about what to implement and in what order. The implementation itself is mostly documentation changes (editing agent instructions, templates, commands) rather than code.
+
+---
+
+**Author Notes:**
+The biggest insight from this pattern: **Agent 4 (internal gap analysis) consistently finds the highest-impact improvements.** External research gives you proven techniques, but the internal analysis tells you exactly WHERE those techniques plug into YOUR specific gaps. Always include both.
+
+The second insight: **inline citations are non-negotiable.** Without them, the next Claude instance has no idea why a section exists and might remove it during a future upgrade. The citation chain (inline -> reference doc -> source) is what makes improvements durable across sessions.
+
+This pattern was first used on Dominion Flow v3.2 (2026-02-10) and produced 5 Tier 1 enhancements in a single session.