Unix Review

Evaluate codebases against the Unix philosophy and SOLID principles, with a novel AI-Readiness dimension for the age of AI-assisted development.

Philosophy

Code Quality = f(Codebase, Architecture Type, Team Context, AI Collaboration)

The Unix philosophy—born from decades of building systems that survive—remains the most battle-tested framework for software design. Eric Raymond distilled it into 17 rules. SOLID principles complement them at the object/module level. Together they form a complete lens for evaluating code.

But we add a new dimension: AI-Readiness. Code that AI agents can navigate, understand, and safely modify is not a luxury—it's a competitive advantage. The same properties that make code good for humans (clarity, modularity, separation of concerns) make it good for AI, but AI has specific needs around context windows, file independence, and composable interfaces.

We collapse 17 Unix rules + 5 SOLID principles into 8 scoreable dimensions to avoid overwhelming output while preserving full analytical coverage.

Quick Start

Quick Scan: Reconnaissance → Score 8 dimensions → Top 5 recommendations Deep Review: Full file analysis → Dimensional scoring with exemplars/violations → Architecture profile → Detailed remediation AI-Readiness Audit: Focus on AI-Readiness sub-scores with specific remediation

Operating Modes

Mode 1: Quick Scan (default)

When: User says "review," "evaluate," or "how's this codebase?"

Process:

1. Reconnaissance (2-3 min exploration)
   • Read project structure, entry points, config files
   • Sample 5-8 representative files across the codebase
   • Identify architecture type
2. Score all 8 dimensions (0-100)
3. Output architecture profile with top 5 recommendations

Mode 2: Deep Review

When: User says "deep review," "full audit," or "thorough analysis"

Process:

1. Reconnaissance (thorough exploration)
   • Map full project structure
   • Read all key files, not just samples
   • Trace dependency chains
   • Analyze test coverage patterns
2. Score all 8 dimensions with exemplar files and violation citations
3. Diagnose dimension gaps
4. Output full architecture profile with detailed remediation plan

Mode 3: AI-Readiness Audit

When: User says "AI readiness," "agent friendly," or "how AI-ready is this?"

Process:

1. Standard reconnaissance
2. Deep-dive on AI-Readiness sub-scores:
   • Navigability, Contextual Independence, Modifiability, Agent Composability, Inspectability
3. Load references/ai-readiness.md
4. Output AI-readiness focused report with specific file-level recommendations

Three-Phase Workflow

Phase 1: Reconnaissance

Before scoring, understand the terrain:

1. Structure scan: tree or glob patterns to map the project
2. Entry points: Find main files, CLI entry, server bootstrap
3. Architecture type detection:
   • CLI Tool
   • Library/SDK
   • Web Application
   • Microservice/API
   • AI/ML Pipeline
   • Monorepo/Multi-package
4. Sample files: Read representative files across layers (entry, core logic, utilities, tests, config)
5. Dependency analysis: Check package manifest, imports, coupling patterns

Phase 2: Dimensional Scoring

Score each dimension 0-100. Load references/scoring-rubric.md for calibration.

The 8 Dimensions:

For each dimension, identify:

• Exemplar: Best file/module demonstrating this principle (with path:line)
• Violation: Worst offender against this principle (with path:line)
• Score rationale: 1-2 sentence justification

Phase 3: Synthesis

1. Apply architecture-type calibration weights (load references/scoring-rubric.md)
2. Compute weighted overall score
3. Diagnose dimension gaps (high X + low Y = specific problem)
4. Generate top 5 actionable recommendations ranked by impact
5. Format output

Architecture-Type Calibration

Different architectures emphasize different dimensions:

AI-Readiness Sub-Scores

AI-Readiness breaks into 5 sub-criteria (each 0-100, averaged for dimension score):

Load references/ai-readiness.md for detailed criteria and anti-patterns.

Dimension Gap Diagnostics

Certain dimension combinations reveal specific architectural problems:

Output Format

UNIX REVIEW — ARCHITECTURE PROFILE

Project: [name]
Architecture: [detected type] | Calibration: [applied]
Files analyzed: [N] | Lines of code: [~N]

DIMENSIONAL SCORES:
       Modularity: ████████░░ 82 - [Brief interpretation]
    Composability: ██████░░░░ 63 - [Brief interpretation]
         Clarity: █████████░ 91 - [Brief interpretation]
      Simplicity: ███████░░░ 74 - [Brief interpretation]
      Robustness: ██████░░░░ 58 - [Brief interpretation]
  Data-Drivenness: █████░░░░░ 48 - [Brief interpretation]
   Extensibility: ████████░░ 79 - [Brief interpretation]
    AI-Readiness: ███████░░░ 71 - [Brief interpretation]

OVERALL: ████████░░ 73 (Architecture-weighted)

DIMENSION GAP DIAGNOSIS:
[Diagnostic based on score patterns — e.g., "High clarity but low
data-drivenness suggests logic encoded in control flow rather than
data structures. Consider configuration-driven approaches."]

EXEMPLARS (Best Practices Found):
1. [path:line] — [What it does well and which dimension]
2. [path:line] — [...]
3. [path:line] — [...]

VIOLATIONS (Highest Impact):
1. [path:line] — [What principle it violates and why it matters]
2. [path:line] — [...]
3. [path:line] — [...]

AI-READINESS DETAIL:
      Navigability: ████████░░ 80
  Context Independence: ██████░░░░ 65
     Modifiability: ███████░░░ 72
  Agent Composability: ██████░░░░ 60
    Inspectability: ████████░░ 78

TOP 5 RECOMMENDATIONS:
1. [Most impactful, actionable fix with specific files]
2. [...]
3. [...]
4. [...]
5. [...]

Scoring Philosophy

• Be calibrated, not generous. 70 is genuinely good. 90+ is exceptional. 50 means real problems.
• Architecture type matters. A CLI tool doesn't need the composability of a library.
• Dimension gaps are diagnostic. The pattern of scores reveals more than any single number.
• Cite specific files. Every exemplar and violation must reference actual code with path:line.
• Recommendations must be actionable. "Improve modularity" is useless. "Extract the validation logic from src/handlers/auth.ts:45-120 into a separate module" is actionable.

Reference Files

Load as needed:

• references/unix-rules.md — All 17 ESR rules with code smells and exemplar patterns
• references/solid-principles.md — 5 SOLID principles mapped to the 8 dimensions
• references/scoring-rubric.md — Score bands, architecture weights, diagnostic combos, calibration examples
• references/ai-readiness.md — AI-age thesis, sub-criteria detail, anti-patterns

Critical Principles

1. Reconnaissance Before Judgment. Never score without reading code. Sample broadly.
2. Architecture-Type Calibration Is Non-Negotiable. A microservice and a CLI have different priorities.
3. Dimension Gaps Are Diagnostic. The pattern matters more than the average.
4. Cite or It Didn't Happen. Every claim must reference specific files and lines.
5. Actionable Over Exhaustive. Five concrete recommendations beat twenty vague observations.
6. The Unix Way Is Pragmatic. Rules are heuristics, not laws. Flag violations but acknowledge justified exceptions.
7. AI-Readiness Is About Structure, Not Comments. Good structure for AI means good structure for humans—but the reverse isn't always true.
8. Score the Code, Not the Idea. Evaluate implementation quality, not whether the project concept is good.