software-design-philosophy

Name: software-design-philosophy
Availability: InStock
Author: Taylor Bell

Reviews software designs for complexity using deep modules, information hiding, and strategic programming principles.

Updated Jun 24, 2026

Search Tags:#architecture #code review #refactoring #software design #modularity #complexity #information hiding

Ready to run

npx skills add https://github.com/tayiorbeii/paperclip-factory-kit-hermes --skill software-design-philosophy-tayiorbeii

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: software-design-philosophy
Source: https://github.com/tayiorbeii/paperclip-factory-kit-hermes/tree/main/skills/paperclip/software-design-philosophy
Command: npx skills add https://github.com/tayiorbeii/paperclip-factory-kit-hermes --skill software-design-philosophy-tayiorbeii

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Software systems accumulate complexity through hundreds of small design decisions, making them hard to understand, modify, and debug. This Skill provides a structured framework based on John Ousterhout's "A Philosophy of Software Design" to diagnose complexity, evaluate module designs, and guide refactoring decisions with a 0-10 scoring rubric. ## Core Features & Use Cases - Complexity Diagnosis: Identifies change amplification, cognitive load, and unknown unknowns caused by dependencies and obscurity. - Module Design Review: Evaluates deep vs shallow modules, information hiding and leakage, and general-purpose vs special-purpose interfaces. - Design Documentation Guidance: Applies comment-driven design and strategic vs tactical programming principles to keep codebases maintainable. - Use Case: When reviewing a pull request that adds three thin wrapper classes around file I/O, use this Skill to identify classitis, recommend merging them into one deep module, and score the design against the framework. ## Quick Start Ask the AI to review your module or API design using the software design philosophy framework and score it from 0 to 10 with specific improvements.

Frequently Asked Questions about software-design-philosophy

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I review a module design for complexity?▼

Evaluate the ratio of functionality to interface complexity: deep modules hide significant implementation behind simple interfaces, while shallow modules leak complexity outward. Check for change amplification, cognitive load, and unknown unknowns, then score the design 0-10 against the framework's principles.

What is a deep module vs a shallow module?▼

A deep module provides powerful functionality behind a simple interface, like Unix file I/O. A shallow module has a complex interface relative to what it does, such as thin wrapper classes that just pass calls through. Depth matters more than method or class size.

How do I detect information leakage in code?▼

Information leakage appears when the same design knowledge is reflected in multiple modules, such as shared data formats, protocols, or temporal decomposition splitting related logic across phases. Fix it by encapsulating the knowledge in a single module or merging the affected modules.

When should I choose general-purpose over special-purpose interfaces?▼

Choose a somewhat general-purpose interface when it covers all current needs with fewer special cases, such as one store(key, value) method instead of per-entity methods. Avoid over-generalization; the key question is what is the simplest interface covering current needs.

What are the limitations of self-documenting code?▼

Self-documenting code only conveys low-level what, not why, design alternatives, or assumptions. Interface comments capturing the abstraction are essential; write them before the code using comment-driven design and keep them updated as the code evolves.