@thierrynakoa/fire-flow 12.2.1 → 13.0.1

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

@@ -0,0 +1,140 @@
+---
+name: REVIEW_BACKTRACK_PANEL
+category: methodology
+description: Show all collected answers before any writes; let the user edit any answer before committing
+version: 1.0.0
+tags: [wizard, review-panel, undo, multi-step, commit-before-verify, devin-pattern]
+---
+
+# Review & Backtrack Panel
+
+## Problem
+
+A multi-step wizard collects 5-7 answers across steps, then immediately generates output.
+The user realizes in step 4 that their step 2 answer was wrong. By the time they see
+the generated output, reverting requires deleting files, undoing barrel exports, and
+re-running from scratch.
+
+**Commit-before-verify anti-pattern:** Acting on collected input before giving the
+user a chance to review all answers together.
+
+## Solution
+
+Add a Review Panel step **before any file writes or irreversible actions**. The panel:
+
+1. Displays all collected answers in one view
+2. Shows `[Edit]` next to each answer
+3. Requires explicit confirmation before proceeding
+4. If user edits → return to that step, collect new answer, re-display panel
+
+```markdown
+### Step N.5: Review All Answers
+
+REVIEW PANEL
+══════════════════════════════════════════════════════════
+  {Step 1 label}:    {answer}    [Edit]
+  {Step 2 label}:    {answer}    [Edit]
+  {Step 3 label}:    {answer}    [Edit]
+  {Step 4 label}:    {answer}    [Edit]
+══════════════════════════════════════════════════════════
+
+[✓ Proceed]   [Edit a section]   [Cancel]
+```
+
+## Rules
+
+1. **Always before writes** — The panel must appear before ANY file is created,
+   modified, or any external action taken. Not after.
+2. **Edit returns to that step** — Editing step 2 goes back to step 2, collects
+   a new answer, then re-displays the full panel. Does not restart from step 1.
+3. **Show ALL answers** — Even the ones the user didn't explicitly confirm. If it
+   was collected as input, it appears in the panel.
+4. **Not a confirmation dialog** — This is a structured summary, not "Are you sure Y/N?"
+   The structure lets users catch errors they didn't know they made.
+
+## Implementation Examples
+
+### fire-add-new-skill.md Step 5.5
+
+```markdown
+### Step 5.5: Review & Edit All Answers
+
+Before running security scan or saving the skill, display collected answers:
+
+SKILL REVIEW PANEL
+══════════════════════════════════════════════════════════
+  Problem:      {summary of step 1 answer}    [Edit]
+  Category:     {selection}                   [Edit]
+  Scope:        {general/project}             [Edit]
+  Name:         {skill name}                  [Edit]
+  Solution:     {summary of pattern}          [Edit]
+  Code:         {yes/no}                      [Edit]
+══════════════════════════════════════════════════════════
+[✓ Run security scan + save]  [Edit a section]  [Cancel]
+```
+
+### fire-scaffold.md Step 5.5
+
+```markdown
+STEP 5.5 of 6 — Preview
+
+FILES TO CREATE:
+  {output-path}/{Name}.{ext}           ← main file
+  {output-path}/{Name}.test.{ext}      ← test file
+
+SKELETON PREVIEW:
+  {First 20 lines of generated content}
+
+[✓ Generate these files]  [Edit a previous answer]  [Cancel]
+```
+
+### fire-setup.md Step 7 (Review & Save)
+
+```markdown
+DEVELOPER PROFILE REVIEW
+══════════════════════════════════════════════════════════
+  Frontend:     {selection}    [Edit]
+  Backend:      {selection}    [Edit]
+  Database:     {selection}    [Edit]
+  ...
+══════════════════════════════════════════════════════════
+[✓ Save profile]   [Edit a section]   [Cancel]
+```
+
+## When to Skip
+
+**Do NOT add a review panel for:**
+- Commands with only 1-2 inputs (trivial to re-run)
+- Commands where all steps are reversible (can undo any step freely)
+- Read-only commands (nothing is written)
+
+**DO add a review panel for:**
+- Wizards with 4+ collection steps
+- Any wizard that writes files
+- Any wizard that modifies existing files (barrel exports, route registrations)
+- Onboarding wizards that write profile/config files
+
+## Measurable Impact
+
+**Devin Interactive Planning** (score 89/100 in wizard creation research): Showing
+what will be created BEFORE consuming resources. The preview/review step maps directly
+to Devin's plan approval gate — users approve the plan, then execution happens.
+
+**"No Hardware, No Problem"** (ACM C&C 2025): Pre-generation simulation dramatically
+improves user confidence and reduces post-generation correction rate.
+
+**UX principle:** Decisions made in a sequential wizard feel isolated. Seeing all
+decisions together in one panel reveals inconsistencies the user couldn't detect
+across 6 separate steps.
+
+## Research Basis
+
+> **Devin Interactive Planning** (score 89/100) — Show what will be created BEFORE
+> consuming resources. Plan approval gate prevents costly generation errors.
+>
+> **"No Hardware, No Problem"** (ACM C&C 2025) — Pre-generation simulation improves
+> confidence and reduces post-generation correction rate.
+>
+> Applied: Step 5.5 (Review & Edit All Answers) added to fire-add-new-skill.md;
+> Step 5.5 (Preview Before Generating) added to fire-scaffold.md;
+> Step 7 (Review & Save) in fire-setup.md in v12.3.

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

@@ -0,0 +1,117 @@
+---
+name: review-fix-loop
+category: methodology
+version: 1.0.0
+contributed: 2026-03-08
+contributor: dominion-flow
+last_updated: 2026-03-08
+tags: [review, subagent, circuit-breaker, quality-gate, fix-loop, multi-agent]
+difficulty: hard
+---
+
+# Review-Fix Loop — Automated Subagent Quality Gate
+
+## Problem
+
+After implementing changes (research findings, feature code, refactors), there's no automated quality gate. Errors ship silently because:
+- The implementing agent has blind spots from its own context
+- Manual review is slow and inconsistent
+- Without structured feedback, the same mistakes recur across sessions
+- No circuit breaker prevents infinite fix-review cycles
+
+## Solution Pattern
+
+Spawn parallel reviewer subagents after each implementation breath. Collect findings, classify by severity, fix in a loop with circuit breaker escapes. The pattern separates concerns (correctness vs consistency) across independent reviewers, uses weight-based stuck detection, and maps dead-end types to specific interventions.
+
+```
+FOR each completed breath:
+
+  1. SPAWN 2+ parallel reviewer agents (code-reviewer subagent_type)
+     - Reviewer A: Implementation Correctness (linting, tests, citations)
+     - Reviewer B: Integration & Consistency (cross-file, naming, numbering)
+
+  2. COLLECT findings, classify severity: CRITICAL / IMPORTANT / MINOR
+
+  3. FIX-LOOP (max 3 attempts, weight-based circuit breaker):
+     - Fix all CRITICAL first, then IMPORTANT
+     - Re-run reviewers on changed files only
+     - Track accumulated_weight: CRITICAL=1.0, IMPORTANT=0.5
+     - IF weight > 5.0: classify stuck state and escape
+
+  4. EXIT CONDITIONS:
+     - CLEAN: all CRITICAL+IMPORTANT resolved → proceed
+     - FIXATION: same findings recur → log as deferred, proceed
+     - LOGIC: fixes create new problems → rollback once, retry
+     - ARCHITECTURE: structural issue → stop pipeline, escalate
+```
+
+## Implementation Steps
+
+1. After completing a unit of work (breath, wave, phase), identify all modified files
+2. Launch 2+ reviewer agents in a SINGLE message for true parallelism
+3. Each reviewer returns structured findings: `{severity, summary, file, line}`
+4. Merge findings, display counts by severity
+5. Enter fix loop — apply fixes, re-review, track circuit breaker weight
+6. On clean exit, proceed. On dead-end, classify and route appropriately
+
+## When to Use
+
+- After implementing research findings (`/fire-research` Step 6.5)
+- After any multi-file implementation where cross-file consistency matters
+- When changes touch coordination protocols (naming, taxonomies, step numbering)
+- After porting code between projects (ministry-lms porting pattern)
+- Any time you want automated quality validation before moving to the next task
+
+## When NOT to Use
+
+- Single-line fixes or trivial changes (overhead exceeds benefit)
+- When the change is already covered by existing test suites with high coverage
+- During exploratory/research phases where code isn't being committed
+- When circuit breaker has already tripped on this exact scope (don't re-enter)
+
+## Must Do
+
+- Separate reviewers by concern (correctness vs consistency)
+- Use severity classification — MINOR findings NEVER block progression
+- Track accumulated weight across fix attempts (not just attempt count)
+- Classify dead-end type BEFORE choosing intervention
+- Re-run reviewers on CHANGED FILES ONLY (not full codebase)
+
+## Must Not Do
+
+- Do not let MINOR findings block the pipeline
+- Do not retry more than 3 times without dead-end classification
+- Do not use a single reviewer for both correctness and consistency
+- Do not skip the circuit breaker — infinite fix loops waste tokens
+- Do not rollback more than once for LOGIC errors (tag as DEAD_END on second attempt)
+
+## Common Mistakes
+
+- Using a single "general review" agent instead of separating concerns
+- Treating all findings equally (no severity classification)
+- No escape mechanism — the loop runs forever burning tokens
+- Fixing MINOR issues while CRITICAL ones remain
+- Re-reviewing the entire codebase instead of just changed files
+
+## Proven Results
+
+First use (v13.0 multi-agent coordination, 2026-03-08):
+- 3 parallel code-reviewer agents spawned
+- 18 findings collected (7 critical, 9 important, 2 informational)
+- 11 fixes applied in one pass
+- Caught: TRANSIENT naming collision, missing SWARM awareness in executor,
+  broken JSON fences, unspecified DAG reorder, verdict arbitration gaps
+
+## Related Skills
+
+- [CIRCUIT_BREAKER_INTELLIGENCE](./CIRCUIT_BREAKER_INTELLIGENCE.md) — stuck-state classification feeds dead-end routing
+- [MULTI_AGENT_COORDINATION](./MULTI_AGENT_COORDINATION.md) — structured envelope and cascade prevention
+- [CONTEXT_ROTATION](./CONTEXT_ROTATION.md) — fresh-eyes pattern for FIXATION-type dead-ends
+- [SELF_TESTING_FEEDBACK_LOOP](./SELF_TESTING_FEEDBACK_LOOP.md) — related self-validation pattern
+
+## References
+
+- Dominion Flow v13.0 — first implementation in `/fire-research` Step 6.5
+- biome `handler.rs` — catch_unwind isolation pattern (MIT)
+- oxc `service.rs` — cumulative warning thresholds (MIT)
+- Contributed from: dominion-flow internal session 2026-03-08

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

@@ -0,0 +1,155 @@
+---
+name: Voting-Based Verdict Arbitration
+category: methodology
+version: 1.0.0
+contributed: 2026-03-12
+contributor: fire-research
+last_updated: 2026-03-13
+tags: [multi-agent, voting, conflict-resolution, code-review, verification, arbitration]
+difficulty: medium
+---
+
+# Voting-Based Verdict Arbitration — Independent Votes Over Weighted Averages
+
+> (ACL 2025) — voting improves reasoning tasks by 13.2%, consensus improves knowledge by 2.8%.
+> uv PubGrub `priority.rs` — weighted scoring + fork strategy for conflict resolution.
+
+## Problem
+
+When multiple reviewers (human or AI) evaluate the same work, they often disagree. The naive approach is weighted averaging: verifier gets 60%, reviewer gets 40%, combine scores. This collapses independent perspectives into a single number, losing the signal that comes from disagreement patterns. Weighted averages also create false precision — a 71% combined score PASSES while 69% FAILS, despite being within noise.
+
+## Solution Pattern
+
+Replace weighted scoring with independent voting when multiple perspectives are available:
+
+### Vote Types
+```
+PASS        — No blocking issues found
+SOFT_BLOCK  — Concerns but not critical, can proceed with TODOs
+HARD_BLOCK  — Critical issue, must fix before proceeding
+```
+
+### Resolution Rules
+```
+IF hard_block_votes >= 2:
+  → BLOCK (multiple independent perspectives see critical issues)
+
+ELIF pass_votes > (soft_block_votes + hard_block_votes):
+  → PASS (majority passes, log soft_block items as TODOs)
+
+ELSE:
+  → NEEDS_REVIEW (no clear majority — requires deeper analysis)
+```
+
+### When to Use Voting vs. Weighted Scoring
+
+| Scenario | Method | Why |
+|----------|--------|-----|
+| 3+ independent reviewers | **Voting** | Preserves independence |
+| 2 reviewers (verifier + reviewer) | **Weighted** | Not enough votes for majority |
+| Single reviewer with confidence | **Threshold** | No votes to tally |
+| Reasoning task (correctness) | **Voting** | +13.2% improvement (ACL 2025) |
+| Knowledge task (factual) | **Consensus** | +2.8% improvement (ACL 2025) |
+
+## Code Example
+
+```python
+# Before — weighted scoring (collapses perspectives)
+def resolve_conflict(verifier_conf, reviewer_conf):
+    combined = (verifier_conf * 0.6) + (reviewer_conf * 0.4)
+    return "PASS" if combined > 70 else "FAIL"
+
+# After — independent voting (preserves perspectives)
+def resolve_conflict(persona_verdicts: list[str]):
+    hard_blocks = sum(1 for v in persona_verdicts if v == "HARD_BLOCK")
+    passes = sum(1 for v in persona_verdicts if v == "PASS")
+    total = len(persona_verdicts)
+
+    if hard_blocks >= 2:
+        return "BLOCK"
+    elif passes > (total - passes):
+        return "PASS"
+    else:
+        return "NEEDS_REVIEW"
+```
+
+## Implementation Steps
+
+1. Collect independent verdicts from each reviewer/persona (don't let them see each other's votes)
+2. Extract vote type from each verdict (map severity of findings to PASS/SOFT_BLOCK/HARD_BLOCK)
+3. Tally votes by type
+4. Apply resolution rules
+5. Log vote breakdown for performance tracking
+
+## Conflict Type Classification
+
+Before voting, classify the conflict — not all disagreements need votes:
+
+```
+SCOPE conflict: Verifier checks functionality, reviewer checks quality
+  → Both can be right. Apply BOTH sets of fixes. No vote needed.
+
+SEVERITY conflict: One says PASS, another says BLOCK
+  → Use voting protocol (this is where voting shines)
+
+CONTRADICTION: One says "add X", another says "remove X"
+  → Fork resolution — try both approaches, verify each, pick winner
+```
+
+## Fallback
+
+If fewer than 3 independent perspectives are available, fall back to weighted resolution:
+```
+verifier_weight = 0.6  (functional correctness is primary)
+reviewer_weight = 0.4  (code quality is secondary)
+```
+
+Voting requires sufficient independent perspectives to be statistically meaningful.
+
+## Conflict History Tracking
+
+Track which personas frequently conflict:
+```
+After 3+ conflicts from same persona IN CURRENT PHASE:
+  → Deprioritize that persona's BLOCK votes (weight 0.2)
+  → Reset at start of each new phase
+  → A persona wrong in Phase 2 may be right in Phase 5
+```
+
+## When to Use
+
+- Multi-reviewer code review with 3+ independent perspectives
+- Verifier/reviewer disagreements in automated pipelines
+- Any decision requiring synthesis of independent evaluations
+- AI-assisted review where multiple "personas" evaluate the same work
+
+## When NOT to Use
+
+- Binary decisions with clear right/wrong answers
+- Fewer than 3 independent voters (use weighted scoring instead)
+- When voters have vastly different expertise levels (weight by expertise, don't vote)
+- Trivial decisions where the overhead exceeds the benefit
+
+## Must Do
+
+- Keep votes independent — don't share one voter's verdict before others vote
+- Log vote breakdowns for trend analysis
+- Track conflict frequency per persona for calibration
+
+## Must Not Do
+
+- Do not collapse votes into a weighted average (defeats the purpose)
+- Do not let one HARD_BLOCK veto when it's the only one (require 2+)
+- Do not use voting for factual/knowledge queries (consensus is better per ACL 2025)
+
+## Related Skills
+
+- [MULTI_AGENT_COORDINATION](./MULTI_AGENT_COORDINATION.md) — § Verdict Arbitration Protocol
+- [OBSERVATION_MASKING](./OBSERVATION_MASKING.md) — reduces noise before voting
+- [AUTO_REVIEWER_SUBAGENT](./AUTO_REVIEWER_SUBAGENT.md) — generates the reviewer verdicts
+
+## References
+
+- "LLM Voting: Understanding When It Helps and When It Doesn't" — ACL 2025
+- uv PubGrub `priority.rs` — weighted scoring + fork strategy
+- Wired into: `fire-3-execute.md` Step 8.5 Merge Gate

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

@@ -21,7 +21,7 @@ Reference skill for `/fire-1a-new` Step 4b. After VISION.md is locked, Claude re
 3. Run installations in dependency order (framework → database → services → tooling)
 4. Verify each install succeeded (version check or health check)
 5. Log results to `.planning/TOOLING-LOG.md`
-6. If any install fails, log to breadcrumbs `FAILURES.md` and suggest alternative
+6. If any install fails, log the failure and suggest alternative
 
 ---
 
@@ -249,7 +249,7 @@ If a CLI install fails:
 
 1. Check if it's a network issue (retry once)
 2. Check if it's a version conflict (try `--legacy-peer-deps`)
-3. Log the failure to `.planning/breadcrumbs/FAILURES.md`
+3. Log the failure to `.planning/TOOLING-LOG.md`
 4. Suggest manual install command to the user
 5. Continue with remaining installations (don't block on one failure)
 

package/skills-library/_general/methodology/dead-code-activation.md

@@ -0,0 +1,123 @@
+---
+name: dead-code-activation
+category: methodology
+version: 1.0.0
+contributed: 2026-03-12
+contributor: dominion-flow
+last_updated: 2026-03-12
+contributors:
+  - dominion-flow
+tags: [methodology, dead-code, activation, gap-analysis, wiring, upgrade]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Dead Code Activation
+
+## Problem
+
+Large codebases accumulate **documented-but-unwired features** — code, configs, or documentation that describe capabilities which were never connected to the execution path. These features were designed, sometimes even partially implemented, but never called from the main flow. They sit dormant, invisible to users and agents.
+
+This is distinct from unused code (which should be deleted). Dead code activation targets **valuable features that SHOULD be active** but aren't — often because the implementer documented the feature in one file but forgot to wire it into the calling code.
+
+**Symptoms:**
+- Documentation describes a feature that doesn't seem to work
+- Config files define options that have no effect
+- Helper functions exist but are never imported or called
+- README mentions capabilities that aren't accessible
+- Version history says "added X" but X has no entry point
+
+## Solution Pattern
+
+**Systematic grep-trace-wire cycle:**
+
+1. **Grep for references** — Find all mentions of the feature across docs, configs, and code
+2. **Trace the call path** — Follow from entry point (CLI, API, UI) to where the feature should be invoked
+3. **Identify the gap** — Find where the call chain breaks (the feature is defined but never called)
+4. **Wire it in** — Add the missing import/call/registration at the gap point
+5. **Verify end-to-end** — Confirm the feature is now reachable from its intended entry point
+
+### Why This Is the Highest-Impact Upgrade Pattern
+
+Across 4+ consecutive Dominion Flow versions, internal gap analysis consistently scored higher than external research papers. The reason: **activation cost is near-zero** (the feature already exists) while **impact is immediate** (a fully-designed feature goes live). By contrast, implementing a paper requires design, coding, testing, and documentation from scratch.
+
+```
+Cost/Impact Matrix:
+                    Low Cost    High Cost
+High Impact     →  [ACTIVATE]   [Implement paper]
+Low Impact      →  [Skip]       [Definitely skip]
+```
+
+## Code Example
+
+```javascript
+// Example: Error classification was documented but never wired into execution
+
+// File: docs/error-classification.md (EXISTS — documented)
+// "Classify errors into 5 health states: GREEN, YELLOW, ORANGE, RED, BLACK"
+
+// File: agents/fire-executor.md (GAP — no step calls classifier)
+// Step 3 → Step 4 → Step 5 ... error-classification never referenced
+
+// File: references/error-classification.md (EXISTS — full schema defined)
+// { GREEN: "all passing", YELLOW: "warnings", ... }
+
+// FIX: Wire classifier into executor between Step 3 and Step 4
+// Added Step 3.6: Health State Classification
+// "After task execution, classify result using error-classification.md schema"
+// "Route: GREEN→continue, YELLOW→log+continue, ORANGE→retry, RED→escalate"
+```
+
+## Implementation Steps
+
+1. **Run gap analysis** — Search for features mentioned in docs/configs but not in execution code:
+   ```bash
+   # Find features documented but never imported/called
+   grep -r "feature-name" docs/ config/ --include="*.md" --include="*.json"
+   grep -r "feature-name" src/ --include="*.ts" --include="*.js"
+   # If docs have references but src doesn't → dead code candidate
+   ```
+
+2. **Map the intended call path** — Read the documentation to understand WHERE the feature was meant to be invoked
+
+3. **Find the break point** — Trace from entry point to feature; identify the missing link
+
+4. **Add the wire** — Usually 1-10 lines: an import, a function call, a step reference, or a config registration
+
+5. **Test the activated feature** — Run the entry point and verify the feature now executes
+
+6. **Score the activation** — Rate by impact (how much value it adds) and risk (how much it could break)
+
+## When to Use
+
+- Starting a new version/upgrade cycle — scan for dead code before writing new features
+- After a gap analysis reveals documented-but-unwired capabilities
+- When documentation mentions features that users can't access
+- When config files define options that have no observable effect
+- When you need high-impact improvements with minimal implementation risk
+
+## When NOT to Use
+
+- The "dead code" is genuinely unused and should be deleted (no documentation, no design intent)
+- The feature was intentionally deferred (check git blame for "TODO" or "deferred" comments)
+- The feature requires dependencies that aren't installed (activation would cause import errors)
+- The code is experimental/prototype quality — needs redesign, not just wiring
+
+## Common Mistakes
+
+- **Activating without understanding** — Wire in a feature you don't fully understand; it breaks something downstream
+- **Confusing dead code with deprecated code** — Deprecated features were turned OFF intentionally; don't re-enable them
+- **Not verifying end-to-end** — Wiring the import but not testing the full path from entry to execution
+- **Skipping the gap analysis** — Jumping to implementation of new features when existing dead features would solve the same problem
+
+## Related Skills
+
+- [INTERNAL_CONSISTENCY_AUDIT](../methodology/INTERNAL_CONSISTENCY_AUDIT.md) — Finds contradictions between documentation and code
+- [REVIEW_BACKTRACK_PANEL](../methodology/REVIEW_BACKTRACK_PANEL.md) — Review step for catching missed activations
+
+## References
+
+- Dominion Flow v10.0-v12.6: Internal gap analysis consistently scored equal to or higher than academic papers
+- Pattern confirmed across 4 consecutive versions with 20+ activations
+- Contributed from: dominion-flow plugin (2026-03-12)