@thierrynakoa/fire-flow 10.0.0

package/commands/fire-reflect.md

@@ -0,0 +1,235 @@
+# /fire-reflect
+
+> Capture, search, and review failure reflections. Reflexion-style self-reflection for cross-session learning.
+
+---
+
+## Purpose
+
+After any failure (debug resolution, test failure, approach rotation, stalled loop), capture **what was tried, why it failed, and what actually worked** as a persistent reflection. Future sessions search these before investigating.
+
+**Research basis:** Reflexion (NeurIPS 2023) — 91% pass@1 via verbal self-reflection stored as linguistic memory.
+
+---
+
+## Arguments
+
+```yaml
+arguments:
+  action:
+    required: false
+    type: string
+    description: "Action to perform: capture (default), search, list, review"
+    example: "/fire-reflect capture"
+
+optional_flags:
+  --from debug: "Auto-extract from most recent resolved debug session"
+  --from session: "Extract from current session context"
+  --project <name>: "Tag with project name"
+  --severity <level>: "minor | moderate | critical (default: moderate)"
+  --search <query>: "Search reflections by keyword/symptom"
+```
+
+---
+
+## Process
+
+### Step 1: Determine Action
+
+```
+IF args contain "search" or --search:
+  → Go to Search Mode (Step 5)
+IF args contain "list":
+  → Go to List Mode (Step 6)
+IF args contain "review":
+  → Go to Review Mode (Step 7)
+ELSE:
+  → Capture Mode (Step 2)
+```
+
+### Step 2: Gather Reflection Content
+
+**If `--from debug`:**
+- Read most recent file in `.planning/debug/resolved/`
+- Extract: symptoms, eliminated hypotheses, root cause, fix applied
+- Auto-fill reflection fields
+
+**If `--from session`:**
+- Review current conversation context
+- Identify: failed approaches, what was tried, what worked
+- Auto-fill reflection fields
+
+**If interactive (default):**
+Ask using AskUserQuestion:
+
+1. **What was the problem?** — Brief symptom description
+2. **What did you try that failed?** — Each approach and why it didn't work
+3. **What actually worked?** — The solution that resolved it
+4. **The lesson** — One-sentence takeaway for future self
+5. **Search triggers** — When should future agents find this?
+
+### Step 3: Generate Reflection File
+
+Create file at `~/.claude/reflections/{date}_{slug}.md`:
+
+```markdown
+---
+type: reflection
+date: {YYYY-MM-DD}
+project: {project-name}
+trigger: debug-resolution | test-failure | approach-rotation | stalled-loop
+severity: minor | moderate | critical
+tags: [{technology}, {pattern}, {symptom}]
+---
+# What I tried and why it failed
+
+## The Problem
+{Brief description of symptoms — what went wrong, what was observed}
+
+## What I Tried (and why each failed)
+1. **{Approach 1}** — {Why it didn't work. What was the evidence?}
+2. **{Approach 2}** — {Why it didn't work. What disproved it?}
+
+## What Actually Worked
+{The solution. Be specific — include the code pattern, command, or insight.}
+
+## The Lesson
+{One-sentence takeaway. This is what a future agent reads first.}
+
+## Future Self: Search For This When
+- {Symptom 1 that should trigger finding this reflection}
+- {Symptom 2}
+- {Error message pattern}
+```
+
+### Step 4: Save and Confirm
+
+```
+Save to: ~/.claude/reflections/{date}_{slug}.md
+
+Display:
++----------------------------------------------------------------------+
+| REFLECTION CAPTURED                                                   |
++----------------------------------------------------------------------+
+|                                                                      |
+|  File: ~/.claude/reflections/{date}_{slug}.md                        |
+|  Project: {project}                                                  |
+|  Severity: {severity}                                                |
+|  Tags: {tags}                                                        |
+|                                                                      |
+|  Lesson: {one-sentence lesson}                                       |
+|                                                                      |
+|  This reflection will be searchable via:                             |
+|    /fire-remember "{symptom}" --type reflection                     |
+|    /fire-reflect --search "{keyword}"                               |
+|                                                                      |
++----------------------------------------------------------------------+
+```
+
+### Step 5: Search Mode
+
+When called with `--search` or `search` action:
+
+```
+1. Search ~/.claude/reflections/ for matching files
+2. Use keyword matching on: tags, problem description, lesson, search triggers
+3. If vector memory available:
+   /fire-remember "{query}" --type reflection
+4. Display matching reflections ranked by relevance
+
+Output:
+  1. [{date}] {slug} — Severity: {severity}
+     Lesson: {one-sentence lesson}
+     Tags: {tags}
+     Match: {what matched}
+
+  2. ...
+```
+
+### Step 6: List Mode
+
+```
+List all reflections sorted by date (newest first):
+
+  # | Date       | Project     | Severity | Lesson
+  1 | 2026-02-20 | voice-bridge | critical | VK codes stable, char corrupted by Ctrl
+  2 | 2026-02-19 | dominion-flow   | moderate | ...
+  ...
+
+  Total: {N} reflections across {M} projects
+```
+
+### Step 7: Review Mode
+
+Read a specific reflection and display it formatted:
+
+```
+/fire-reflect review {slug-or-number}
+```
+
+---
+
+## Auto-Trigger Integration
+
+Reflections are auto-generated by other commands:
+
+| Trigger | Command | When |
+|---------|---------|------|
+| Debug resolution | `/fire-debug` Step 7.5 | After root cause found and fix verified |
+| Stalled loop | `/fire-loop` Step 9 | On STALLED → SPINNING transition |
+| Approach rotation | `/fire-loop` Step 9 | On SPINNING state (forced rotation) |
+
+Auto-generated reflections use `--from debug` or `--from session` to extract context automatically.
+
+---
+
+## Pre-Investigation Search
+
+Before starting any debug or complex task, search reflections:
+
+```
+Search reflections for: "[error symptoms]"
+If match found with relevant lesson:
+  "I've encountered this before — {lesson}. Applying directly instead of re-investigating."
+```
+
+This is wired into:
+- `/fire-debug` Step 2.5 — Search before investigating
+- `/fire-loop` iteration start — Check for known failure patterns
+
+---
+
+## Reflection Quality Guidelines
+
+**Good reflection:**
+- Specific symptoms (error messages, behaviors)
+- Multiple failed approaches with reasons
+- Concrete solution (code, command, config change)
+- One-sentence lesson that's useful without context
+- Search triggers that match how you'd describe the problem
+
+**Bad reflection:**
+- Vague ("something was wrong")
+- Only records the solution without the journey
+- No search triggers
+- Lesson is too abstract ("be more careful")
+
+---
+
+## Success Criteria
+
+- [ ] Reflection file created with all sections filled
+- [ ] Tags extracted from problem domain
+- [ ] Severity classified correctly
+- [ ] Search triggers are realistic symptom descriptions
+- [ ] Lesson is a single actionable sentence
+- [ ] File saved to `~/.claude/reflections/`
+
+---
+
+## References
+
+- **Research:** Reflexion (NeurIPS 2023) — verbal self-reflection, 91% pass@1
+- **Storage:** `~/.claude/reflections/` — searchable via vector memory
+- **Index:** Qdrant sourceType: `reflection` — auto-indexed by your-memory-repo
+- **Related:** `/fire-debug`, `/fire-loop`, `/fire-remember`

package/commands/fire-research.md

@@ -0,0 +1,246 @@
+# /fire-research
+
+> Daily AI research-to-upgrade pipeline — search papers, score findings, implement in waves
+
+---
+
+## Purpose
+
+Systematic daily workflow for finding, evaluating, and implementing AI research improvements into dominion-flow. Eliminates the need to explain the process each session — any fresh agent follows this pipeline autonomously.
+
+**Proven track record:** 7 successful executions (v3.2 through v8.0), producing 70+ implemented enhancements from 200+ papers analyzed.
+
+---
+
+## Arguments
+
+```yaml
+arguments:
+  focus:
+    required: false
+    type: string
+    description: "Research focus area (e.g., 'memory consolidation', 'failure taxonomy')"
+    example: "/fire-research agent confidence calibration"
+
+optional_flags:
+  --scan-only: "Research and score papers but don't implement (reconnaissance mode)"
+  --from-deferred: "Start from deferred candidates of last version"
+  --quick: "Single agent search instead of parallel (faster, less thorough)"
+```
+
+---
+
+## Process
+
+### Step 1: Load the Research Pipeline Skill
+
+Read the full methodology skill — it contains scoring matrices, wave templates, and citation formats refined across 7 versions:
+
+```
+@skills-library/methodology/RESEARCH_BACKED_WORKFLOW_UPGRADE.md
+```
+
+**This is MANDATORY.** The skill contains the paper scoring matrix, gap taxonomy, wave grouping rules, and citation format. Do not skip.
+
+### Step 2: Determine Focus Area
+
+**If arguments provided:** Use as focus area directly.
+
+**If `--from-deferred`:** Check MEMORY.md and recent handoffs for deferred candidates:
+```bash
+cd ~/.claude/memory
+npm run search -- "deferred candidate" --type handoff --limit 5
+```
+
+**If no arguments:** Ask user:
+
+```
+What area should we research today?
+
+Recent deferred candidates from previous versions:
+1. [List from memory search]
+2. [List from memory search]
+
+Or describe a new focus area:
+> [User input]
+```
+
+### Step 3: Launch Parallel Research Agents
+
+Launch 3-4 agents in a SINGLE message for true parallelism:
+
+```
+Agent 1: Academic Papers (arXiv, ACL, NeurIPS, ICML, ICLR — 2024-2026)
+  - Search: "[focus area] AI agent 2025 2026"
+  - Extract per paper: title, venue, date, key finding, measurable result,
+    how it maps to our workflow, specific file/step it would modify
+  - Return: Top 15 papers ranked by APPLICABILITY
+
+Agent 2: Community Patterns + Industry Tools
+  - Search: Manus AI, Replit Agent, Cursor, Devin, SWE-Agent, Claude Code
+  - Focus: What do production AI coding tools do that we don't?
+  - Return: Top 10 patterns with source links
+
+Agent 3: Internal Gap Analysis (Explore subagent)
+  - Read: All workflow files in the dominion-flow plugin directory
+  - Classify each gap: MEMORY | REFLECTION | PLANNING | ACTION | SYSTEM
+  - Return: Top 10 gaps ranked by impact
+
+Agent 4 (optional): Failure Pattern Mining
+  - Search Qdrant: debug_resolution + failure_pattern source types
+  - Find recurring failures indicating systemic gaps
+  - Return: Top 5 failure patterns
+```
+
+### Step 4: Score Papers With Matrix
+
+When agents return, evaluate each finding:
+
+| Criterion | Weight | Scoring |
+|-----------|--------|---------|
+| Recency | 15% | 2026=5, 2025=4, 2024=3, older=1 |
+| Measurable Results | 25% | Has numbers=5, qualitative=3, none=1 |
+| Applicability | 30% | Maps to specific file=5, general=3, tangential=1 |
+| Novelty | 15% | Don't do this at all=5, partial=3, already done=0 |
+| Implementation Cost | 15% | <10 lines=5, <50 lines=3, architectural=1 |
+
+**Threshold:** Score < 3.0 = deferred. Score > 4.0 = Wave 1.
+
+Present scored results to user:
+
+```
+=============================================================
+            RESEARCH RESULTS — [Focus Area]
+=============================================================
+
+Papers/Patterns Analyzed: [N]
+Above threshold (≥3.0): [N]
+Wave 1 candidates (≥4.0): [N]
+
+-------------------------------------------------------------
+TOP FINDINGS (sorted by score)
+-------------------------------------------------------------
+
+1. [Paper Name] ([Venue] [Year]) — Score: 4.7
+   Finding: [key result]
+   Maps to: [specific file/step]
+
+2. [Paper Name] ([Venue] [Year]) — Score: 4.3
+   ...
+
+-------------------------------------------------------------
+INTERNAL GAPS (from Agent 3)
+-------------------------------------------------------------
+
+1. [GAP-MEMORY] [description] — Score: 4.5
+2. [GAP-PLANNING] [description] — Score: 3.8
+
+-------------------------------------------------------------
+DEFERRED (< 3.0, tracked for next version)
+-------------------------------------------------------------
+
+- [Paper] — Score: 2.7 — Reason: [why deferred]
+
+=============================================================
+```
+
+**If `--scan-only`:** Stop here. Save findings to handoff.
+
+### Step 5: Group Into Waves
+
+Not tiers (priority) — WAVES (dependency order):
+
+```
+Wave 1: Foundation (no dependencies)
+  - [changes that can be implemented immediately]
+
+Wave 2: Intelligence (builds on Wave 1)
+  - [logic that USES Wave 1 structures]
+
+Wave 3: Decision (builds on Wave 2)
+  - [higher-order patterns integrating Wave 1+2]
+```
+
+Confirm wave plan with user before implementing.
+
+### Step 6: Implement Wave by Wave
+
+For each wave:
+1. Implement changes with inline citations:
+   ```
+   > **Research basis (vX.Y):** [Paper] ([Venue] [Year]) — [finding].
+   > Applied: [what changed and why].
+   ```
+2. Verify wave works before starting next
+3. Track deferred candidates
+
+### Step 7: Post-Implementation
+
+After all waves complete:
+
+- [ ] **Version bump** — Update plugin version (semver minor for additions)
+- [ ] **Generate report** — Save to `~/Documents/Claude Reports/`
+- [ ] **Index into Qdrant** — `cd your-memory-repo && npm run index`
+- [ ] **Update MEMORY.md** — Add concise entry with paper count, changes, key insight
+- [ ] **Track deferred** — Add to handoff for next session's `/fire-research --from-deferred`
+
+### Completion Display
+
+```
+=============================================================
+            FIRE RESEARCH COMPLETE
+=============================================================
+
+Version: [old] → [new]
+Papers Analyzed: [N] from [N] parallel agents
+Findings Above Threshold: [N]
+Changes Implemented: [N] across [N] waves
+
+-------------------------------------------------------------
+WAVE SUMMARY
+-------------------------------------------------------------
+
+Wave 1: [N] changes — [brief description]
+Wave 2: [N] changes — [brief description]
+
+Files Modified: [N]
+Key Insight: [one sentence]
+
+-------------------------------------------------------------
+DEFERRED TO NEXT VERSION
+-------------------------------------------------------------
+
+- [paper/pattern] — [reason]
+
+-------------------------------------------------------------
+NEXT STEPS
+-------------------------------------------------------------
+
+-> Run `/fire-4-verify` to validate changes
+-> Run `/fire-5-handoff` to save session state
+-> Tomorrow: `/fire-research --from-deferred`
+
+=============================================================
+```
+
+---
+
+## Success Criteria
+
+- [ ] Research pipeline skill loaded
+- [ ] Focus area determined (from args, deferred, or user)
+- [ ] 3-4 parallel research agents launched
+- [ ] Papers scored with 5-criterion matrix
+- [ ] Findings grouped into dependency-ordered waves
+- [ ] Each change has inline research citation
+- [ ] Deferred candidates tracked
+- [ ] Version bumped, report generated, memory indexed
+
+---
+
+## Related Commands
+
+- `/fire-search` — Search existing skills library
+- `/fire-add-new-skill` — Contribute individual skill from session
+- `/fire-4-verify` — Verify changes after implementation
+- `/fire-5-handoff` — Save session state with deferred candidates