software-design-philosophy

Reduce software complexity by applying deep module principles, hiding implementation details behind simple interfaces to prevent change amplification and cognitive load. The Skill diagnoses interface bloat and guides refactoring boundaries using a 0–10 scoring rubric for abstraction quality.

A deep module in software design provides a simple interface that hides significant implementation complexity, enforcing information hiding across module boundaries. This approach prevents design decisions from leaking, reduces unknown unknowns, and avoids shallow pass-through designs that shift complexity to the caller.

Score and review API design for interface bloat using the Skill's 0–10 rubric, which evaluates whether an abstraction earns its interface complexity. It checks for red-flag diagnostics like classitis and pass-through methods, applying comment-driven design rules to capture intent and assumptions code cannot express.

Choose strategic programming over tactical programming to invest 10–20% of development time in design quality, preventing compounding technical debt. Tactical programming focuses on immediate features, whereas the strategic approach prioritizes deep modules and information hiding to manage long-term system complexity.

Common symptoms of software complexity include change amplification, where simple modifications require multiple code changes, cognitive load that limits developer understanding, and unknown unknowns where existing code behavior is unclear. The Skill identifies these red flags during design reviews and API boundary analysis.

Yes, you can use this approach to decide between general-purpose and special-purpose abstractions by evaluating deep-vs-shallow tradeoffs. The Skill provides concrete principles and red-flag diagnostics to determine if a general-purpose abstraction hides enough complexity to justify its broader interface over a specialized design.