Software design philosophy guide based on John Ousterhout's "A Philosophy of Software Design."
SkillScore95Maintained
Automatic
◆Coding pack
Last verified 8/21/2026
What it changes
Passed 21 of 22 test cases with the skill, and 15 of 22 without it.
Without skill68%
With skill95%
Checks it passed that the model alone missed
Identifies this issue as conjoined methods.
Identifies Option 1 as exposing shallow modules.
Evaluates Approach A as exhibiting temporal decomposition.
and 7 more in the full report
7 fixed14 passed either way0 still failing1 broke
Pass-rate lift
+27 pp
Tokens
+110%
Agent turns
0%
Response time
-15%
Model gemini-3.6-flashMeasured 8/21/2026v121 of 22 cases passed with skill
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 7 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 7
Prompt
In an e-commerce checkout library, calling `calculate_tax()` causes runtime errors unless `initialize_cart_context()` and `apply_discounts()` were invoked in that exact order previously, though this dependency is not enforced by signatures. What design red flag is present?
What was checked, without and with the skill
Checked
Without skill
With skill
Identifies this issue as conjoined methods.
Missed
Passed
Recommends consolidating the coupled calls inside a single interface method.
Passed
Passed
case-19 · gemini-3.6-flash · 8/21/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md279 linessingle file
A Philosophy of Software Design — Distilled Guide
Source: John Ousterhout, A Philosophy of Software Design
Central thesis: The core challenge of software design is managing complexity.
I. Complexity: Know the Enemy
Definition
Complexity is anything related to the structure of a software system that makes it hard to understand and modify. Complexity is not the same as system size — a small system can be complex, and a large well-designed system can be manageable.
Three Symptoms of Complexity
Change Amplification: A seemingly simple change requires code modifications in many different places.
Cognitive Load: Developers must absorb a large amount of information to complete a task safely. Note: fewer lines of code ≠ simpler — sometimes more code is actually simpler because it reduces cognitive load.
Unknown Unknowns: It's unclear which code must be modified or what information is needed to complete a task. This is the most dangerous symptom.
Two Root Causes
Dependencies: A piece of code cannot be understood or modified in isolation; it relates to other code that must also be considered.
Obscurity: Important information is not obvious — vague names, missing docs, implicit conventions, hidden constraints.
Key Insight
Complexity is incremental: It's not caused by a single catastrophic error; it accumulates through thousands of small decisions.
Therefore you must adopt a zero-tolerance mindset — every bit of "minor" complexity matters.
II. Strategic vs. Tactical Programming
Tactical Programming (Anti-pattern)
Goal: get features working as quickly as possible.
Mindset: "Just make it work", "We'll refactor later."
Result: complexity accumulates fast, tech debt spirals out of control.
Strategic Programming (Recommended)
Goal: produce great design; working code is a byproduct.
Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, clean up legacy code, eliminate code smells, or improve code maintainability. This skill guides through a phased approach with research, planning, and safe incremental implementation.