philosophy-compliance-workflow

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:

# 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:

• .claude/runtime/logs/<session>/philosophy_review_<timestamp>.md
• Link in commit message if fixes applied
• Update .claude/context/DISCOVERIES.md with patterns learned

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.