@mindrian_os/install 1.13.0-beta.11

package/references/methodology/root-cause.md

@@ -0,0 +1,178 @@
+# Root Cause Analysis -- Framework Reference
+
+*Loaded on demand by `/mos:root-cause`*
+
+## Framework Overview
+
+Root Cause Analysis helps users trace problems to their structural root -- not just symptoms. It offers five precision instruments, each suited to different problem complexity: 5 Whys (linear chains), Fishbone/Ishikawa (multi-factor), Fault Tree (cascading systems), Barrier Analysis (control failures), and Change Analysis (sudden-onset problems). The method matches the mess. Structured around the DACE process: Define, Analyze, Correct, Embed. Applied through Larry's evidence-demanding teaching style.
+
+The operating principle: Most organizations fix what hurts and call it solved. Then the same problem resurfaces six months later wearing a different hat. That's not problem-solving -- that's whack-a-mole with a budget. Every recurring problem is a gift telling you the real cause is still alive.
+
+## The Voice (This Methodology)
+
+Larry in diagnostic mode. Systematic. Evidence-demanding. Systems-thinker.
+
+Signature phrases:
+- "Symptoms lie. Root causes tell the truth."
+- "You're treating symptoms. Let's find the disease."
+- "That's a symptom, not a cause. Keep digging."
+- "You're fixing the alarm clock instead of what's causing the fire."
+- "If the same problem keeps coming back, you haven't found the root cause yet."
+- "Evidence. Not opinion. Show me the data."
+- "Every barrier that failed is a gift -- it tells you exactly where your system is blind."
+- "The compounding effect is what kills you -- each change alone is manageable, but together they overwhelm."
+
+Anti-patterns to catch:
+- Accepting a symptom as a root cause -- "The server crashed" is a symptom, not a cause
+- Skipping the evidence check -- each causal link must have supporting data
+- Using 5 Whys on a complex problem -- if causes are entangled, 5 Whys gives false clarity
+- Stopping at containment -- containment stops the bleeding but corrective and preventive are both required
+- Blaming people instead of systems -- "Bob made a mistake" is not a root cause
+- Presenting all DACE phases at once -- one phase, one question, build the analysis together
+- Skipping the embed phase -- RCA without documented learnings is expensive storytelling
+
+## The Five Analysis Methods
+
+### Method 1: 5 Whys
+**Best for:** Clear/Complicated problems with linear causal chains.
+- Each Why MUST be evidence-backed, not speculation.
+- If a Why branches into multiple causes, switch to Fishbone.
+- Stop when you reach a cause you can directly act on.
+
+### Method 2: Ishikawa Fishbone
+**Best for:** Complicated, multi-factor problems.
+- Decompose across 6M categories: Man, Machine, Method, Material, Measurement, Mother Nature.
+- Rate each factor: Impact (H/M/L) x Likelihood (H/M/L).
+- High-High factors are your probable root causes.
+
+### Method 3: Fault Tree Analysis
+**Best for:** Complex, cascading system failures.
+- Work top-down from the failure event using AND/OR gates.
+- AND gate: all children must occur. OR gate: any child can cause parent.
+- Basic events at leaf nodes = actionable root causes.
+
+### Method 4: Barrier Analysis
+**Best for:** Complex problems where controls should have prevented failure.
+- For each barrier: Worked / Failed / Missing / Bypassed.
+- Four failure modes: Missing (never existed), Failed (broke), Bypassed (circumvented), Inadequate (insufficient).
+
+### Method 5: Change Analysis
+**Best for:** Sudden-onset problems with clear before/after.
+- Before/after comparison: People, Process, Technology, Environment, Timing.
+- The changes are your candidate root causes.
+
+## Phases
+
+### Phase 1: DETECT -- Problem Framing and Complexity (Investigative -- turns 1-3)
+
+Frame the problem precisely and assess complexity.
+
+- "What exactly broke? Give me a specific, measurable problem statement -- not a category."
+  - BAD: "Sales are down."
+  - GOOD: "Q3 enterprise pipeline conversion dropped from 34% to 19% despite stable lead volume, beginning in week 28."
+- "What's the impact? Financial, temporal, scope -- quantify what's at stake."
+- Classify complexity using Cynefin:
+  - Clear: obvious cause-effect --> 5 Whys
+  - Complicated: multiple possible causes, experts needed --> Fishbone or Change Analysis
+  - Complex: entangled causes, emergent behavior --> Fault Tree + Barrier Analysis
+  - Chaotic: no clear causality --> stabilize first, RCA later
+- "What evidence do we have vs what do we need?"
+
+ONE question per response. Short and Socratic.
+
+### Phase 2: ANALYZE -- Method Selection and Execution (Investigative to Blend -- turns 3-6)
+
+Select and execute the appropriate analysis method(s).
+
+- Select method based on complexity assessed in Phase 1.
+- Multiple methods can combine for thorough analysis.
+- Execute the chosen method step by step, always requiring evidence for each causal link.
+
+### Phase 3: CORRECT -- Action Planning (Blend to Insight -- turns 6-8)
+
+For each validated root cause, define three tiers of action.
+
+- Containment (immediate): Stop the bleeding. Hours/days.
+- Corrective (medium-term): Fix the root cause. Weeks.
+- Preventive (long-term): Ensure it never recurs. Months.
+
+Priority: Impact x Urgency. P1 = act now, P2 = plan immediately, P3 = quick win, P4 = backlog.
+
+### Phase 4: EMBED -- Learning and Prevention (Insight -- turns 8+)
+
+Ensure the analysis produces lasting organizational learning.
+
+- Document: Problem --> Analysis --> Root Causes --> Actions --> Results.
+- Share: Who else faces similar risks?
+- Update: Checklists, monitoring, training.
+- Review: Schedule 30/60/90 day check on corrective actions.
+
+End with: "Now the real question -- what other problems in your organization have the same root cause you just found?"
+
+## Artifact Template
+
+```markdown
+---
+methodology: root-cause
+created: {date}
+depth: {quick|deep}
+problem_type: {type}
+venture_stage: {stage}
+room_section: problem-definition
+---
+
+# Root Cause Analysis -- {Problem Title}
+
+## Problem Statement
+{Clear, specific, measurable description}
+
+## Impact
+- Financial: {quantified}
+- Scope: {who/what affected}
+- Urgency: {timeline}
+
+## Complexity: {Clear / Complicated / Complex / Chaotic}
+## Method(s) Used: {5 Whys / Fishbone / Fault Tree / Barrier / Change}
+
+## Analysis
+{Method-specific analysis with evidence at each step}
+
+## Root Causes (ranked by confidence)
+1. {Root Cause 1} -- Confidence: {H/M/L} -- Evidence: {summary}
+2. {Root Cause 2} -- Confidence: {H/M/L} -- Evidence: {summary}
+
+## Corrective Action Plan (DACE)
+
+| # | Root Cause | Action | Type | Owner | Due | Metric |
+|---|-----------|--------|------|-------|-----|--------|
+| 1 | {RC1} | {action} | Containment | {who} | {when} | {measure} |
+| 2 | {RC1} | {action} | Corrective | {who} | {when} | {measure} |
+| 3 | {RC1} | {action} | Preventive | {who} | {when} | {measure} |
+
+## Lessons Learned
+{Key insights for preventing similar issues}
+
+## Review Schedule
+- 30-day check: {date} -- verify containment holding
+- 60-day check: {date} -- verify corrective actions in place
+- 90-day check: {date} -- verify preventive measures effective
+
+## Homework
+Take your highest-confidence root cause. Walk through your organization and find three other processes that share the same structural vulnerability. The root cause you found isn't unique -- it's a pattern. Find the pattern.
+```
+
+## Default Room
+
+problem-definition
+
+## Cross-References
+
+- **find-bottlenecks**: If root causes reveal systemic bottlenecks
+- **analyze-systems**: If the problem exists within a complex system
+- **challenge-assumptions**: If root cause analysis reveals hidden assumptions
+- **validate**: If root cause evidence needs rigorous validation
+
+## Quick Pass vs Deep Dive
+
+- **Quick (10-15 min)**: Frame the problem, run 5 Whys, identify top root cause, basic containment plan. Good when the problem is clear and linear.
+- **Deep (30-60 min)**: Full DACE process, multiple analysis methods, complete corrective action plan with all three tiers, embed phase with review schedule. Best for complex or recurring problems where superficial analysis has already failed.

package/references/methodology/sapphire-encoding.md

@@ -0,0 +1,355 @@
+# SAPPhIRE Functional Encoding Guide
+
+*A systematic method for extracting function-behavior-structure descriptions from room artifacts, enabling cross-domain analogy discovery.*
+
+---
+
+## What Is SAPPhIRE?
+
+SAPPhIRE is a 7-layer ontology developed by Chakrabarti et al. for encoding ANY system in terms of its functional architecture. The acronym stands for:
+
+- **S**tate change
+- **A**ction
+- **P**art
+- **Ph**enomenon
+- **I**nput
+- **R**eal effect (physical/logical law)
+- **E**ffect (intended outcome)
+
+The model captures how a system transforms inputs into outcomes through its structural parts, the phenomena they create, and the physical/logical effects that govern the transformation. By encoding artifacts at this level, two systems that look nothing alike on the surface can be recognized as structurally identical -- enabling analogy transfer.
+
+---
+
+## The 7 SAPPhIRE Layers
+
+### Layer 1: State Change
+
+**Definition:** The observable change in condition, position, or configuration that occurs when the system operates.
+
+**Question:** What changes? What is different before vs after?
+
+**Room mapping:** `problem-definition/` -- the gap between current state and desired state.
+
+### Layer 2: Action
+
+**Definition:** The interaction or operation that causes the state change. What the system DOES, in functional terms.
+
+**Question:** What does the system do to cause the state change?
+
+**Room mapping:** `solution-design/` -- the product/service action, the user interaction mechanism.
+
+### Layer 3: Part
+
+**Definition:** The structural components, agents, or resources involved in performing the action.
+
+**Question:** What structural elements are involved? Who/what performs the action?
+
+**Room mapping:** `team-execution/` -- team composition, partnerships, technology stack, resources.
+
+### Layer 4: Phenomenon
+
+**Definition:** The observable behaviors, signals, or patterns that emerge from the parts performing the action.
+
+**Question:** What can you observe happening? What patterns emerge?
+
+**Room mapping:** `market-analysis/` -- market trends, user behaviors, demand signals, adoption patterns.
+
+### Layer 5: Input
+
+**Definition:** The energy, information, material, or resources consumed or required for the phenomenon to occur.
+
+**Question:** What goes in? What is consumed, spent, or required?
+
+**Room mapping:** `business-model/` -- revenue streams, funding sources, customer acquisition cost, operational inputs.
+
+### Layer 6: Real Effect
+
+**Definition:** The physical, economic, or logical law/principle that governs why the phenomenon produces the intended effect. The underlying mechanism.
+
+**Question:** WHY does it work? What law or principle makes this possible?
+
+**Room mapping:** `competitive-analysis/` -- moat, structural advantage, network effects, economic logic.
+
+### Layer 7: Effect
+
+**Definition:** The intended outcome, the value delivered, the purpose fulfilled.
+
+**Question:** What value is created? What job is done?
+
+**Room mapping:** `financial-model/` -- unit economics, growth mechanism, value creation, return on investment.
+
+---
+
+## SAPPhIRE Extraction Template
+
+Use this template when encoding a room artifact for analogy search. Strip all domain-specific language and express each layer in functional terms.
+
+```yaml
+sapphire_encoding:
+  artifact_id: "{section}/{filename}"
+  domain: "{venture domain}"
+
+  state_change:
+    before: "{current state in functional terms}"
+    after: "{desired state in functional terms}"
+    delta: "{what specifically changes}"
+
+  action:
+    verb: "{functional verb: deliver, protect, transform, connect, filter, amplify, regulate, separate, convert}"
+    description: "{domain-independent description of what the system does}"
+
+  parts:
+    - name: "{component name}"
+      role: "{functional role}"
+    - name: "{component name}"
+      role: "{functional role}"
+
+  phenomenon:
+    observable: "{what you can measure or observe}"
+    pattern: "{temporal or spatial pattern}"
+
+  input:
+    energy: "{what energy/effort is consumed}"
+    information: "{what information is required}"
+    material: "{what material/resource is consumed}"
+
+  real_effect:
+    principle: "{underlying law or mechanism}"
+    why_it_works: "{causal explanation}"
+
+  effect:
+    intended_outcome: "{value delivered}"
+    beneficiary: "{who benefits}"
+
+  functional_keywords:
+    - "{keyword1}"
+    - "{keyword2}"
+    - "{keyword3}"
+
+  triz_parameters:
+    improving: "{TRIZ parameter being improved}"
+    worsening: "{TRIZ parameter being worsened, if any}"
+```
+
+---
+
+## Worked Examples
+
+### Example 1: EdTech Platform (Education Domain)
+
+**Original artifact:** "Our AI tutoring platform uses spaced repetition algorithms to personalize study schedules for medical students, improving board exam pass rates from 72% to 91%."
+
+```yaml
+sapphire_encoding:
+  artifact_id: "solution-design/ai-tutoring-platform"
+  domain: "education-technology"
+
+  state_change:
+    before: "Knowledge retention decays rapidly after initial exposure"
+    after: "Knowledge retention maintained at high levels over extended period"
+    delta: "Retention curve flattened through optimized review timing"
+
+  action:
+    verb: "regulate"
+    description: "System regulates timing of information re-exposure based on individual decay rates"
+
+  parts:
+    - name: "decay-rate estimator"
+      role: "measures individual knowledge degradation per concept"
+    - name: "schedule optimizer"
+      role: "computes optimal re-exposure intervals"
+    - name: "content delivery mechanism"
+      role: "presents appropriate material at computed time"
+
+  phenomenon:
+    observable: "Review intervals lengthen as retention strengthens"
+    pattern: "Exponentially increasing gaps between reviews for mastered material"
+
+  input:
+    energy: "Learner time and attention per review session"
+    information: "Performance data from each review attempt"
+    material: "Structured knowledge content with assessable components"
+
+  real_effect:
+    principle: "Ebbinghaus forgetting curve - memory strength follows exponential decay, counteracted by timed retrieval practice"
+    why_it_works: "Each successful retrieval strengthens the memory trace, shifting the decay curve"
+
+  effect:
+    intended_outcome: "Sustained knowledge mastery with minimal total study time"
+    beneficiary: "Learner seeking long-term retention"
+
+  functional_keywords:
+    - "regulate"
+    - "decay-counteraction"
+    - "adaptive-timing"
+    - "retention-optimization"
+
+  triz_parameters:
+    improving: "Duration of action of moving object"
+    worsening: "Loss of energy"
+```
+
+**Analogy discovery:** This SAPPhIRE encoding matches systems in agriculture (drip irrigation timing), medicine (drug dosing schedules), and infrastructure maintenance (predictive maintenance intervals) -- all regulate timing of intervention to counteract a decay process.
+
+---
+
+### Example 2: Supply Chain Transparency (Logistics Domain)
+
+**Original artifact:** "Blockchain-based provenance tracking for coffee from farm to cup. Each handler scans and records, creating immutable chain of custody. Reduces fraud claims by 85%."
+
+```yaml
+sapphire_encoding:
+  artifact_id: "solution-design/blockchain-provenance"
+  domain: "supply-chain-logistics"
+
+  state_change:
+    before: "Chain of custody has unverifiable gaps between handlers"
+    after: "Complete, tamper-evident record of every custody transfer"
+    delta: "Trust gap eliminated through distributed verification"
+
+  action:
+    verb: "connect"
+    description: "System connects sequential custody events into a tamper-evident chain"
+
+  parts:
+    - name: "distributed ledger"
+      role: "stores immutable sequence of custody records"
+    - name: "identity verifier"
+      role: "authenticates each handler at transfer point"
+    - name: "event recorder"
+      role: "captures transfer metadata at each handoff"
+
+  phenomenon:
+    observable: "Monotonically growing chain of signed transfer events"
+    pattern: "Each new event references the previous, forming directed acyclic graph"
+
+  input:
+    energy: "Handler effort to scan/record at each transfer"
+    information: "Identity credentials, location, timestamp, condition metadata"
+    material: "Physical good being tracked"
+
+  real_effect:
+    principle: "Hash chain integrity - each record cryptographically references its predecessor, making retrospective alteration computationally infeasible"
+    why_it_works: "Tamper detection is automatic because any modification breaks the hash chain"
+
+  effect:
+    intended_outcome: "Trustworthy provenance without requiring trust in any single party"
+    beneficiary: "End consumer and brand owner seeking authenticity assurance"
+
+  functional_keywords:
+    - "connect"
+    - "tamper-evident-chain"
+    - "distributed-verification"
+    - "custody-tracking"
+
+  triz_parameters:
+    improving: "Reliability"
+    worsening: "Device complexity"
+```
+
+**Analogy discovery:** This matches DNA chain of evidence in forensics, academic citation chains (each paper references predecessors), and version control systems (Git commits form hash chains). The structural isomorphism is the tamper-evident linked sequence.
+
+---
+
+### Example 3: Cancer Drug Delivery (Biomedical Domain)
+
+**Original artifact:** "Nanoparticle drug carriers with pH-sensitive coating. Coating remains stable in normal blood pH (7.4) but dissolves in tumor microenvironment (pH 6.5-6.8), releasing drug payload only at target site."
+
+```yaml
+sapphire_encoding:
+  artifact_id: "solution-design/ph-sensitive-nanocarrier"
+  domain: "biomedical-drug-delivery"
+
+  state_change:
+    before: "Therapeutic agent distributed systemically causing off-target effects"
+    after: "Therapeutic agent concentrated at target site with minimal off-target exposure"
+    delta: "Spatial specificity of delivery achieved through environmental sensing"
+
+  action:
+    verb: "filter"
+    description: "System filters delivery location based on environmental condition at destination"
+
+  parts:
+    - name: "payload container"
+      role: "carries therapeutic agent in protected state"
+    - name: "environment-sensitive barrier"
+      role: "remains intact in normal conditions, degrades in target conditions"
+    - name: "targeting ligand"
+      role: "guides carrier toward target tissue"
+
+  phenomenon:
+    observable: "Barrier integrity changes as environmental parameter crosses threshold"
+    pattern: "Binary switch: stable above threshold, degrades below threshold"
+
+  input:
+    energy: "Chemical energy of pH-driven dissolution"
+    information: "Environmental pH as binary location signal"
+    material: "Carrier material consumed during dissolution"
+
+  real_effect:
+    principle: "pH-dependent solubility - protonation state of polymer changes with pH, altering hydrophilicity and structural integrity"
+    why_it_works: "The environmental difference between target and non-target creates a natural binary classifier"
+
+  effect:
+    intended_outcome: "Maximum therapeutic effect with minimum side effects"
+    beneficiary: "Patient receiving targeted therapy"
+
+  functional_keywords:
+    - "filter"
+    - "environment-triggered-release"
+    - "binary-threshold"
+    - "targeted-delivery"
+
+  triz_parameters:
+    improving: "Harmful side effects"
+    worsening: "Device complexity"
+```
+
+**Analogy discovery:** This matches smart contracts (execute only when conditions are met), geofenced notifications (trigger only in specific locations), and adaptive building materials (change properties based on temperature). The structural isomorphism is environment-triggered state change with binary threshold.
+
+---
+
+## How to Use in MindrianOS
+
+### During /mos:find-analogies (Stage 1: DECOMPOSE)
+
+1. Larry reads room artifacts across all sections
+2. For each significant artifact, Larry extracts a SAPPhIRE encoding using this template
+3. The functional_keywords become search terms for Stage 2 (ABSTRACT)
+4. The triz_parameters feed the TRIZ contradiction matrix lookup
+
+### During Pipeline Stage 2 (ABSTRACT)
+
+1. Strip all domain-specific language from the SAPPhIRE encoding
+2. Map to TRIZ parameter space using triz_parameters
+3. Generate functional search queries: "What else [action verb]s to achieve [effect] by exploiting [real_effect]?"
+
+### During Pipeline Stage 3 (SEARCH)
+
+1. Use functional_keywords for Brain semantic search
+2. Use action verb + real_effect for cross-domain pattern matching
+3. SAPPhIRE encodings from different domains are compared layer-by-layer
+4. Isomorphism score = proportion of layers with structural correspondence
+
+### Scoring Structural Fitness
+
+Compare two SAPPhIRE encodings layer by layer:
+
+| Match Level | Layers Matching | Fitness Score |
+|-------------|----------------|---------------|
+| Surface | State change only | 0.1-0.2 |
+| Behavioral | State change + Action + Phenomenon | 0.3-0.5 |
+| Structural | State + Action + Phenomenon + Real effect | 0.6-0.8 |
+| Deep | All 7 layers correspond | 0.8-1.0 |
+
+High structural fitness with different domains = far analogy = high innovation potential.
+
+---
+
+## Reference
+
+Chakrabarti, A., Sarkar, P., Leelavathamma, B., & Nataraju, B.S. (2005). A functional representation for aiding biomimetic and artificial inspiration of new ideas. *Artificial Intelligence for Engineering Design, Analysis and Manufacturing*, 19(2), 113-132.
+
+Srinivasan, V., & Chakrabarti, A. (2010). Investigating novelty-outcome relationships in engineering design. *Artificial Intelligence for Engineering Design, Analysis and Manufacturing*, 24(2), 161-178.
+
+Gentner, D. (1983). Structure-mapping: A theoretical framework for analogy. *Cognitive Science*, 7(2), 155-170.