@thierrynakoa/fire-flow 10.0.0 → 12.2.1

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

@@ -0,0 +1,251 @@
+---
+name: PHOENIX_REBUILD_METHODOLOGY
+category: methodology
+version: 1.0.0
+contributed: 2026-03-06
+contributor: dominion-flow
+last_updated: 2026-03-06
+tags: [phoenix, rebuild, refactor, intent-extraction, vibe-code, technical-debt, reverse-engineering]
+difficulty: hard
+sources:
+  - "Fred Brooks — No Silver Bullet (1986) — Essential vs Accidental Complexity"
+  - "Martin Fowler — Refactoring: Improving the Design of Existing Code"
+  - "Michael Feathers — Working Effectively with Legacy Code"
+  - "Refactoring.Guru — Design Pattern Catalog"
+---
+
+# Phoenix Rebuild Methodology
+
+> **Core insight:** Don't refactor the mess — reverse-engineer the INTENT, then build clean from scratch. A phoenix burns the old and rises new. The ashes carry the knowledge; the new form carries none of the accidental complexity.
+
+---
+
+## 1. How to Extract Intent from Messy Code
+
+### Reading Order (Critical — Do NOT Read Code First)
+
+```
+1. README / docs          → What the developer SAID the app does
+2. Route / endpoint files → The API surface reveals feature boundaries
+3. Database schema/models → The data model reveals domain concepts
+4. Tests (if any)         → Tests encode intended behavior
+5. Git commit messages    → The narrative of how the code evolved
+6. The code itself        → LAST — read implementation after you understand intent
+```
+
+**Why this order:** Reading code first biases toward "what it does" instead of "what it was meant to do." Surrounding artifacts reveal intent more clearly than tangled implementation.
+
+### Intent Extraction Patterns
+
+| Pattern | What to Look For | What It Reveals |
+|---------|-----------------|-----------------|
+| **Naming Intent** | Function/variable names vs their behavior | Gap between name and behavior = accidental complexity |
+| **Comment Intent** | Comments saying "should", "TODO", "HACK", "FIXME" | Unfulfilled intent — developer knew what they wanted |
+| **Test Intent** | What tests assert (if tests exist) | The behaviors the developer cared about verifying |
+| **Error Handling Intent** | What errors are caught vs thrown | What the developer thought could go wrong |
+| **Commit Message Intent** | "fix:", "feat:", "hack:" prefixes | The sequence of intentions over time |
+| **Dead Code Intent** | Commented-out code, unreachable branches | Abandoned attempts — replaced or forgotten? |
+| **Copy-Paste Intent** | Duplicated blocks with minor variations | "I needed this to work like THAT but slightly different" |
+| **Magic Number Intent** | Hardcoded values with no explanation | A business rule or config never extracted |
+| **Import Intent** | Imported but unused libraries | Features planned but never implemented |
+| **Overengineering Intent** | Complex abstractions wrapping simple logic | Developer anticipated needs that never materialized |
+
+### The "Squint Test"
+
+For any module, ask: **"If I squint past the implementation mess, what is this module's job in ONE sentence?"**
+
+If you cannot answer in one sentence, the module violates Single Responsibility and should be split during rebuild. The squint test produces the "intent statement" for each feature.
+
+---
+
+## 2. Accidental vs Essential Complexity (Fred Brooks)
+
+### Essential Complexity — Keep and Rewrite Clean
+
+Complexity inherent to the PROBLEM itself. Cannot be removed without changing what the application does.
+
+**Examples:**
+- Tax calculation rules (complex because taxes are complex)
+- Multi-currency arithmetic (complex because currencies are complex)
+- Role-based permissions with inheritance (complex because access control is nuanced)
+- Content repurposing logic (complex because each platform has different format requirements)
+
+**During rebuild:** Preserve ALL essential complexity. Rewrite it cleaner, add tests, add comments — but do NOT simplify away the business rules.
+
+### Accidental Complexity — Remove Entirely
+
+Complexity introduced by the IMPLEMENTATION, not the problem. CAN and SHOULD be eliminated.
+
+**Detection heuristics:**
+```
+IF removing the pattern changes WHAT the app does    → ESSENTIAL (keep)
+IF removing the pattern only changes HOW it does it  → ACCIDENTAL (remove)
+IF the pattern exists because "that's how the tutorial did it" → ACCIDENTAL
+IF the pattern exists because "the business rule requires it" → ESSENTIAL
+IF the pattern appears in "common anti-patterns" lists → likely ACCIDENTAL
+```
+
+**Common accidental complexity indicators:**
+- Global state mutations instead of state management
+- Callback nesting instead of async/await
+- Raw SQL strings instead of parameterized queries / ORM
+- No separation between routes, business logic, and data access
+- Duplicated code instead of shared functions
+- Inconsistent error handling (some try/catch, some not)
+- No type safety (everything is `any`)
+- Hardcoded configuration values
+- No environment separation (dev/staging/prod)
+
+---
+
+## 3. Edge Case Preservation Protocol
+
+### The 5-Step Protocol
+
+Every edge case in the original code must be:
+
+```
+1. IDENTIFIED  — Found in the code (conditional branches, special cases)
+2. DOCUMENTED  — Recorded in INTENT.md with WHY it exists
+3. CLASSIFIED  — Is this edge case still needed in the rebuild?
+4. CARRIED     — If needed, it MUST appear in the rebuild BLUEPRINT
+5. VERIFIED    — The rebuilt project must handle this edge case (test it)
+```
+
+### Where Edge Cases Hide (Top 10 Locations)
+
+```
+ 1. if/else branches with non-obvious conditions
+ 2. try/catch blocks with specific error type handling
+ 3. Database query filters with multiple conditions
+ 4. Validation rules with specific ranges or patterns
+ 5. Timeout/retry logic
+ 6. Date/time/timezone handling
+ 7. Currency/precision arithmetic (rounding rules)
+ 8. Null/undefined guards (especially nested: user?.profile?.settings?.theme)
+ 9. Migration/compatibility code (backwards compat shims)
+10. Feature flags / A/B test branches
+```
+
+### Kill or Keep Decision Framework
+
+```
+KEEP if:
+  - It handles a real business scenario (even rare ones)
+  - It prevents data corruption or data loss
+  - It handles an external API quirk (rate limits, format variations)
+  - It was added in response to a bug report (check git blame)
+  - Removing it would change user-visible behavior
+
+KILL if:
+  - It handles a bug in code that is being rewritten anyway
+  - It works around a library limitation that no longer exists
+  - It exists because of poor architecture (which the rebuild fixes)
+  - It is dead code (no execution path reaches it)
+  - It was a temporary hack with a TODO to remove
+```
+
+---
+
+## 4. Vibe-Coder Anti-Pattern Replacement Map
+
+| Anti-Pattern | Detection Signal | Production Replacement |
+|-------------|-----------------|----------------------|
+| **God File** | Single file > 500 LOC with mixed concerns | Split by responsibility: routes, services, models, utils |
+| **Copy-Paste Variation** | Near-identical blocks (>80% similar) | Extract shared function with parameters for variations |
+| **Callback Hell** | Nested callbacks > 3 levels deep | async/await with proper error handling |
+| **Global State Spaghetti** | `global`, `window.`, module-level mutation | State management (Redux, Zustand, Context) or DI |
+| **No Error Handling** | No try/catch, uncaught promise rejections | Error middleware + typed error classes + logging |
+| **Inline Everything** | SQL in route handlers, HTML in logic | Layered architecture: controller → service → repository |
+| **Magic Strings/Numbers** | Hardcoded values throughout | Named constants, enums, config files |
+| **No Types** | `any` everywhere, no interfaces | TypeScript strict mode with proper type definitions |
+| **No Tests** | Zero test files | Test-first rebuild (write tests from INTENT.md before code) |
+| **Security Ignorance** | Hardcoded secrets, no input validation, raw SQL | .env, validation schemas, parameterized queries, auth middleware |
+| **No Config Separation** | URLs, ports, keys mixed in code | Environment-specific config with validation |
+| **Monolith Route File** | All routes in one file | Route module per resource with controller pattern |
+
+---
+
+## 5. The Intent Graph
+
+A three-column mapping that serves as the translation layer between messy source and clean target:
+
+```
+CODE (what exists)  →  INTENT (what was meant)  →  CLEAN (what to build)
+```
+
+### Why the Intent Graph Matters
+
+It prevents two failure modes:
+
+**Failure Mode 1: Literal Translation**
+Rebuilding the mess exactly as it is, just with better formatting. The intent graph forces you to go THROUGH intent, not directly from code to code.
+
+**Failure Mode 2: Intent Loss**
+Rebuilding something clean but missing features because the developer's hidden knowledge was not extracted. The graph forces you to document every code pattern before discarding it.
+
+### Building the Intent Graph
+
+```
+FOR each source code module:
+  1. Read the code → document WHAT it does (observable behavior)
+  2. Read surrounding context → document WHY (intent)
+  3. Look up best practice → document HOW to do it right
+  4. Record all three columns in INTENT-GRAPH.md
+  5. Cross-check: does the "clean" column preserve all behaviors
+     from the "code" column? If not, something was lost.
+```
+
+### Example Intent Graph Entries
+
+| Source Code (Messy) | Developer Intent | Clean Implementation |
+|---------------------|-----------------|---------------------|
+| 200-line auth middleware with inline SQL | Role-based access control | passport.js + RBAC middleware + DB-backed roles |
+| Global error handler that catches everything | Don't crash the app | Express error middleware + typed error classes + Sentry |
+| 15 API routes in one file | CRUD for users + products + orders | Separate route modules + controller layer + service layer |
+| Hardcoded `PORT=3000` in 5 files | Environment-specific config | dotenv + typed config loader + validation |
+| Copy-pasted validation in every route | Input validation | Zod/Joi schema per endpoint, shared validation middleware |
+| `setTimeout(fn, 5000)` retry loops | Handle transient API failures | Exponential backoff utility with configurable retries |
+| `if (user.role === 'admin' \|\| user.id === 1)` | Admin access + superuser bypass | RBAC with permissions table + superuser flag in DB |
+
+---
+
+## 6. Rebuild Order Strategy
+
+When rebuilding from INTENT.md, build in this order:
+
+```
+1. FOUNDATION     — Project scaffold, config, types, database schema
+2. CORE           — Highest-uniqueness features (CRITICAL and HIGH)
+3. SUPPORT        — Medium-uniqueness features
+4. STANDARD       — Low-uniqueness and boilerplate (often auto-generated)
+5. INTEGRATION    — Wire everything together, cross-module flows
+6. HARDENING      — Error handling, logging, security, edge cases
+7. TESTING        — Tests written from INTENT.md assertions
+8. DOCUMENTATION  — README, API docs, deployment guide
+```
+
+**Rationale:** Build what is UNIQUE first. Boilerplate is easiest to add later and lowest risk. If context runs out, you want the unique business logic done, not the boilerplate. This is the opposite of how vibe coders build (scaffold first, unique logic last — which is why their unique logic is always the messiest part).
+
+---
+
+## 7. Feature Uniqueness Classification
+
+| Score | Definition | Rebuild Strategy |
+|-------|-----------|-----------------|
+| **BOILERPLATE** | Standard framework code, no custom logic | Regenerate from best practices (don't even read the original) |
+| **LOW** | Minor customization of standard patterns | Use standard pattern, apply customizations from INTENT.md |
+| **MEDIUM** | Meaningful business logic using common patterns | Rewrite with proper architecture, preserve all business rules |
+| **HIGH** | Custom algorithms, domain-specific rules | Carefully extract logic, rewrite with tests, preserve edge cases |
+| **CRITICAL** | Core business differentiator, proprietary logic | Extract verbatim, wrap in clean architecture, comprehensive tests |
+
+---
+
+## When Agents Should Reference This Skill
+
+- **fire-phoenix-analyst:** Primary reference — use reading order, intent extraction patterns, squint test, uniqueness classification
+- **fire-phoenix (command):** Reference rebuild order strategy when creating phase breakdown from INTENT.md
+- **fire-planner:** When planning rebuild phases, use uniqueness scores to prioritize task order
+- **fire-executor:** When rebuilding modules, check anti-pattern map to avoid reintroducing accidental complexity
+- **fire-verifier:** When verifying rebuild, check that accidental complexity items are absent and edge cases are preserved
+- **fire-researcher:** When researching alternatives for a stuck rebuild, check intent graph for original intent

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

@@ -0,0 +1,157 @@
+---
+name: QUALITY_GATES_AND_VERIFICATION
+category: methodology
+description: Industry-proven verification patterns — tiered gates, risk-based testing, error budgets, shift-left, and the 7 principles of testing applied to AI-assisted development
+version: 1.0.0
+tags: [quality-gates, verification, testing, risk-based-testing, error-budget, shift-left]
+sources:
+  - "Google SRE — Error Budget Policy (sre.google)"
+  - "Netflix — Kayenta Automated Canary Analysis"
+  - "SonarSource, Dynatrace, LinearB — Quality Gate frameworks"
+  - "Hans-Petter Halvorsen — Software Development: A Practical Approach"
+  - "ISTQB — 7 Principles of Testing"
+  - "CRISP-ML(Q) — Phase-level risk registers"
+---
+
+# Quality Gates and Verification
+
+> **Core insight:** A gate that halts progress is working correctly. Distinguish between "agent failed" and "gate blocked advancement pending better input."
+
+---
+
+## 1. Tiered Verification (Shift-Left)
+
+Structure verification as two tiers — never run expensive checks when cheap ones already fail:
+
+### Tier 1: Fast Gate (seconds, always run)
+- Syntax validation / linting
+- File existence checks
+- Schema conformance
+- Import resolution
+- Type checking (if applicable)
+
+### Tier 2: Slow Gate (minutes, run only when Tier 1 passes)
+- Integration tests
+- End-to-end validation
+- Performance benchmarks
+- Security scans
+- Cross-phase contract verification
+
+**Why:** A build that doesn't compile will never pass integration tests. Running integration tests on broken syntax wastes tokens and time.
+
+**Agent action:** fire-verifier should run Tier 1 checks first. If any fail, report immediately without running Tier 2. This alone can save 50%+ of verification time on failed phases.
+
+---
+
+## 2. Risk-Based Testing
+
+Test scope is a function of two variables:
+
+```
+Test Priority = Likelihood of Failure × Impact of Failure
+```
+
+| Quadrant | Likelihood | Impact | Strategy |
+|----------|-----------|--------|----------|
+| **Test first, test most** | High | High | Full verification, manual review |
+| **Test thoroughly** | Low | High | Targeted deep tests |
+| **Test efficiently** | High | Low | Automated regression |
+| **Sample or defer** | Low | Low | Spot check, trust |
+
+**Agent action:** Before verification, classify each changed area by this matrix. Don't test everything equally — that's wasteful. Don't skip testing on "small changes" — that's dangerous.
+
+### Change Impact Scoping
+```
+Config-only change    → verify config loads, skip code tests
+Backend-only change   → verify API + DB, skip frontend/E2E
+Frontend-only change  → verify rendering + UX, skip backend
+Full-stack change     → full verification
+Test-only change      → verify tests pass, minimal code review
+```
+
+---
+
+## 3. Error Budget for Retry Decisions
+
+Borrowed from Google SRE: every task has a finite retry budget.
+
+```
+Task error budget = max_retries (default: 2)
+
+After each retry:
+  budget -= 1
+
+  IF budget == 0:
+    STOP retrying
+    Route to: research → re-plan → or escalate
+
+  NEVER: retry the same approach a 3rd time
+```
+
+**Why this works:** An agent that retries the same failing approach 5 times is burning tokens, not solving problems. Two retries catches transient failures. Beyond that, the approach itself is wrong.
+
+**Integration with circuit breaker:** The error budget is the per-task trip threshold. When exhausted, the task-level breaker opens and routes to research.
+
+---
+
+## 4. The 7 Principles of Testing (Applied to AI Development)
+
+From ISTQB, adapted for AI-agent workflows:
+
+| Principle | Original | AI-Agent Translation |
+|-----------|----------|---------------------|
+| **1. Testing shows presence of bugs** | Testing reduces probability of undiscovered defects but isn't proof of correctness | Verification catches issues but passing doesn't guarantee production-ready |
+| **2. Exhaustive testing is impossible** | Test based on risk assessment, not completeness | Scope verification to change impact, don't verify everything |
+| **3. Early testing** | Start testing as early as possible | Verify plan coherence before execution, not after |
+| **4. Defect clustering** | A small number of modules contain most bugs | Track which phases/tasks cluster failures — invest guards there |
+| **5. Pesticide paradox** | Same tests stop finding new bugs | Rotate verification approaches; static checklist misses novel failures |
+| **6. Testing is context-dependent** | Different software needs different testing | Backend change ≠ frontend change ≠ config change → different checks |
+| **7. Absence of error is a fallacy** | Bug-free software can still be unusable | Code that passes all checks but doesn't meet user requirements is still wrong |
+
+---
+
+## 5. Phase-Level Risk Registers (CRISP-ML(Q))
+
+Before each major phase, generate a short risk assessment:
+
+```markdown
+## Phase {N} Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| {most likely failure mode} | {H/M/L} | {H/M/L} | {specific action} |
+| {second most likely} | {H/M/L} | {H/M/L} | {specific action} |
+| {third most likely} | {H/M/L} | {H/M/L} | {specific action} |
+```
+
+**This is 5 lines, not a document.** The point is to think about failure before executing, not to create paperwork.
+
+---
+
+## 6. Definition of Ready / Definition of Done
+
+Two gates that prevent wasted work:
+
+### Definition of Ready (before starting a task)
+- [ ] Acceptance criteria are clear and verifiable
+- [ ] Dependencies are resolved or documented
+- [ ] Scope is bounded (files, tools, operations)
+- [ ] Required context is available (MEMORY.md, prior phase output)
+
+### Definition of Done (before declaring complete)
+- [ ] All Tier 1 checks pass
+- [ ] Tier 2 checks pass (if applicable to scope)
+- [ ] No regressions introduced
+- [ ] RECORD.md updated with what was done
+- [ ] Agent confidence ≥ 70% on the output
+
+**Rule:** If DoR isn't met, send the task back for clarification — don't start it. If DoD isn't met, the task is not done — don't advance.
+
+---
+
+## When Agents Should Reference This Skill
+
+- **fire-verifier:** Apply tiered verification (Tier 1 before Tier 2), risk-based scoping
+- **fire-planner:** Include risk register in plan output, define DoR/DoD per task
+- **fire-executor:** Check DoR before starting, track error budget per task
+- **fire-autonomous:** Use error budget to decide retry vs. escalate

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

@@ -0,0 +1,104 @@
+---
+name: RELIABILITY_PREDICTION
+category: methodology
+description: Predict phase reliability before execution using implied scenario detection, sensitivity analysis, and constrained models — catch architectural mismatches before they cost tokens
+version: 1.0.0
+tags: [reliability, prediction, implied-scenarios, sensitivity-analysis, quality-gates]
+sources:
+  - "Rodrigues, Rosenblum, Uchitel — Reliability Prediction in Model-Driven Development (UCL/Imperial, 2005)"
+  - "CRISP-ML(Q) — Mercedes-Benz AG + TU Berlin, 2020"
+---
+
+# Reliability Prediction for AI-Assisted Development
+
+> **Core insight:** "Composition reveals what specification omits." When you connect agents, phases, or tools together, the system produces behaviors no individual specification predicted. Detect these early or pay later.
+
+---
+
+## 1. Two Risk Dimensions Per Phase
+
+Every phase has two independent failure probabilities — assess both before executing:
+
+| Dimension | Question | Example |
+|-----------|----------|---------|
+| **Transition probability** | If this phase succeeds, does it cleanly advance to the next? | "Auth phase done, but API routes phase expects a different token format" |
+| **Component reliability** | What's the probability this agent/tool produces correct output? | "LLM generating boilerplate = 95% reliable. LLM designing novel algorithm = 60% reliable" |
+
+**Agent action:** Before executing a task, estimate both. If component reliability < 60%, research first. If transition probability is unclear, verify the interface contract with the next phase.
+
+---
+
+## 2. Implied Scenario Detection
+
+After any multi-agent or multi-phase interaction, check for unspecified behaviors:
+
+### Positive Implied Scenarios (missing specification)
+- The system produced a correct behavior not in the plan
+- **Action:** Add it to the phase spec. Document it in PATTERNS.md
+- Example: "The auth middleware also handles rate limiting — not planned, but correct and useful"
+
+### Negative Implied Scenarios (architecture mismatch)
+- The system permits behavior the specification forbids
+- **Action:** Add a constraint (validation gate, type check, pre-condition) — don't patch the agent
+- Example: "The executor can write to files outside the declared scope — add scope enforcement"
+
+> **Key finding:** Adding a single constraint improved system reliability from 64.9% to 86.2% in the source study. Constraints beat corrections.
+
+---
+
+## 3. Sensitivity Analysis — Where to Invest Guards
+
+Not all phase failures are equal. Rank by **downstream impact**, not frequency:
+
+```
+For each phase that has ever failed:
+  1. Fix that phase's reliability to 0% (assume it fails)
+  2. Estimate: how many downstream phases break?
+  3. Estimate: what's the rework cost?
+  4. Rank phases by total downstream damage
+
+Result: The phase with the highest damage multiplier
+        gets the most verification investment
+```
+
+**Common surprise:** The rarest failure with the highest downstream cost should get the most guard investment. A planning failure that happens 5% of the time but invalidates 3 downstream phases is worse than an execution failure that happens 20% of the time but is locally contained.
+
+---
+
+## 4. Probability Completeness
+
+Every decision diamond must have exhaustive branches. No implicit "otherwise":
+
+```
+BAD:  "If verification passes → proceed to handoff"
+      (What happens if it fails? Undefined.)
+
+GOOD: "If verification passes → proceed to handoff
+       If verification fails with fixable issues → re-execute with gaps
+       If verification fails with architectural issues → re-plan
+       If verification fails 3 times → dead-end shelf + escalate"
+```
+
+**Rule:** If the branches from a decision point don't cover 100% of outcomes, the workflow has a structural defect.
+
+---
+
+## 5. Early Non-Functional Analysis
+
+> "Early evaluation of software properties is important in order to reduce costs before resources have been allocated and decisions have been made."
+
+The highest-leverage phase is **planning** — not because planning is intrinsically valuable, but because:
+- Defect caught in planning = 1 iteration to fix
+- Same defect caught in execution = 5 iterations
+- Caught in production = indefinitely more
+
+**Agent action:** Before executing, verify the plan's non-functional properties: Is the architecture coherent? Are the dependencies resolvable? Is the scope verifiable? These questions cost 30 seconds to check and save hours of rework.
+
+---
+
+## When Agents Should Reference This Skill
+
+- **fire-planner:** Before generating a plan, assess transition probabilities between phases
+- **fire-verifier:** After verification, run implied scenario check on multi-agent outputs
+- **fire-executor:** Before starting a task with < 60% component reliability, route to research
+- **fire-researcher:** When analyzing why a phase failed, use sensitivity analysis to prioritize

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

@@ -0,0 +1,155 @@
+---
+name: REQUIREMENTS_DECOMPOSITION
+category: methodology
+description: Turn vague requirements into testable specifications using utility trees, ATAM tradeoff analysis, and weighted decision matrices — never accept Level 1 input for execution
+version: 1.0.0
+tags: [requirements, decomposition, utility-tree, atam, weighted-decision-matrix, tradeoffs]
+sources:
+  - "CMU SEI — How to Address Poorly-Defined Requirements in Software System Design (Nov 2025)"
+  - "Dr. Lori Flynn, Lyndsi Hughes — Carnegie Mellon University Software Engineering Institute"
+  - "IEEE — Software Quality Definition"
+  - "ATAM — Architecture Tradeoff Analysis Method"
+---
+
+# Requirements Decomposition
+
+> **Core insight:** "Never accept a vague requirement as input to any agent task — always decompose to Level 4 before beginning execution." A requirement you can't test is a requirement you can't verify.
+
+---
+
+## 1. The Four-Level Decomposition (Utility Tree)
+
+Every requirement must be drilled from vague to testable:
+
+```
+Level 1: Quality Attribute (vague)
+  "Good security"
+
+Level 2: Sub-factors (decomposed concerns)
+  Data Protection, Auth, Security Logging, Compliance
+
+Level 3: Refined Sub-factors (actionable concerns)
+  Encrypt data at rest, Restrict access, Log unauthorized access
+
+Level 4: Requirements (specific, testable, implementable)
+  "FIPS 140-2 validated encryption", "RBAC with role hierarchy",
+  "Failed auth attempts logged with IP + timestamp"
+```
+
+**Rule:** You cannot start execution on a Level 1 or Level 2 requirement. If a user says "make it secure" or "add good error handling," decompose FIRST.
+
+**Agent action:** fire-planner decomposes every requirement to Level 4 before generating BLUEPRINT tasks. Each Level 4 entry must have a corresponding test/verification criterion.
+
+---
+
+## 2. Tradeoff Analysis (ATAM)
+
+Requirements exist in tension. You cannot maximize everything:
+
+| Tension | Example |
+|---------|---------|
+| Security vs. Performance | Encryption adds latency |
+| Flexibility vs. Simplicity | More config options = more complexity |
+| Speed-to-market vs. Quality | Shortcuts now = rework later |
+| Feature richness vs. Maintainability | More features = more surface area |
+
+**The ATAM goal:** "Elicit, concretize, and prioritize the driving quality attribute requirements."
+
+**Agent action:** When a plan has competing quality attributes, surface the tradeoff explicitly:
+```markdown
+## Tradeoff: {Attribute A} vs. {Attribute B}
+
+Decision: Prioritize {A} because {reason}
+Consequence: {B} will be {specific impact}
+Mitigation: {what we'll do to limit the downside}
+```
+
+**Never silently resolve a tradeoff.** The user should know what they're trading away.
+
+---
+
+## 3. Weighted Decision Matrix (WDM)
+
+When choosing between approaches, score mathematically:
+
+```
+Score = Σ (weight_i × rating_i) for each criterion
+
+Where:
+  weight_i = stakeholder priority (sum to 1.0)
+  rating_i = how well this option satisfies criterion i
+```
+
+### Weight Calculation (Rank-to-Linear)
+```
+weight = 2r / N(N+1)
+  where r = priority rank, N = total criteria count
+```
+
+### Scaling Convention
+- Higher raw value = better → use R directly (coverage %, security score)
+- Higher raw value = worse → use 1/R (cost, latency, error rate)
+- Normalize to comparable magnitude before multiplying
+
+**Agent action:** When fire-planner or fire-researcher evaluates 2+ approaches, use WDM scoring instead of subjective "I think approach A is better." Present the scored comparison to the user.
+
+---
+
+## 4. Requirements Handoff Gate
+
+Requirements are ready for execution when ALL of these are true:
+
+- [ ] **Tradeoffs are known** — you understand what you're giving up
+- [ ] **Threats to quality are mitigated** — identified and addressed
+- [ ] **Requirements are precisely defined** — not vague
+- [ ] **Requirements are measurable** — you can test and get a number
+- [ ] **Requirements are prioritized** — ranked by importance
+- [ ] **Requirements have test criteria** — each requirement maps to a verification step
+
+**If this gate fails:** Send back for clarification. Do NOT start building on vague requirements — that's how Frankenstein projects are born.
+
+---
+
+## 5. Behavioral Discovery (Post-Build Requirements)
+
+Some requirements are discovered after building, not before:
+
+| Discovery Type | Action |
+|----------------|--------|
+| **New behavior we want** | Add as new requirement, add test |
+| **Behavior that violates a requirement** | File as defect, fix |
+| **Behavior we consciously accept** | Document as acknowledged risk |
+| **Behavior not in spec at all** | Classify: is it positive implied scenario or negative? |
+
+This maps to the implied scenario detection pattern from RELIABILITY_PREDICTION.md — composition reveals behaviors no individual specification predicted.
+
+---
+
+## 6. Scenario Elicitation for AI Agents
+
+When gathering requirements from users who don't know exactly what they want:
+
+### Seed Scenario Technique
+Present high-level context descriptions to anchor the conversation:
+- "This is a SaaS platform for small businesses" (seed)
+- "Given that context, what matters most — speed to market, enterprise security, or cost efficiency?" (elicit priority)
+- "What could go wrong that would be unacceptable?" (elicit constraints)
+- "What must always work, even if other things break?" (elicit critical paths)
+
+### Quality Attribute Building Blocks
+For each stated concern, ask three questions:
+1. **Concerns:** What are you worried about?
+2. **Factors:** What sub-dimensions define this?
+3. **Methods:** How will we achieve it?
+
+This converts stakeholder stories into technical requirements without requiring technical language.
+
+---
+
+## When Agents Should Reference This Skill
+
+- **fire-1a-discuss:** Use utility tree decomposition during requirement gathering
+- **fire-planner:** Decompose to Level 4 before generating BLUEPRINT tasks
+- **fire-researcher:** Use WDM when comparing alternative approaches
+- **fire-verifier:** Verify against Level 4 requirements, not Level 1 descriptions
+- **fire-vision-architect:** Surface tradeoffs explicitly when presenting architecture branches