| name | torvalds-building-principles |
| description | Software development planning enhancement using Linus Torvalds' design philosophy. Triggered by phrase "using Torvalds Building Principles" or "Linus Torvalds Building Principles". Analyzes software plans, technical specifications, codebases, or architecture documents against twelve dimensions derived from Torvalds' 30+ year career (Linux kernel, Git). Dimensions include data-structures-first, never-break-userspace, core-simplicity, good-taste-code, minimal-abstraction, performance-by-design, explicit-over-hidden, function-focus, chain-of-trust, release-early, and merit-over-politics. Outputs README_LT.md with scored assessment and enhanced plan. Use when user submits software design documents, API specifications, codebases, or technical architectures requesting Torvalds-style assessment. Specializes in "data structures and their relationships" philosophy. |
Torvalds Building Principles
Enhance software development plans by applying Linus Torvalds' design philosophy—where data structures drive design, userspace stability is sacred, core simplicity enables surface complexity, and good taste eliminates special cases.
Activation
Trigger: "using Torvalds Building Principles" or "Linus Torvalds Building Principles" with a software plan/specification/codebase.
Workflow
1. RECEIVE software plan, technical spec, API design, or codebase
2. READ references/design-philosophy.md (core methodology)
3. ASSESS Tier 1 Foundations (Data-Structures-First, Never-Break-Userspace, Core-Simplicity) - score 1-5 each
4. READ references/coding-principles.md
5. ASSESS Code Quality dimensions (Good-Taste, Minimal-Abstraction, Explicit-Over-Hidden) - score 1-5 each
6. READ references/technical-principles.md
7. ASSESS Technical dimensions (Performance-By-Design, Data-Integrity, Function-Focus) - score 1-5 each
8. READ references/process-principles.md
9. ASSESS Process dimensions (Chain-Of-Trust, Release-Early, Merit-Over-Politics) - score 1-5 each
10. IDENTIFY enhancements for any dimension < 3
11. READ references/output-template.md
12. GENERATE README_LT.md with analysis + enhanced plan
Core Insight
Torvalds' methodology: "Bad programmers worry about the code. Good programmers worry about data structures and their relationships." Data drives design. Stability contracts are sacred. Core simplicity enables surface complexity. Constraints clarify rather than limit.
Torvalds' Statement: "If a change results in user programs breaking, it's a bug in the kernel. We never EVER blame the user programs."
The Test: If APIs might break users, redesign. If code needs special cases, find better abstractions. If understanding requires a debugger, simplify. If internal complexity leaks externally, refactor.
Dimension Overview
| # | Dimension | Key Question |
|---|
| 1 | Data-Structures-First | Do data structures drive design decisions? |
| 2 | Never-Break-Userspace | Are external API contracts immutable? |
| 3 | Core-Simplicity | Does a simple core support complex capabilities? |
| 4 | Good-Taste-Code | Does the code naturally handle edge cases without special logic? |
| 5 | Minimal-Abstraction | Are abstractions justified by explicit current requirements? |
| 6 | Explicit-Over-Hidden | Is control flow transparent and allocation visible? |
| 7 | Performance-By-Design | Is performance a core requirement, not an afterthought? |
| 8 | Data-Integrity | Is corruption prevention prioritized over features? |
| 9 | Function-Focus | Do functions do one thing, fit on a screen, and stay shallow? |
| 10 | Chain-Of-Trust | Is there hierarchical ownership with clear accountability? |
| 11 | Release-Early | Is working code shipped before it's "complete"? |
| 12 | Merit-Over-Politics | Do technical arguments determine outcomes? |
Priority Tiers
Tier 1 (Foundational): Without these, the "Torvalds approach" cannot exist
- Data-Structures-First (data drives design)
- Never-Break-Userspace (external stability)
- Core-Simplicity (simple foundations)
Tier 2 (Code Quality): Define implementation excellence
- Good-Taste-Code
- Minimal-Abstraction
- Explicit-Over-Hidden
Tier 3 (Technical Excellence): Shape system characteristics
- Performance-By-Design
- Data-Integrity
- Function-Focus
Tier 4 (Process Excellence): Organizational principles
- Chain-Of-Trust
- Release-Early
- Merit-Over-Politics
Quick Assessment
Tier 1 Foundations (assess first):
- Data-Structures-First: 5=data model fully specified before code; 3=partial data-driven design; 1=code-first development
- Never-Break-Userspace: 5=external APIs immutable with deprecation paths; 3=most breaking changes avoided; 1=frequent breaking changes
- Core-Simplicity: 5=few primitives combine for all capabilities; 3=some simple core; 1=special interfaces for everything
If Tier 1 average < 3: Highest priority. All other improvements depend on foundational architecture.
The Data Structures Principle
Torvalds' signature insight—good programmers focus on data, not code:
Bad programmer: Write code, retrofit data structures
Good programmer: Design data structures, code follows naturally
Result: 50% less code, clearer logic, easier maintenance
Apply to: Any software design. Ask: "What are the data structures and their relationships? How does the data flow?"
The Good Taste Protocol
Every piece of code should eliminate special cases through better abstraction:
| Poor Taste | Good Taste | Principle |
|---|
if (head) else if (middle) else (tail) | Indirect pointer handles all | Unify cases |
| Explicit edge case handling | Algorithm naturally handles edges | Find better abstraction |
| Comments explaining tricky code | Self-evident code | Simplify |
| Defensive null checks everywhere | Impossible states unrepresentable | Design out errors |
Test: Does this code have an if-statement that could be eliminated with a better abstraction?
The Never-Break-Userspace Rule
External stability enables internal flexibility:
- External APIs: Immutable once published
- Internal APIs: Free to change
- Deprecation: Warn, provide migration path, maintain compatibility
- Versioning: Not about features, about stability contracts
"If you cannot upgrade [the system] without upgrading [user code], that should be considered a real bug."
References
Constraints
- Data structures first: Design around data, code follows
- External stability required: Never break userspace
- Core simplicity: Few primitives, many capabilities
- Good taste: Eliminate special cases through abstraction
- Minimal abstraction: No hypothetical future requirements
- Explicit control: No hidden allocations or magic
- Performance matters: Speed is a feature, not an optimization
- Functions focused: One thing, one screen, shallow depth
- Preserve creator vision: Amplify intent, don't replace style
The Ultimate Test
Design achieves Torvalds integration when:
- Data structures are documented before algorithms
- External APIs haven't broken in years
- Core concepts fit in one paragraph
- Edge cases are handled by algorithm, not conditionals
- Every abstraction serves a current, concrete need
- No hidden allocations or control flow
- Performance is measurable and monitored
- Functions fit on screen with < 3 indentation levels
- Ownership hierarchy is clear and accountable
- Working code ships before it's "perfect"
- Technical arguments determine outcomes
- Engineers say "obvious" and users say "stable"
