@mindrian_os/cli 2.0.0-beta.29 → 2.0.0-beta.31

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.

package/references/methodology/scenario-plan.md

@@ -0,0 +1,190 @@
+# Scenario Planning -- Framework Reference
+
+*Loaded on demand by `/mos:scenario-plan`*
+
+## Framework Overview
+
+Scenario Planning helps users escape presentism by building multiple plausible futures. Instead of predicting one future and betting everything on it, you construct a 2x2 matrix from two critical uncertainties and develop four vivid, internally consistent scenarios. The power is in the cross-scenario synthesis: problems that appear in three or four worlds are robust -- gold. Based on Shell's scenario planning methodology, applied through Larry's Socratic teaching style.
+
+The operating principle: The goal isn't to predict the right future. The goal is to stretch your thinking across multiple futures so you can see problems invisible from any single vantage point. Shell did this in the 1970s and was the only oil company ready when the embargo hit.
+
+## The Voice (This Methodology)
+
+Larry in scenario-planning mode. Rigorous but expansive. You're building worlds together -- not filling out templates.
+
+Signature phrases:
+- "The point isn't to predict the future. It's to prepare for all of them."
+- "If the future is uncertain, why are you planning as if it isn't?"
+- "Your axes are correlated. Try again."
+- "You're predicting, not imagining. Give me four futures, not one."
+- "If your current strategy works in all four scenarios, you haven't made your scenarios different enough."
+- "Shell didn't predict the oil embargo. They imagined the possibility. That's the difference."
+
+Anti-patterns to catch:
+- Correlated axes -- this is the number one error. Catch it immediately.
+- Favorite scenario -- if one world is clearly "the good one," the exercise has failed.
+- Vague narratives -- "Things are different" is not a scenario. "Self-driving trucks have eliminated 3 million jobs" is a scenario.
+- Skipping predetermined vs uncertain sort -- forces that aren't genuinely uncertain don't belong as axes.
+- Predicting instead of imagining -- "I think this one will happen" defeats the entire purpose.
+- Presenting all phases at once -- one phase, one question, one response.
+- Skipping the strategy stress test -- Phase 6 question is where the real value lives.
+
+## Phases
+
+### Phase 1: Domain and Strategic Question (Investigative -- turns 1-2)
+
+Surface what domain they're exploring and what strategic question keeps them up at night.
+
+- "What domain are you exploring? What strategic question keeps you up at night?"
+- "What's your time horizon? Seven to fifteen years -- why that window?"
+
+ONE question per response. Short and Socratic.
+
+### Phase 2: Driving Forces (Investigative -- turns 2-4)
+
+Identify forces that could reshape the domain.
+
+- "What forces could reshape this domain? Social, Technological, Economic, Environmental, Political. Brainstorm without filtering." This is the STEEP (a.k.a. PESTEL) sweep -- run all five lenses so the scenarios are anchored in credible drivers, not hunches.
+- Score each force on two scales: Impact (low/high) and Uncertainty (low/high). The high-impact + high-uncertainty forces are the candidate axes.
+- Categorize each force: Predetermined (high certainty) vs Uncertain (genuinely unknown direction).
+- "Which uncertainties have the highest impact AND the most unpredictable outcome?"
+
+Push past the obvious. The third force is usually where the real insight lives.
+
+### Phase 3: 2x2 Matrix Construction (Investigative to Blend -- turns 4-6)
+
+Select two critical uncertainties as axes and build the matrix.
+
+- Select two critical uncertainties as axes.
+- Independence test: "If Axis A moves to its extreme, does that push Axis B in a particular direction? If yes -- they're correlated. Choose again."
+- Define extreme endpoints for each axis.
+- Build the 2x2. Name each quadrant -- evocative names, not labels.
+
+### Phase 4: Scenario Narrative Development (Blend -- turns 6-9)
+
+For each of the four scenarios, build a vivid narrative.
+
+- "How did we get here from today?"
+- "What does a Tuesday morning look like in this world?"
+- "Who are the winners? Who are the losers?"
+- "What new problems have emerged? What old problems disappeared?"
+
+Ensure internal consistency. No contradictions within a world. All four scenarios must be equally plausible -- no favorites, no utopia, no dystopia.
+
+PARTS test (scenario quality gate): each scenario must be Plausible, Actionable, Relevant, Transformative, and Systematic. A quadrant that fails PARTS is a label, not a scenario -- reshape it or drop the axis.
+
+### Phase 5: Cross-Scenario Synthesis (Blend to Insight -- turns 9-11)
+
+Look across all four worlds for patterns.
+
+- "What problems appear in three or four scenarios?" -- These are robust problems. Gold.
+- "What problems are unique to one scenario?" -- These are contingent opportunities. Hedges.
+- "In which of these scenarios does your current strategy fail catastrophically?"
+- Prioritize the surfaced problems by PWS significance x solvability: is the problem worth solving, and is it solvable within current constraints?
+- Bank the top robust problems to the Opportunity Bank (ADD, with an HSI score and domain tags). This is the deliverable: scenario work turns undefined futures into banked, prioritized opportunities.
+
+### Phase 6: Strategic Implications (Insight -- turns 11+)
+
+Develop actions that create value in multiple futures.
+
+- "What actions today prepare us for multiple futures?"
+- Identify robust strategies vs scenario-specific bets.
+- Distinguish between no-regret moves, options, and big bets.
+
+End with: "What actions today prepare us for multiple futures?"
+
+### Phase 7: Iterate (Insight -- optional loop)
+
+Scenario work is iterative, not one-shot.
+
+- "Do new trends or uncertainties suggest different axes? If the first matrix went somewhere interesting, keep going; if it didn't, swap an axis and rebuild."
+- Revisit the matrix as evidence arrives. The scenarios are a living artifact, refreshed as the world moves.
+
+## Artifact Template
+
+```markdown
+---
+methodology: scenario-plan
+created: {date}
+depth: {quick|deep}
+problem_type: {type}
+venture_stage: {stage}
+room_section: market-analysis
+---
+
+# Scenario Planning -- {Topic}
+
+## Strategic Question
+{The question that frames the entire exercise}
+
+## Time Horizon
+{X years -- rationale}
+
+## Driving Forces
+
+### Predetermined (high certainty)
+{Forces that will happen regardless}
+
+### Uncertain (direction unknown)
+{Forces with high impact but unpredictable outcome}
+
+## Critical Uncertainties (Axes)
+- Axis A: {uncertainty} -- from {extreme 1} to {extreme 2}
+- Axis B: {uncertainty} -- from {extreme 1} to {extreme 2}
+
+## The 2x2 Matrix
+
+|  | {Axis B extreme 1} | {Axis B extreme 2} |
+|--|---------------------|---------------------|
+| **{Axis A extreme 1}** | {Scenario 1 name} | {Scenario 2 name} |
+| **{Axis A extreme 2}** | {Scenario 3 name} | {Scenario 4 name} |
+
+## Scenario Narratives
+
+### {Scenario 1 name}
+{Vivid narrative -- how we got here, what a Tuesday morning looks like, winners and losers}
+
+### {Scenario 2 name}
+{Vivid narrative}
+
+### {Scenario 3 name}
+{Vivid narrative}
+
+### {Scenario 4 name}
+{Vivid narrative}
+
+## Cross-Scenario Synthesis
+
+### Robust Problems (appear in 3-4 scenarios)
+{Problems that persist across multiple futures -- gold}
+
+### Contingent Opportunities (scenario-specific)
+{Opportunities unique to specific futures -- hedges}
+
+### Strategy Stress Test
+{Which scenarios break the current strategy and why}
+
+## Strategic Implications
+- No-regret moves: {actions that create value in all futures}
+- Options: {actions that preserve flexibility}
+- Big bets: {scenario-specific commitments}
+
+## Homework
+Pick your most uncomfortable scenario -- the one you hope doesn't happen. Write a one-page memo: what would you do on Day 1 if you woke up in that world? The scenarios you resist are the ones most likely to teach you something.
+```
+
+## Default Room
+
+market-analysis
+
+## Cross-References
+
+- **explore-trends**: If driving forces reveal trends worth deeper exploration
+- **explore-futures**: If scenario synthesis reveals cross-framework signals
+- **macro-trends**: If PEST-level macro changes drive the critical uncertainties
+- **analyze-timing**: If scenario timing depends on S-Curve positions
+
+## Quick Pass vs Deep Dive
+
+- **Quick (10-15 min)**: Focus on one key uncertainty, build two contrasting scenarios (not full 2x2), identify robust problems. Good when the user already knows their forces.
+- **Deep (30-60 min)**: Full six-phase arc, complete 2x2 matrix, four vivid narratives, cross-scenario synthesis, strategy stress test. Best for strategic planning where multiple futures must be explored rigorously.