@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/commands/fire-research.md

@@ -1,12 +1,12 @@
 # /fire-research
 
-> Daily AI research-to-upgrade pipeline — search papers, score findings, implement in waves
+> Daily AI research-to-upgrade pipeline — search papers, score findings, implement in breaths
 
 ---
 
 ## Purpose
 
-Systematic daily workflow for finding, evaluating, and implementing AI research improvements into fire-flow. Eliminates the need to explain the process each session — any fresh agent follows this pipeline autonomously.
+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.
 
@@ -82,7 +82,7 @@ Agent 2: Community Patterns + Industry Tools
   - Return: Top 10 patterns with source links
 
 Agent 3: Internal Gap Analysis (Explore subagent)
-  - Read: All workflow files in the fire-flow plugin directory
+  - 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
 
@@ -104,7 +104,7 @@ When agents return, evaluate each finding:
 | 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.
+**Threshold:** Score < 3.0 = deferred. Score > 4.0 = Breath 1.
 
 Present scored results to user:
 
@@ -115,7 +115,7 @@ Present scored results to user:
 
 Papers/Patterns Analyzed: [N]
 Above threshold (≥3.0): [N]
-Wave 1 candidates (≥4.0): [N]
+Breath 1 candidates (≥4.0): [N]
 
 -------------------------------------------------------------
 TOP FINDINGS (sorted by score)
@@ -146,34 +146,153 @@ DEFERRED (< 3.0, tracked for next version)
 
 **If `--scan-only`:** Stop here. Save findings to handoff.
 
-### Step 5: Group Into Waves
+### Step 5: Group Into Breaths
 
-Not tiers (priority) — WAVES (dependency order):
+Not tiers (priority) — BREATHS (dependency order):
 
 ```
-Wave 1: Foundation (no dependencies)
+Breath 1: Foundation (no dependencies)
   - [changes that can be implemented immediately]
 
-Wave 2: Intelligence (builds on Wave 1)
-  - [logic that USES Wave 1 structures]
+Breath 2: Intelligence (builds on Breath 1)
+  - [logic that USES Breath 1 structures]
 
-Wave 3: Decision (builds on Wave 2)
-  - [higher-order patterns integrating Wave 1+2]
+Breath 3: Decision (builds on Breath 2)
+  - [higher-order patterns integrating Breath 1+2]
 ```
 
-Confirm wave plan with user before implementing.
+Confirm breath plan with user before implementing.
 
-### Step 6: Implement Wave by Wave
+### Step 6: Implement Breath by Breath
 
 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 6.5: Review-Fix Loop (v13.0 — Automated Quality Gate)
+
+> **Principle:** Implementation without review is speculation. After each breath, spawn
+> reviewer subagents that test with all available tools. Fix findings. Loop until clean
+> or circuit breaker trips.
+
+```
+FOR each completed breath:
+
+  // ─── SPAWN REVIEWER SUBAGENTS ───────────────────────────
+  Launch 2 parallel reviewer agents (code-reviewer subagent_type):
+
+  Reviewer A: Implementation Correctness
+    - Read ALL files modified in this breath
+    - Grep for inline citations — verify every change has one
+    - Check that new patterns don't contradict existing patterns
+    - Verify cross-references (step numbers, file paths) are correct
+    - Test: Run any available linters, type checks, or test suites
+    - Return: structured findings list with severity (CRITICAL/IMPORTANT/MINOR)
+
+  Reviewer B: Integration & Consistency
+    - Read the MULTI_AGENT_COORDINATION.md skill (or relevant skill)
+    - Cross-check: do command files (fire-3-execute, fire-executor)
+      match what the skill document says?
+    - Check for naming collisions, taxonomy conflicts, missing mappings
+    - Verify: new steps have correct numbering (no duplicates, no gaps)
+    - Return: structured findings list with severity
+
+  // ─── COLLECT & CLASSIFY FINDINGS ────────────────────────
+  findings = merge(Reviewer_A.findings, Reviewer_B.findings)
+
+  critical_count = count(findings WHERE severity == CRITICAL)
+  important_count = count(findings WHERE severity == IMPORTANT)
+  minor_count = count(findings WHERE severity == MINOR)
+
+  Display:
+    "Breath {N} Review Results:"
+    "  CRITICAL: {critical_count}"
+    "  IMPORTANT: {important_count}"
+    "  MINOR: {minor_count}"
+
+  // ─── FIX-LOOP WITH CIRCUIT BREAKER ──────────────────────
+  fix_attempt = 0
+  max_fix_attempts = 3
+  accumulated_weight = 0.0
+
+  WHILE (critical_count > 0 OR important_count > 0) AND fix_attempt < max_fix_attempts:
+    fix_attempt += 1
+
+    Display: "  Fix attempt {fix_attempt}/{max_fix_attempts}..."
+
+    // Apply fixes for all CRITICAL findings first, then IMPORTANT
+    FOR each finding in findings WHERE severity IN (CRITICAL, IMPORTANT):
+      Apply fix
+      Log: "Fixed: {finding.summary}"
+
+    // Re-run reviewers on modified files only
+    Re-launch Reviewer A + B on changed files
+    findings = merge(new findings)
+
+    critical_count = count(findings WHERE severity == CRITICAL)
+    important_count = count(findings WHERE severity == IMPORTANT)
+
+    // Circuit breaker weight tracking
+    accumulated_weight += (critical_count * 1.0) + (important_count * 0.5)
+
+    IF accumulated_weight > 5.0:
+      Display: "  Circuit breaker: accumulated weight {accumulated_weight} > 5.0"
+      Display: "  Classifying stuck state..."
+      GOTO dead_end_check
+
+  // ─── EXIT CONDITIONS ────────────────────────────────────
+  IF critical_count == 0 AND important_count == 0:
+    Display: "  Breath {N}: CLEAN — all findings resolved in {fix_attempt} attempts"
+    // MINOR findings logged but don't block progression
+    IF minor_count > 0:
+      Display: "  {minor_count} MINOR findings logged (non-blocking)"
+    PROCEED to next breath
+
+  IF fix_attempt >= max_fix_attempts AND (critical_count > 0 OR important_count > 0):
+    GOTO dead_end_check
+
+  // ─── DEAD-END CHECK (Circuit Breaker Escape) ────────────
+  dead_end_check:
+    Classify stuck type:
+      FIXATION:  Same findings reappear after fix → context rotation needed
+      LOGIC:     Fixes introduce NEW critical findings → approach is wrong
+      ARCHITECTURE: Findings point to structural issue → escalate to planner
+
+    MATCH stuck_type:
+      FIXATION:
+        Display: "  FIXATION detected — same issues recurring."
+        Display: "  Shelving {count} unresolved findings as known gaps."
+        Log findings to breath report as DEFERRED_FIXES
+        PROCEED to next breath (don't block pipeline)
+
+      LOGIC:
+        Display: "  LOGIC error — fixes creating new problems."
+        Display: "  Rolling back breath {N} changes and re-implementing."
+        IF already_rolled_back_once:
+          Tag as DEAD_END, skip breath, PROCEED
+        ELSE:
+          already_rolled_back_once = true
+          GOTO Step 6 for this breath (re-implement with reviewer feedback)
+
+      ARCHITECTURE:
+        Display: "  ARCHITECTURE issue — structural problem detected."
+        Display: "  STOPPING review loop. Manual intervention needed."
+        Display: "  Run /fire-debug to investigate, or /fire-2-plan --gaps"
+        STOP (do not proceed to next breath)
+```
+
+**Key design decisions:**
+- **2 reviewers, not 1** — Correctness and consistency are independent concerns
+- **Max 3 fix attempts** — Prevents infinite loops (Dominion Flow circuit breaker pattern)
+- **Weight-based circuit breaker** — Critical findings weigh more than important ones
+- **Dead-end classification** — Uses the stuck-state taxonomy from CIRCUIT_BREAKER_INTELLIGENCE.md
+- **MINOR findings don't block** — Only CRITICAL and IMPORTANT require fixes
+- **FIXATION allows progression** — If fixes keep recurring, log them and move on (pipeline > perfection)
+- **ARCHITECTURE stops the pipeline** — Structural issues can't be fixed by retry
+
 ### Step 7: Post-Implementation
 
 After all waves complete:
@@ -194,14 +313,14 @@ After all waves complete:
 Version: [old] → [new]
 Papers Analyzed: [N] from [N] parallel agents
 Findings Above Threshold: [N]
-Changes Implemented: [N] across [N] waves
+Changes Implemented: [N] across [N] breaths
 
 -------------------------------------------------------------
-WAVE SUMMARY
+BREATH SUMMARY
 -------------------------------------------------------------
 
-Wave 1: [N] changes — [brief description]
-Wave 2: [N] changes — [brief description]
+Breath 1: [N] changes — [brief description]
+Breath 2: [N] changes — [brief description]
 
 Files Modified: [N]
 Key Insight: [one sentence]
@@ -231,8 +350,10 @@ NEXT STEPS
 - [ ] 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
+- [ ] Findings grouped into dependency-ordered breaths
 - [ ] Each change has inline research citation
+- [ ] Review-fix loop ran on each wave (Step 6.5)
+- [ ] All CRITICAL/IMPORTANT findings resolved or classified as dead-ends
 - [ ] Deferred candidates tracked
 - [ ] Version bumped, report generated, memory indexed