| name | build-philosophy |
| description | Comprehensive build philosophy including system awareness, MIP for code, decision frameworks, and wisdom paths. Prevents accumulative complexity through systematic thinking. |
| allowed-tools | * |
| triggers | ["build philosophy","system awareness","code complexity","minimal intervention","ripple mapping","UNDERSTAND SHAPE ACT","essential complexity","accumulative complexity"] |
===SKILL:BUILD_PHILOSOPHY===
META:
TYPE::SKILL
VERSION::"2.0"
PURPOSE::"Comprehensive build philosophy framework preventing accumulative complexity"
SOURCE::"Consolidated from ~/.claude/skills/build-execution/*.oct.md"
§1::SYSTEM_AWARENESS_MANDATE
CORE_PRINCIPLE::"Code change → System ripple → Understand ripples BEFORE modification"
SYSTEM_THINKING::[
MAP_IMPACT::[
"Trace all imports/uses of changed code",
"Follow data flow dependencies",
"Identify shared state impacts",
"Document ripple paths explicitly"
],
LOCAL_CHANGE_SYSTEM_CONTEXT::"Simple edit can break distant components - think globally",
LOCAL_OPTIMIZATION_DEGRADES::"Faster function ≠ better system if breaks caching",
MINIMAL_CODE_SERVES::"Essential complexity serves users, accumulative serves maintenance burden"
]
MAINTAIN_LIVING_SYSTEM::"Not editing text files - every change affects production"
§2::MINIMAL_INTERVENTION_PRINCIPLE
DEFINITION::[
ESSENTIAL::"Code serving measurable user value",
ACCUMULATIVE::"Code adding maintenance burden without proportional user value"
]
DECISION::"Could we achieve same outcome with simpler means?"
PROCESS::"Remove components until UX degrades → identify break point → restore last essential → minimal achieved"
ENFORCEMENT::[
JUSTIFICATION::"User problem? Why not extend existing? Simplification test?",
EVIDENCE::"What removed? Break point found? Minimal restoration done?",
SIGNOFF::"Reviewer verifies minimality credible, no obvious bloat"
]
§3::PHILOSOPHY_FRAMEWORK
UNDERSTAND_SHAPE_ACT::[
UNDERSTAND::[
"What is the user problem?",
"System connections and dependencies?",
"Core assumptions and invariants?",
"WARNING: 'just try this', 'probably works', 'not sure how'"
],
SHAPE::[
"Simplest solution satisfying requirements",
"Obvious to future readers (6mo test)",
"Easy test isolation",
"Minimal coupling",
"PATTERNS: proven>novel, simple>clever, explicit>implicit"
],
ACT::[
"TDD: failing test first",
"Implement minimal solution",
"Refactor for essential simplification only",
"Commit atomically",
"SCOPE: requested ≠ while_here, one concern per commit"
]
]
WISDOM_PATH::[
BETWEEN::"Complexity labyrinth ← minimal effective → Oversimplification sea",
AVOID_LABYRINTH::"Over-abstracted, premature generalization, unjustified patterns",
AVOID_OVERSIMPLIFICATION::"Unjustified duplication, skipping necessary abstractions",
MINIMAL_EFFECTIVE::[
"Just enough abstraction to prevent duplication",
"Just enough flexibility to handle known variations",
"Just enough structure to maintain coherence"
]
]
§4::DECISION_GATES
BEFORE_CODE::[
"Is this solving a user problem?",
"Can we extend existing components?",
"Is this feature explicitly requested?",
"Are we solving a problem that doesn't exist yet?",
"IF accumulative → DON'T ADD"
]
BEFORE_ABSTRACTION::[
"Rule of Three: 1st concrete → 2nd copy → 3rd abstract",
"Does it reduce cognitive load?",
"Is it understandable without docs?",
"Cost if requirements change?",
"IF mysterious → KEEP CONCRETE"
]
BEFORE_OPTIMIZATION::[
"Is this a measured bottleneck?",
"Have we profiled first?",
"Is the gain measured?",
"PROFILE FIRST → IF not measured → DON'T OPTIMIZE"
]
BEFORE_TESTS::[
"Does this test user-facing behavior?",
"Does it validate component contract?",
"Will it catch real bugs?",
"Testing behavior not implementation?",
"IF not user-facing → RECONSIDER"
]
BEFORE_REFACTOR::[
"Does this improve clarity?",
"Does it reduce complexity?",
"Are tests still green?",
"Will it make future changes easier?",
"SAFETY: small steps, test after each, revert if fail",
"IF behavior changes → NOT REFACTORING, IT'S A FEATURE"
]
§5::PRACTICAL_EXAMPLES
RIPPLE_MAP_EXAMPLE::[
CHANGE::"processUser(id) → processUser(user)",
DIRECT::"10 files need to pass user object",
INDIRECT::"Tests need fixtures not IDs, API needs hydration, caching changes",
FLOW::"DB queries move to callers, N+1 risk emerges",
OUTCOME::"Simple signature change → 20 files + performance testing + staged migration"
]
WITH_WITHOUT_PHILOSOPHY::[
REQUEST::"Add PDF export",
WITHOUT::"Add library → create service → endpoint → ship = 500 lines untested",
WITH::[
"UNDERSTAND: Who? Why? How often? → 1 user, monthly report, using screenshots now",
"SHAPE: Screenshot API suffices → 10 lines",
"ACT: TEST → IMPLEMENT → TEST → DOCUMENT = 50 lines tested, solves actual need"
]
]
§6::WISDOM
CORE_TRUTH::"Code change = system change. Think systemically + Code minimally + Verify rigorously"
QUALITY_HIERARCHY::[
BEST::"Code you don't write",
SECOND::"Code that is obvious, testable, and minimal"
]
RIPPLE_AWARENESS::"Between isolated edit (wrong) and system paralysis (wrong) lies systematic local change with global awareness"
===END===
