@thierrynakoa/fire-flow 10.0.0 → 12.2.1

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

@@ -0,0 +1,212 @@
+---
+name: INTERNAL_CONSISTENCY_AUDIT
+category: methodology
+version: 1.0.0
+contributed: 2026-03-06
+contributor: dominion-flow
+last_updated: 2026-03-06
+tags: [audit, consistency, wiring, cross-reference, versioning, agents, skills]
+difficulty: medium
+sources:
+  - "Dominion Flow v12.0 internal audit — 2026-03-06"
+  - "IEEE 1028 — Software Reviews and Audits"
+---
+
+# Internal Consistency Audit
+
+> **Core insight:** When a multi-agent system evolves across versions, new patterns get wired into core agents but peripheral commands, supporting agents, and documentation drift out of sync. A structured audit catches these gaps before they cause silent failures at runtime.
+
+---
+
+## Problem
+
+After a major version upgrade (e.g., adding 6 new methodology skills), the system can appear complete because the core agents implement the new patterns. But:
+
+- Peripheral commands (e.g., `/fire-autonomous`) may still operate at the old version
+- Supporting agents (e.g., fire-researcher) may not know about new skills that name them
+- Documentation (OVERVIEW) may use different terminology than the implementation
+- Version footers may be stale
+- Interface contracts between agents may have implicit mismatches
+
+These inconsistencies are invisible during normal use because each component works in isolation. They only surface when the full pipeline runs end-to-end.
+
+---
+
+## Solution Pattern
+
+Run a **6-dimension audit** that systematically cross-references every claim against every implementation:
+
+### The Six Audit Dimensions
+
+| Dimension | Question | What It Catches |
+|-----------|----------|-----------------|
+| **A. Skill-Agent Wiring** | Do skills name agents? Do those agents implement the skill? | Orphan skills, unwired patterns |
+| **B. Overview-Agent Consistency** | Does the system map match the territory? | Terminology drift, missing features |
+| **C. Internal Agent Consistency** | Are field names, step numbers, and enumerations correct within each agent? | Broken templates, mismatched counts |
+| **D. Cross-Agent Flow** | Do agents use identical field names when passing data? | Interface contract mismatches |
+| **E. Version Consistency** | Do all files agree on the current version? | Stale version references |
+| **F. Completeness** | What's promised but not implemented? What's implemented but not documented? | Peripheral gaps, missing wiring |
+
+### Audit Protocol
+
+```
+FOR each dimension (A through F):
+  FOR each check in dimension:
+    1. Identify the CLAIM (what the system says it does)
+    2. Identify the EVIDENCE (what the implementation actually does)
+    3. Compare: PASS (match), GAP (missing), CONFLICT (contradicts)
+    4. If GAP or CONFLICT: document specific fix needed
+
+OUTPUT: Table per dimension + summary matrix
+```
+
+---
+
+## Audit Checklist Template
+
+### A. Skill-Agent Wiring
+
+For each new or modified skill:
+
+```
+1. Does the skill have a "When Agents Should Reference" section?
+2. Does it name specific agents?
+3. Do those named agents contain steps implementing the skill's guidance?
+4. Is there a skill that NO agent references? (orphan)
+5. Is there an agent step that uses a concept without citing its source skill? (unwired)
+```
+
+### B. Overview-Agent Consistency
+
+For each feature claimed in the OVERVIEW:
+
+```
+1. Locate the claim (e.g., "Tier 0: Fast Gate")
+2. Find the implementing agent step
+3. Verify terminology matches (same names, same numbering)
+4. Verify behavior matches (same logic, same conditions)
+```
+
+### C. Internal Agent Consistency
+
+For each agent file:
+
+```
+1. Are all new frontmatter fields present in templates?
+2. Do enumerated lists (e.g., "6 stuck types") match their source skill?
+3. Are numeric values (weights, thresholds) consistent with source?
+4. Do conditional gates actually STOP (not just log)?
+5. Are step numbers sequential with no gaps or duplicates?
+```
+
+### D. Cross-Agent Flow
+
+For each data handoff between agents:
+
+```
+1. Planner creates field X → Executor reads field X → same name?
+2. Executor produces output Y → Verifier checks output Y → same format?
+3. Verifier returns verdict Z → routing logic uses verdict Z → same values?
+```
+
+### E. Version Consistency
+
+```
+1. Header version matches?
+2. Footer version matches?
+3. Banner/system map version matches?
+4. version.json matches?
+5. No stale prior-version references in modified files?
+   (Distinguish version PROVENANCE markers like "(v11.2)" from
+    version IDENTITY claims like "Dominion Flow v9.0")
+```
+
+### F. Completeness
+
+```
+1. Do peripheral commands reference new patterns?
+2. Do supporting agents know about new skills that name them?
+3. Are "Future" items tracked explicitly (not silently missing)?
+4. Are there TODO/FIXME/placeholder markers in modified files?
+```
+
+---
+
+## Output Format
+
+### Per-Dimension Table
+
+```markdown
+| Check | Verdict | Evidence | Fix Needed |
+|-------|---------|----------|------------|
+| {check description} | PASS/GAP/CONFLICT | {where you looked, what you found} | {specific action or "None"} |
+```
+
+### Summary Matrix
+
+```markdown
+| Section | PASS | GAP | CONFLICT |
+|---------|------|-----|----------|
+| A. Skill-Agent Wiring | N | N | N |
+| B. Overview-Agent | N | N | N |
+| C. Internal Consistency | N | N | N |
+| D. Cross-Agent Flow | N | N | N |
+| E. Version Consistency | N | N | N |
+| F. Completeness | N | N | N |
+| TOTALS | N | N | N |
+```
+
+### Priority-Ranked Fixes
+
+Sort fixes into three tiers:
+- **Critical:** Breaks runtime behavior or causes silent failures
+- **Important:** Creates user confusion or documentation drift
+- **Minor:** Cosmetic or single-line fixes
+
+---
+
+## When to Use
+
+- After any major version upgrade that adds new skills or agent steps
+- After wiring new patterns into core agents (planner/executor/verifier)
+- Before publishing or releasing a new version
+- When peripheral commands haven't been updated in 2+ versions
+- As a pre-flight check before `/fire-autonomous` runs on a new codebase
+
+## When NOT to Use
+
+- For minor bug fixes that don't change agent architecture
+- For skill-only additions that don't claim agent wiring
+- During active development (wait until the version stabilizes)
+
+---
+
+## Common Findings Pattern
+
+From the v12.0 audit, the most common gap pattern is **core-vs-periphery drift:**
+
+```
+Core agents (planner, executor, verifier) = fully updated
+Peripheral commands (autonomous, discuss) = still at prior version
+Supporting agents (researcher) = unaware of new skills
+Documentation (OVERVIEW) = slightly different terminology
+```
+
+This happens because developers naturally focus on the agents they're actively modifying. The fix pattern is always the same: after updating core agents, grep all commands and supporting agents for the skill names — any that should reference them but don't are gaps.
+
+---
+
+## Related Skills
+
+- [QUALITY_GATES_AND_VERIFICATION](QUALITY_GATES_AND_VERIFICATION.md) — the tiered verification pattern this audit checks for
+- [CIRCUIT_BREAKER_INTELLIGENCE](CIRCUIT_BREAKER_INTELLIGENCE.md) — stuck-state classification this audit cross-references
+- [RELIABILITY_PREDICTION](RELIABILITY_PREDICTION.md) — implied scenario detection this audit verifies
+- [AUTONOMOUS_ORCHESTRATION](AUTONOMOUS_ORCHESTRATION.md) — scope manifests and DORA metrics this audit checks
+- [REQUIREMENTS_DECOMPOSITION](REQUIREMENTS_DECOMPOSITION.md) — utility tree decomposition this audit verifies wiring for
+- [CONTEXT_ROTATION](CONTEXT_ROTATION.md) — articulation protocol this audit cross-references
+
+## References
+
+- First applied: Dominion Flow v12.0 internal consistency audit (2026-03-06)
+- Found: 26 PASS, 7 GAP, 1 CONFLICT across 34 checks
+- Key finding: Core-vs-periphery drift is the dominant gap pattern

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

@@ -0,0 +1,242 @@
+---
+name: LIVE_BREADCRUMB_PROTOCOL
+category: methodology
+description: Automatic breadcrumb trail that makes each Claude instance smarter than the last
+version: 1.0.0
+tags: [reflexion, breadcrumbs, learning, memory, cross-session]
+---
+
+# Live Breadcrumb Protocol — Institutional Memory
+
+Each Claude instance drops breadcrumbs as it works. The next instance reads them and starts smarter. Over time, the project accumulates institutional knowledge that no single session could hold.
+
+> **Military analogy:** After-action reports. Every unit debriefs. The lessons go into doctrine. The next unit deploys with that doctrine baked in — they've never been to that battlefield, but they know what works there.
+
+---
+
+## Architecture
+
+```
+.planning/
+  breadcrumbs/
+    LESSONS.md           ← Living document: solutions that worked (READ FIRST)
+    FAILURES.md          ← What was tried and failed (READ SECOND)
+    PATTERNS.md          ← Project-specific patterns discovered during execution
+    DEPENDENCIES.md      ← Gotchas with specific libraries/versions
+```
+
+### Why 4 files (not 1)
+
+- **LESSONS.md** — "Do this" (positive knowledge, solutions)
+- **FAILURES.md** — "Don't do this" (negative knowledge, dead ends)
+- **PATTERNS.md** — "This is how things work here" (project conventions)
+- **DEPENDENCIES.md** — "Watch out for this" (library/version gotchas)
+
+Separating them lets agents read only what's relevant. A planner needs LESSONS + FAILURES. An executor needs PATTERNS + DEPENDENCIES. A researcher needs all four.
+
+---
+
+## When Breadcrumbs Are Written (Automatic Triggers)
+
+### Trigger 1: After Solving a Non-Trivial Problem (> 2 attempts)
+**Who writes:** fire-executor, fire-debugger → `LESSONS.md`
+```markdown
+### JWT refresh token not persisting
+Root cause: httpOnly cookie not set on response — missing `credentials: 'include'`
+Fix: add `credentials: 'include'` to fetch AND `cors({ credentials: true })` on server
+```
+
+### Trigger 2: After Verification Failure
+**Who writes:** fire-verifier → `FAILURES.md`
+```markdown
+### Phase 2: Custom auth middleware approach FAILED
+Tried: rolling own JWT validation middleware
+Why: race condition on token refresh — 2 concurrent requests both try to refresh
+Don't retry unless: switching to a battle-tested auth library (better-auth, lucia)
+```
+
+### Trigger 3: After Discovering a Project Pattern
+**Who writes:** fire-executor, fire-planner → `PATTERNS.md`
+```markdown
+### API routes use camelCase, not snake_case
+Example: `server/routes/userProgress.js` — `getUserProgress`, not `get_user_progress`
+Breaks: frontend expects camelCase from API responses
+```
+
+### Trigger 4: After Hitting a Dependency Gotcha
+**Who writes:** fire-executor, fire-researcher → `DEPENDENCIES.md`
+```markdown
+### next@15 — cookies() is now async
+Symptom: `cookies()` returns Promise, not CookieStore
+Fix: `const cookieStore = await cookies()` — must await in App Router
+```
+
+**Notice: every example above is 3-4 lines. That's the target.**
+
+---
+
+## When Breadcrumbs Are Read (Automatic Injection)
+
+### On Session Start (via hooks)
+When `/fire-6-resume` or a new session starts on an existing project:
+```
+1. Check if .planning/breadcrumbs/ exists
+2. If yes: Read LESSONS.md (always) + FAILURES.md (always)
+3. Inject as context: "Previous instances learned these lessons..."
+4. PATTERNS.md and DEPENDENCIES.md are read on-demand by agents
+```
+
+### Before Planning (fire-planner, Step 1)
+```
+Read .planning/breadcrumbs/LESSONS.md
+  → "Previous instances found these solutions..."
+Read .planning/breadcrumbs/FAILURES.md
+  → "Previous instances tried these and they FAILED..."
+
+This prevents re-planning with approaches already proven to fail.
+```
+
+### Before Execution (fire-executor, start of each plan)
+```
+Read .planning/breadcrumbs/PATTERNS.md
+  → "This project follows these conventions..."
+Read .planning/breadcrumbs/DEPENDENCIES.md
+  → "Watch out for these library gotchas..."
+```
+
+### During Recovery Research (fire-researcher, recovery mode)
+```
+Read ALL 4 breadcrumb files
+  → "Here's everything previous instances learned about this project"
+  → Cross-reference with FAILURES.md to avoid repeating dead ends
+```
+
+---
+
+## File Templates (Slim — 2-line headers, 3-4 line entries)
+
+### LESSONS.md
+```markdown
+# Lessons — {Project Name}
+> Solutions that worked. Max 20 entries. Merge or archive when full.
+
+### {title}
+Root cause: {why}
+Fix: {what to do}
+```
+
+### FAILURES.md
+```markdown
+# Dead Ends — {Project Name}
+> What failed. If you're about to try something here, STOP.
+
+### {approach that failed}
+Tried: {what}
+Why it failed: {root cause}
+Don't retry unless: {condition}
+```
+
+### PATTERNS.md
+```markdown
+# Patterns — {Project Name}
+> Follow these conventions. Breaks stuff if you don't.
+
+### {pattern name}
+Example: `{file:line}`
+Breaks: {what goes wrong if ignored}
+```
+
+### DEPENDENCIES.md
+```markdown
+# Gotchas — {Project Name}
+> Library-specific traps. Check before debugging weird errors.
+
+### {package}@{version} — {title}
+Symptom: {what you see}
+Fix: {what to do}
+```
+
+---
+
+## Breadcrumb Hygiene
+
+### Size Limits — Breadcrumbs, Not a Loaf
+
+**Hard caps per file:**
+| File | Max entries | Max lines | Entry max |
+|------|-------------|-----------|-----------|
+| LESSONS.md | 20 | 80 lines | 4 lines |
+| FAILURES.md | 15 | 60 lines | 4 lines |
+| PATTERNS.md | 15 | 60 lines | 3 lines |
+| DEPENDENCIES.md | 15 | 60 lines | 4 lines |
+
+**Each breadcrumb is a CRUMB — 3-4 lines max.** If you need more than 4 lines to explain it, you're writing documentation, not a breadcrumb.
+
+**Compact format (use this, not the verbose templates above):**
+```markdown
+### Prisma findMany returns empty on new schema
+Root cause: forgot `npx prisma generate` after schema change
+Fix: always run `prisma generate` after editing schema.prisma
+```
+
+**When a file hits the cap:**
+1. Merge related entries (3 Prisma gotchas → 1 consolidated entry)
+2. Delete entries that are obvious in hindsight (not worth preserving)
+3. Only then archive to `.planning/breadcrumbs/archive/{filename}-{date}.md`
+4. **Never let breadcrumbs exceed the cap** — an agent reading 80+ lines of "lessons" is wasting tokens on context it probably won't use
+
+### Deduplication
+Before writing a breadcrumb, check if a similar one already exists:
+```
+Grep pattern="{key phrase from new breadcrumb}" path=".planning/breadcrumbs/"
+IF match found:
+  → Update existing entry instead of creating duplicate
+  → Add "Confirmed again on {date}" to show it's a recurring pattern
+```
+
+### Quality Check
+Every breadcrumb must have:
+- [ ] A clear **search term** (how would a future instance find this?)
+- [ ] The **root cause** (not just the symptom)
+- [ ] The **solution** or **warning** (actionable, not just descriptive)
+- [ ] A **date** (to know how fresh this knowledge is)
+
+Breadcrumbs without root causes are symptoms — not lessons. Don't write "X broke" without "because Y."
+
+---
+
+## Integration Points
+
+| Agent | Reads | Writes |
+|-------|-------|--------|
+| **fire-planner** | LESSONS.md, FAILURES.md | PATTERNS.md (when discovering conventions during planning) |
+| **fire-executor** | PATTERNS.md, DEPENDENCIES.md | LESSONS.md (after solving problems), PATTERNS.md (after discovering conventions), DEPENDENCIES.md (after hitting gotchas) |
+| **fire-verifier** | — | FAILURES.md (after verification failure) |
+| **fire-researcher** | All 4 files | DEPENDENCIES.md (after discovering version issues) |
+| **fire-debugger** | LESSONS.md, FAILURES.md, DEPENDENCIES.md | LESSONS.md (after resolution), FAILURES.md (for dead ends tried) |
+| **fire-6-resume** | LESSONS.md, FAILURES.md | — (read-only injection) |
+
+---
+
+## The Compounding Effect
+
+```
+Session 1:  Claude knows nothing about the project
+            → Hits 5 problems, solves them
+            → Writes 5 breadcrumbs
+
+Session 2:  Claude reads 5 breadcrumbs
+            → Avoids 3 of those problems entirely
+            → Hits 2 new problems, solves them
+            → Writes 2 new breadcrumbs (total: 7)
+
+Session 3:  Claude reads 7 breadcrumbs
+            → Avoids 5 problems, solves 1 new one
+            → Total: 8 breadcrumbs
+
+Session 10: Claude reads 15+ breadcrumbs
+            → Knows every gotcha, every pattern, every dead end
+            → Executes like a senior developer on the project
+```
+
+Each instance is disposable. The breadcrumbs are permanent. The knowledge compounds.