--- name: philosophy-compliance-workflow version: 1.0.0 description: Philosophy compliance guardian - ensures code aligns with amplihack's ruthless simplicity, brick philosophy, and Zen-like minimalism through systematic review auto_activates: - "philosophy review" - "check philosophy" - "validate architecture" - "simplicity review" - "brick compliance" - "zen review" explicit_triggers: - /amplihack:philosophy-review - /amplihack:zen-check confirmation_required: false token_budget: 2500 --- # Philosophy Compliance Workflow Skill ## Purpose Systematic philosophy compliance review that ensures all code and architecture aligns with amplihack's core principles: ruthless simplicity, brick philosophy, and Zen-like minimalism. This skill validates that implementations serve clear purposes without unnecessary complexity. ## When to Use This Skill **USE FOR:** - Architecture reviews before implementation - Code reviews for philosophy alignment - Refactoring validation (did we actually simplify?) - Module design verification - Pre-merge philosophy checks - Identifying over-engineering and complexity creep **AVOID FOR:** - Functional bug fixes (not philosophy issues) - Performance optimization alone - Documentation updates - Pure syntax/style issues ## Core Philosophy Principles ### The Zen of Simple Code - Each line serves a clear purpose without embellishment - As simple as possible, but no simpler - Complex systems from simple, well-defined components - Handle what's needed now, not hypothetical futures ### The Brick Philosophy - **A brick** = Self-contained module with ONE clear responsibility - **A stud** = Public contract (functions, API, data model) others connect to - **Regeneratable** = Can be rebuilt from spec without breaking connections - **Isolated** = All code, tests, fixtures inside the module's folder ### Ruthless Simplicity - Start with the simplest solution that works - Add complexity only when justified - Question every abstraction - Code you don't write has no bugs ## Review Process ### Step 1: Scope Identification **Identify what to review:** - Single module, multiple modules, or full architecture - Recent changes or complete codebase - Specific complexity concerns or general review **Questions to ask:** - What triggered this review? - What are the main concerns? - What's the expected outcome? ### Step 2: Initial Analysis **Scan the code structure:** - Module organization and boundaries - Public interfaces (the "studs") - Dependencies and coupling - Abstraction layers - Configuration complexity **Red flags to watch for:** - Multiple responsibilities in one module - Unclear module boundaries - Deep inheritance hierarchies - Generic "framework" code - Future-proofing for hypothetical needs ### Step 3: Philosophy Questions **Ask the 5 core questions for each component:** 1. **Necessity**: "Do we actually need this right now?" - Is this solving a real problem today? - Or is it future-proofing for "maybe someday"? 2. **Simplicity**: "What's the simplest way to solve this problem?" - Can we remove layers? - Is there a more direct approach? 3. **Modularity**: "Can this be a self-contained brick?" - Does it have ONE clear responsibility? - Are the connection points (studs) obvious? 4. **Regenerability**: "Can AI rebuild this from a specification?" - Is the contract clear enough? - Are dependencies well-defined? 5. **Value**: "Does the complexity add proportional value?" - What would break if we simplified this? - Is the trade-off justified? ### Step 4: Identify Violations **Categorize issues by severity:** **CRITICAL (Must Fix):** - Multiple responsibilities in one module - Circular dependencies - Unclear public contracts - Non-regeneratable designs - Tight coupling preventing module replacement **WARNING (Should Fix):** - Premature optimizations - Excessive configuration options - Unnecessary abstractions - Generic "framework" patterns - Future-proofing without current need **SUGGESTION (Consider):** - Opportunities for simplification - Alternative approaches with fewer dependencies - Ways to flatten abstraction layers - Module boundary improvements ### Step 5: Generate Review Report **Create structured review output:** ```markdown # Philosophy Compliance Review: [Component Name] ## Overall Score: [A/B/C/D/F] ## Summary [One paragraph overview of findings] ## Strengths (What Aligns) - [Philosophy-aligned patterns identified] - [Well-implemented brick designs] - [Clear simplicity examples] ## Concerns (Warnings) - [Complexity that should be addressed] - [Borderline philosophy violations] - [Opportunities for improvement] ## Violations (Critical Issues) - [Clear departures from philosophy] - [Must-fix problems] - [Blocking issues for philosophy compliance] ## Recommendations ### Immediate Actions (Critical) 1. [Specific fix required with rationale] 2. [Another critical fix] ### Structural Improvements (Important) 1. [Module boundary adjustments] 2. [Decoupling suggestions] ### Simplification Opportunities (Good to Have) 1. [Ways to reduce complexity] 2. [Abstraction removal suggestions] ## Regeneration Assessment **Can AI rebuild these components from specifications?** - Module A: [Ready/Needs Work] - [Specific reason] - Module B: [Ready/Needs Work] - [Specific reason] **What's blocking regeneration:** - [List specific issues preventing clear AI regeneration] ## Philosophy Alignment Score - Ruthless Simplicity: [0-10]/10 - [Rationale] - Brick Philosophy: [0-10]/10 - [Rationale] - Zen Minimalism: [0-10]/10 - [Rationale] **Overall: [Score]/10** ``` ### Step 6: Provide Actionable Guidance **For each violation, provide:** - Clear explanation of the problem - Why it violates philosophy - Specific fix recommendation - Expected improvement from fix - Priority (Critical/Important/Nice-to-have) **Example:** ``` Issue: SessionManager class has 8 different responsibilities Violation: Breaks single responsibility (brick philosophy) Fix: Split into: - SessionStore (persistence only) - SessionValidator (validation only) - SessionLifecycle (creation/expiry only) Impact: Each brick becomes regeneratable and testable independently Priority: Critical ``` ## Philosophy Scoring Rubric ### Ruthless Simplicity (0-10) - **10**: Every component serves clear purpose, minimal complexity - **8-9**: Generally simple with minor complexity creep - **6-7**: Some unnecessary abstractions or future-proofing - **4-5**: Significant over-engineering present - **0-3**: Complex beyond necessity, hard to understand ### Brick Philosophy (0-10) - **10**: All modules self-contained with clear single responsibility - **8-9**: Most modules follow brick pattern with minor coupling - **6-7**: Some unclear boundaries or multiple responsibilities - **4-5**: Significant coupling and unclear contracts - **0-3**: Monolithic or tightly coupled, not regeneratable ### Zen Minimalism (0-10) - **10**: Embraces simplicity, handles only current needs - **8-9**: Mostly minimal with some extra features - **6-7**: Some hypothetical futures addressed unnecessarily - **4-5**: Considerable future-proofing and "just in case" code - **0-3**: Over-engineered for "maybe someday" scenarios ### Overall Grade - **A (9-10)**: Excellent philosophy alignment - **B (7-8)**: Good with minor improvements needed - **C (5-6)**: Acceptable but needs attention - **D (3-4)**: Poor alignment, significant refactoring needed - **F (0-2)**: Critical philosophy violations throughout ## Green Patterns (Examples of Good Design) **Philosophy-Aligned Designs:** - Single-responsibility modules with clear purpose - Self-contained directories with all code and tests - Obvious public interfaces (studs) for connections - Direct, straightforward implementations - Minimal dependencies (preferring standard library) **Example: Good Brick Module** ``` authentication/ ├── __init__.py # Exports: authenticate, validate_token ├── core.py # Implementation (one responsibility) ├── models.py # User, Token (clear data models) ├── tests/ │ └── test_core.py # Comprehensive tests └── README.md # Regeneration specification Public Contract (Studs): - authenticate(username, password) -> Token - validate_token(token) -> User One Responsibility: Authentication only (not authorization, not user management) Regeneratable: Yes, from README.md specification ``` ## Red Patterns (Examples to Avoid) **Philosophy Violations:** - God objects with multiple responsibilities - Abstract base classes without clear justification - Complex configuration systems for simple features - Generic "flexible" frameworks - Premature performance optimizations **Example: Bad Design** ``` user_system/ ├── framework.py # Generic abstraction layer ├── manager.py # UserManager does everything ├── config/ # Extensive config system ├── plugins/ # Plugin architecture (unused) └── adapters/ # Future-proofing for other DBs Problems: - UserManager handles auth, profile, settings, notifications - Framework adds complexity without current value - Plugin system built for "maybe someday" - Multiple responsibilities, not regeneratable ``` ## Integration with Other Workflows **When to combine philosophy review with:** - **After Builder**: Validate implemented code follows philosophy - **Before Architect**: Ensure design specs embrace simplicity - **During Reviewer**: Include philosophy as review criteria - **With Cleanup**: Identify what to simplify/remove **Default workflow position:** - Architecture Phase: Before implementation starts - Code Review Phase: After implementation, before merge - Refactoring Phase: Validate simplification efforts ## Key Mantras - "It's easier to add complexity later than to remove it" - "Code you don't write has no bugs" - "Favor clarity over cleverness" - "The best code is often the simplest" - "Modules should be bricks: self-contained and regeneratable" - "Do we need this NOW, or are we future-proofing?" - "What's the simplest thing that could possibly work?" ## Common Pitfalls **Disguised Complexity:** - "This makes it flexible" → Often means over-engineered - "We might need this later" → Future-proofing without current need - "This is more generic" → Generic often means complex - "Industry best practice" → May not apply to your scale **Philosophy Traps:** - Adding abstraction layers "just in case" - Building frameworks for single use cases - Creating plugin systems before needing plugins - Optimizing before measuring performance - Designing for hypothetical scale ## Success Criteria A successful philosophy review: - [ ] Identifies all critical philosophy violations - [ ] Provides actionable fix recommendations - [ ] Explains why violations matter - [ ] Scores components objectively - [ ] Validates regeneration readiness - [ ] Celebrates philosophy-aligned patterns - [ ] Guides team toward simpler designs ## Output Artifacts **Generated documents:** - Philosophy review report (markdown) - Action items with priorities - Before/after comparison (if fixes applied) - Regeneration assessment per module **Where to save:** - `~/.amplihack/.claude/runtime/logs//philosophy_review_.md` - Link in commit message if fixes applied - Store patterns learned in memory using `store_discovery()` from `amplihack.memory.discoveries` ## Remember You are the philosophical conscience of the system. Challenge complexity, celebrate simplicity, and ensure every architectural decision moves toward the Zen ideal of elegant, essential software. **Your goal is not perfection - it's continuous improvement toward simpler, clearer, more regeneratable code.**