moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-foundation-philosopher/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: "moai-foundation-philosopher"
+description: "Strategic thinking framework integrating First Principles Analysis, Stanford Design Thinking, and MIT Systems Engineering for deeper problem-solving and decision-making"
+version: 1.1.0
+category: "foundation"
+modularized: true
+user-invocable: false
+tags: ['foundation', 'strategic-thinking', 'first-principles', 'trade-off-analysis', 'cognitive-bias', 'decision-making']
+updated: 2026-01-08
+status: "active"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# MoAI Foundation Philosopher
+
+Strategic thinking framework that promotes deeper analysis over quick calculations. Integrates three proven methodologies for systematic problem-solving.
+
+Core Philosophy: Think deeply before acting. Question assumptions. Consider alternatives. Make trade-offs explicit. Check for cognitive biases.
+
+## Quick Reference (30 seconds)
+
+What is the Philosopher Framework?
+
+A structured approach to complex decisions combining:
+- First Principles Analysis: Break problems to fundamental truths
+- Stanford Design Thinking: Divergent-convergent solution generation
+- MIT Systems Engineering: Systematic risk assessment and validation
+
+Five-Phase Thinking Process:
+1. Assumption Audit: Surface and question what we take for granted
+2. First Principles Decomposition: Break down to root causes
+3. Alternative Generation: Create multiple solution options
+4. Trade-off Analysis: Compare options systematically
+5. Cognitive Bias Check: Verify thinking quality
+
+When to Activate:
+- Architecture decisions affecting 5+ files
+- Technology selection (library, framework, database)
+- Performance vs maintainability trade-offs
+- Refactoring scope decisions
+- Breaking changes consideration
+- Any decision with significant long-term impact
+
+Quick Access:
+- Assumption questioning techniques: [Assumption Matrix Module](modules/assumption-matrix.md)
+- Root cause analysis: [First Principles Module](modules/first-principles.md)
+- Option comparison: [Trade-off Analysis Module](modules/trade-off-analysis.md)
+- Bias prevention: [Cognitive Bias Module](modules/cognitive-bias.md)
+
+---
+
+## Implementation Guide (5 minutes)
+
+### Phase 1: Assumption Audit
+
+Purpose: Surface hidden assumptions before they become blind spots.
+
+Five Critical Questions:
+- What are we assuming to be true without evidence?
+- What if this assumption turns out to be wrong?
+- Is this a hard constraint or merely a preference?
+- What evidence supports this assumption?
+- Who else should validate this assumption?
+
+Assumption Categories:
+- Technical Assumptions: Technology capabilities, performance characteristics, compatibility
+- Business Assumptions: User behavior, market conditions, budget availability
+- Team Assumptions: Skill levels, availability, domain knowledge
+- Timeline Assumptions: Delivery expectations, dependency schedules
+
+Assumption Documentation Format:
+- Assumption statement: Clear description of what is assumed
+- Confidence level: High, Medium, or Low based on evidence
+- Evidence basis: What supports this assumption
+- Risk if wrong: Consequence if assumption proves false
+- Validation method: How to verify before committing
+
+WHY: Unexamined assumptions are the leading cause of project failures and rework.
+IMPACT: Surfacing assumptions early prevents 40-60% of mid-project pivots.
+
+### Phase 2: First Principles Decomposition
+
+Purpose: Cut through complexity to find root causes and fundamental requirements.
+
+The Five Whys Technique:
+- Surface Problem: What the user or system observes
+- First Why: Immediate cause analysis
+- Second Why: Underlying cause investigation
+- Third Why: Systemic driver identification
+- Fourth Why: Organizational or process factor
+- Fifth Why (Root Cause): Fundamental issue to address
+
+Constraint Analysis:
+- Hard Constraints: Non-negotiable (security, compliance, physics, budget)
+- Soft Constraints: Negotiable preferences (timeline, feature scope, tooling)
+- Self-Imposed Constraints: Assumptions disguised as requirements
+- Degrees of Freedom: Areas where creative solutions are possible
+
+Decomposition Questions:
+- What is the actual goal behind this request?
+- What problem are we really trying to solve?
+- What would a solution look like if we had no constraints?
+- What is the minimum viable solution?
+- What can we eliminate while still achieving the goal?
+
+WHY: Most problems are solved at the wrong level of abstraction.
+IMPACT: First principles thinking reduces solution complexity by 30-50%.
+
+### Phase 3: Alternative Generation
+
+Purpose: Avoid premature convergence on suboptimal solutions.
+
+Generation Rules:
+- Minimum three distinct alternatives required
+- Include at least one unconventional option
+- Always include "do nothing" as baseline
+- Consider short-term vs long-term implications
+- Explore both incremental and transformative approaches
+
+Alternative Categories:
+- Conservative: Low risk, incremental improvement, familiar technology
+- Balanced: Moderate risk, significant improvement, some innovation
+- Aggressive: Higher risk, transformative change, cutting-edge approach
+- Radical: Challenge fundamental assumptions, completely different approach
+
+Creativity Techniques:
+- Inversion: What would make this problem worse? Now do the opposite.
+- Analogy: How do other domains solve similar problems?
+- Constraint Removal: What if budget, time, or technology were unlimited?
+- Simplification: What is the simplest possible solution?
+
+WHY: The first solution is rarely the best solution.
+IMPACT: Considering 3+ alternatives improves decision quality by 25%.
+
+### Phase 4: Trade-off Analysis
+
+Purpose: Make implicit trade-offs explicit and comparable.
+
+Standard Evaluation Criteria:
+- Performance: Speed, throughput, latency, resource usage
+- Maintainability: Code clarity, documentation, team familiarity
+- Implementation Cost: Development time, complexity, learning curve
+- Risk Level: Technical risk, failure probability, rollback difficulty
+- Scalability: Growth capacity, flexibility, future-proofing
+- Security: Vulnerability surface, compliance, data protection
+
+Weighted Scoring Method:
+- Assign weights to criteria based on project priorities (total 100%)
+- Rate each option 1-10 on each criterion
+- Calculate weighted composite score
+- Document reasoning for each score
+- Identify score sensitivity to weight changes
+
+Trade-off Documentation:
+- What we gain: Primary benefits of chosen approach
+- What we sacrifice: Explicit costs and limitations accepted
+- Why acceptable: Rationale for accepting these trade-offs
+- Mitigation plan: How to address downsides
+
+WHY: Implicit trade-offs lead to regret and second-guessing.
+IMPACT: Explicit trade-offs improve stakeholder alignment by 50%.
+
+### Phase 5: Cognitive Bias Check
+
+Purpose: Ensure recommendation quality by checking for common thinking errors.
+
+Primary Biases to Monitor:
+- Anchoring Bias: Over-reliance on first information encountered
+- Confirmation Bias: Seeking evidence that supports existing beliefs
+- Sunk Cost Fallacy: Continuing due to past investment
+- Availability Heuristic: Overweighting recent or memorable events
+- Overconfidence Bias: Excessive certainty in own judgment
+
+Bias Detection Questions:
+- Am I attached to this solution because I thought of it first?
+- Have I actively sought evidence against my preference?
+- Would I recommend this if starting fresh with no prior investment?
+- Am I being influenced by recent experiences that may not apply?
+- What would change my mind about this recommendation?
+
+Mitigation Strategies:
+- Pre-mortem: Imagine the decision failed; what went wrong?
+- Devil's advocate: Argue against your own recommendation
+- Outside view: What do base rates suggest about success?
+- Disagreement seeking: Consult someone likely to challenge you
+- Reversal test: If the opposite were proposed, what would you say?
+
+WHY: Even experts fall prey to cognitive biases under time pressure.
+IMPACT: Bias checking prevents 20-30% of flawed technical decisions.
+
+---
+
+## Advanced Implementation (10+ minutes)
+
+### Integration with MoAI Workflow
+
+SPEC Phase Integration:
+- Apply Assumption Audit during /moai:1-plan
+- Document assumptions in spec.md Problem Analysis section
+- Include alternative approaches considered in plan.md
+- Define validation criteria in acceptance.md
+
+TDD Phase Integration:
+- Use First Principles to identify core test scenarios
+- Generate test alternatives for edge cases
+- Apply Trade-off Analysis for test coverage decisions
+
+Quality Phase Integration:
+- Include Cognitive Bias Check in code review process
+- Verify assumptions remain valid after implementation
+- Document trade-offs accepted in final documentation
+
+### Time Allocation Guidelines
+
+Recommended effort distribution for complex decisions:
+- Assumption Audit: 15% of analysis time
+- First Principles Decomposition: 25% of analysis time
+- Alternative Generation: 20% of analysis time
+- Trade-off Analysis: 25% of analysis time
+- Cognitive Bias Check: 15% of analysis time
+
+Total Analysis vs Implementation:
+- Simple decisions (1-2 files): 10% analysis, 90% implementation
+- Medium decisions (3-10 files): 25% analysis, 75% implementation
+- Complex decisions (10+ files): 40% analysis, 60% implementation
+- Architecture decisions: 50% analysis, 50% implementation
+
+### Decision Documentation Template
+
+Strategic Decision Record:
+
+Decision Title: Clear statement of what was decided
+
+Context: Why this decision was needed
+
+Assumptions Examined:
+- Assumption 1 with confidence and validation status
+- Assumption 2 with confidence and validation status
+
+Root Cause Analysis:
+- Surface problem identified
+- Root cause determined through Five Whys
+
+Alternatives Considered:
+- Option A with pros, cons, and score
+- Option B with pros, cons, and score
+- Option C with pros, cons, and score
+
+Trade-offs Accepted:
+- What we gain with chosen approach
+- What we sacrifice and why acceptable
+
+Bias Check Completed:
+- Confirmation of bias mitigation steps taken
+
+Final Decision: Selected option with primary rationale
+
+Success Criteria: How we will measure if decision was correct
+
+Review Trigger: Conditions that would cause reconsideration
+
+---
+
+## Works Well With
+
+Agents:
+- manager-strategy: Primary consumer for SPEC analysis and planning
+- expert-backend: Technology selection decisions
+- expert-frontend: Architecture and framework choices
+- expert-database: Schema design trade-offs
+- manager-quality: Code review bias checking
+
+Skills:
+- moai-foundation-core: Integration with TRUST 5 and SPEC workflow
+- moai-workflow-spec: Assumption documentation in SPEC format
+- moai-domain-backend: Technology-specific trade-off criteria
+- moai-domain-frontend: UI/UX decision frameworks
+
+Commands:
+- /moai:1-plan: Apply Philosopher Framework during specification
+- /moai:2-run: Reference documented trade-offs during implementation
+
+---
+
+## Quick Decision Matrix
+
+When to use which phase:
+
+Simple Bug Fix: Skip Philosopher (direct implementation)
+Feature Addition: Phases 1, 3, 4 (assumptions, alternatives, trade-offs)
+Refactoring: Phases 1, 2, 4 (assumptions, root cause, trade-offs)
+Technology Selection: All 5 phases (full analysis required)
+Architecture Change: All 5 phases with extended documentation
+
+---
+
+Module Deep Dives:
+- [Assumption Matrix](modules/assumption-matrix.md)
+- [First Principles](modules/first-principles.md)
+- [Trade-off Analysis](modules/trade-off-analysis.md)
+- [Cognitive Bias](modules/cognitive-bias.md)
+
+Examples: [examples.md](examples.md)
+External Resources: [reference.md](reference.md)
+
+Origin: Inspired by Claude Code Philosopher Ignition framework

moai_adk/templates/.claude/skills/moai-foundation-philosopher/examples.md

@@ -0,0 +1,228 @@
+# Philosopher Framework Examples
+
+Practical applications of the Philosopher Framework in real development scenarios.
+
+## Example 1: Technology Selection
+
+### Scenario
+Team needs to choose a state management solution for a React application.
+
+### Phase 1: Assumption Audit
+
+Assumptions identified:
+- Assumption 1: Application will grow significantly in complexity
+  - Confidence: Medium
+  - Risk if wrong: Over-engineering with heavyweight solution
+
+- Assumption 2: Team is familiar with Redux patterns
+  - Confidence: Low (need to verify)
+  - Risk if wrong: Steep learning curve, slower delivery
+
+- Assumption 3: Performance is critical for this application
+  - Confidence: High (based on requirements)
+  - Risk if wrong: Premature optimization
+
+AskUserQuestion applied:
+- Verified team has 2 developers with Redux experience, 3 without
+- Confirmed application expected to have 50+ components with shared state
+- Clarified performance requirement is for initial load, not state updates
+
+### Phase 2: First Principles Decomposition
+
+Surface Problem: Need state management for React app
+
+First Why: Multiple components need to share and update the same data
+Second Why: Component prop drilling becomes unwieldy at scale
+Third Why: Application has deeply nested component hierarchy
+Root Cause: Need centralized, predictable state access pattern
+
+Constraint Analysis:
+- Hard Constraint: Must work with React 18
+- Soft Constraint: Team preference for familiar patterns
+- Degree of Freedom: Can choose any state management approach
+
+### Phase 3: Alternative Generation
+
+Option A - Redux Toolkit:
+- Pros: Industry standard, extensive ecosystem, DevTools
+- Cons: Boilerplate, learning curve, potentially overkill
+
+Option B - Zustand:
+- Pros: Minimal boilerplate, easy to learn, lightweight
+- Cons: Smaller ecosystem, less structured for large apps
+
+Option C - React Context + useReducer:
+- Pros: Built-in, no dependencies, familiar React patterns
+- Cons: Performance concerns at scale, no DevTools
+
+Option D - Jotai:
+- Pros: Atomic approach, minimal re-renders, simple API
+- Cons: Different mental model, smaller community
+
+### Phase 4: Trade-off Analysis
+
+Criteria and Weights (confirmed via AskUserQuestion):
+- Learning Curve: 25% (team has mixed experience)
+- Scalability: 25% (app expected to grow)
+- Performance: 20% (important but not critical)
+- Ecosystem: 15% (tooling matters)
+- Bundle Size: 15% (initial load is priority)
+
+Scores:
+- Redux Toolkit: Learning 5, Scale 9, Perf 7, Eco 9, Size 5 = 7.0
+- Zustand: Learning 9, Scale 7, Perf 8, Eco 6, Size 9 = 7.8
+- Context: Learning 8, Scale 5, Perf 5, Eco 5, Size 10 = 6.5
+- Jotai: Learning 7, Scale 8, Perf 9, Eco 5, Size 8 = 7.4
+
+### Phase 5: Cognitive Bias Check
+
+Anchoring: Initial instinct was Redux due to familiarity - verified alternatives genuinely considered
+Confirmation: Actively searched for Zustand limitations and Redux advantages
+Sunk Cost: No prior investment influencing decision
+Overconfidence: Acknowledged uncertainty in scalability predictions
+
+### Recommendation
+
+Selected: Zustand
+Rationale: Best balance of learning curve and scalability given team composition
+Trade-off Accepted: Smaller ecosystem in exchange for faster team productivity
+Mitigation: Plan migration path to Redux if complexity exceeds Zustand capabilities
+Review Trigger: If state logic exceeds 20 stores or requires complex middleware
+
+---
+
+## Example 2: Performance Optimization Decision
+
+### Scenario
+API endpoint is slow (P95: 2 seconds, target: 200ms).
+
+### Phase 1: Assumption Audit
+
+Assumptions identified:
+- Assumption: Database query is the bottleneck
+  - Confidence: Medium (based on intuition)
+  - Risk if wrong: Optimizing wrong component
+
+AskUserQuestion applied:
+- Requested profiling data before proceeding
+- Discovered: 60% time in DB, 30% in serialization, 10% in network
+
+### Phase 2: First Principles Decomposition
+
+Surface Problem: API is slow (2 seconds)
+
+First Why: Response takes too long to generate
+Second Why: Database query returns too much data
+Third Why: Query fetches all columns when only 5 needed
+Fourth Why: Using ORM default select without optimization
+Root Cause: ORM usage pattern not optimized for this use case
+
+### Phase 3: Alternative Generation
+
+Option A - Optimize existing query:
+- Add column selection, indexes
+- Effort: Low, Risk: Low
+
+Option B - Add caching layer:
+- Redis cache for frequently accessed data
+- Effort: Medium, Risk: Low
+
+Option C - Denormalize data:
+- Create read-optimized view
+- Effort: High, Risk: Medium
+
+Option D - Architecture change:
+- Implement CQRS pattern
+- Effort: Very High, Risk: High
+
+### Phase 4: Trade-off Analysis
+
+Given that root cause is query optimization, Option A addresses root cause directly.
+
+Recommendation: Start with Option A, add Option B if insufficient
+
+### Phase 5: Cognitive Bias Check
+
+Avoided availability bias: Did not jump to caching because of recent project
+Avoided overconfidence: Requested profiling data before assuming cause
+
+---
+
+## Example 3: Refactoring Scope Decision
+
+### Scenario
+Legacy module needs updates. Team debates full rewrite vs incremental improvement.
+
+### Phase 1: Assumption Audit
+
+Assumptions identified:
+- Assumption: Full rewrite will take 3 months
+  - Confidence: Low (estimates often wrong)
+  - Risk if wrong: Project overrun
+
+- Assumption: Legacy code is unmaintainable
+  - Confidence: Medium (need metrics)
+  - Risk if wrong: Unnecessary rewrite
+
+AskUserQuestion applied:
+- Requested code metrics (complexity, test coverage, change frequency)
+- Results: 40% test coverage, cyclomatic complexity 25 (high), 3 bugs/month
+
+### Phase 2: First Principles Decomposition
+
+Surface Problem: Legacy module is problematic
+
+First Why: Bugs are frequent and hard to fix
+Second Why: Code is complex and poorly tested
+Third Why: Original design didn't anticipate current requirements
+Root Cause: Design-requirement mismatch accumulated over time
+
+Key insight: Not all parts equally problematic. Core algorithm is solid, interface layer is messy.
+
+### Phase 3: Alternative Generation
+
+Option A - Full rewrite:
+- Start fresh, modern patterns
+- Risk: Second-system effect, feature parity challenges
+
+Option B - Strangler pattern:
+- Gradually replace pieces
+- Risk: Prolonged hybrid state, complexity
+
+Option C - Targeted refactoring:
+- Fix highest-impact areas only
+- Risk: Technical debt remains in untouched areas
+
+Option D - Interface wrapper:
+- Clean interface over legacy internals
+- Risk: Hiding problems, not solving them
+
+### Phase 4: Trade-off Analysis
+
+Decided via AskUserQuestion: Team has 6 weeks available, not 3 months.
+
+Given time constraint, Option C (targeted refactoring) selected.
+Focus areas: Interface layer (source of most bugs), add tests first.
+
+### Recommendation
+
+Approach: Targeted refactoring with test-first approach
+Scope: Interface layer only (60% of bugs, 30% of code)
+Trade-off: Core algorithm technical debt remains
+Mitigation: Comprehensive tests around core algorithm
+Review Trigger: If bug rate doesn't decrease 50% in 2 months
+
+---
+
+## Key Learnings
+
+1. Always verify assumptions with data before major decisions
+2. Root cause analysis often reveals simpler solutions
+3. Time and resource constraints legitimately narrow options
+4. Document trade-offs for future reference
+5. Set clear review triggers for decisions
+
+---
+
+Version: 1.0.0
+Parent Skill: moai-foundation-philosopher

moai_adk/templates/.claude/skills/moai-foundation-philosopher/modules/assumption-matrix.md

@@ -0,0 +1,80 @@
+# Assumption Matrix Module
+
+Deep dive into systematic assumption identification and validation.
+
+## Assumption Categories
+
+### Technical Assumptions
+
+Common technical assumptions to examine:
+- Technology X can handle our scale requirements
+- The API will maintain backward compatibility
+- Performance will be acceptable with chosen approach
+- Integration with existing system will be straightforward
+- Development team has necessary expertise
+
+Validation Methods:
+- Proof of concept implementation
+- Load testing and benchmarking
+- API documentation and changelog review
+- Architecture review with experienced engineers
+- Skill assessment and training gap analysis
+
+### Business Assumptions
+
+Common business assumptions to examine:
+- Users will adopt the new feature
+- Budget will remain available
+- Timeline is realistic
+- Requirements are stable and well-understood
+- Stakeholder priorities are aligned
+
+Validation Methods:
+- User research and feedback sessions
+- Budget confirmation with finance
+- Historical project data comparison
+- Requirements review meetings
+- Stakeholder alignment workshops
+
+### Team Assumptions
+
+Common team assumptions to examine:
+- Team has capacity for this work
+- Skills are available in-house
+- Communication channels are effective
+- Dependencies on other teams are manageable
+- Knowledge transfer is not needed
+
+Validation Methods:
+- Capacity planning review
+- Skills matrix assessment
+- Team retrospective feedback
+- Dependency mapping exercise
+- Documentation audit
+
+## Assumption Documentation Template
+
+For each significant assumption:
+
+Assumption ID: A-001
+Statement: Clear description of what is assumed
+Category: Technical, Business, or Team
+Confidence: High, Medium, or Low
+Evidence: What supports this assumption
+Risk if Wrong: Impact on project if assumption fails
+Validation Plan: How and when to verify
+Owner: Who is responsible for validation
+Status: Unvalidated, Validated, or Invalidated
+
+## Integration with AskUserQuestion
+
+When surfacing assumptions, use AskUserQuestion to:
+- Confirm which assumptions are critical to validate
+- Gather evidence from user's domain knowledge
+- Prioritize assumption validation efforts
+- Determine acceptable risk levels for unvalidated assumptions
+
+---
+
+Version: 1.0.0
+Parent Skill: moai-foundation-philosopher