software-design-philosophy

SKILL.md

A Philosophy of Software Design Framework

A practical framework for managing the fundamental challenge of software engineering: complexity. Apply these principles when designing modules, reviewing APIs, refactoring code, or advising on architecture decisions.

Core Principle

The greatest limitation in writing software is our ability to understand the systems we are creating. Complexity is the enemy: it makes systems hard to understand, hard to modify, and a source of bugs. Evaluate every design decision by asking "Does this increase or decrease the overall complexity of the system?" — the goal is not zero complexity, but minimizing unnecessary complexity and concentrating the necessary kind where it can be managed.

Scoring

Goal: 10/10. When reviewing or creating a design, score it by counting how many of the eight Quick Diagnostic rows it satisfies (≈1.25 points each), then sanity-check against the bands:

9-10 — deep modules with interfaces far simpler than implementations; no information leakage (an implementation can change without touching callers); interface comments capture design intent; design improvement is routine. All eight diagnostics pass.

6-8 — mostly deep, but one or two leaks, shallow classes, or undocumented abstractions. 5-6 diagnostics pass.

3-5 — classitis or temporal decomposition, recurring leakage, comments that only restate code. 2-4 diagnostics pass.

≤2 — tactical-tornado code: shallow modules, pervasive leakage, no design intent recorded. 0-1 diagnostics pass.

Always state the current score, the diagnostic rows that failed, and the specific change each one needs to reach 10/10.