philosophy-compliance-workflow

What this skill does

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