torvalds-building-principles

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:

1. External APIs: Immutable once published
2. Internal APIs: Free to change
3. Deprecation: Warn, provide migration path, maintain compatibility
4. 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

• Core methodology: See references/design-philosophy.md
• Coding principles: See references/coding-principles.md
• Technical principles: See references/technical-principles.md
• Process principles: See references/process-principles.md
• Assessment protocol: See references/assessment-protocol.md
• Output format: See references/output-template.md
• Full research report: See references/torvalds-research-report.md

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:

1. Data structures are documented before algorithms
2. External APIs haven't broken in years
3. Core concepts fit in one paragraph
4. Edge cases are handled by algorithm, not conditionals
5. Every abstraction serves a current, concrete need
6. No hidden allocations or control flow
7. Performance is measurable and monitored
8. Functions fit on screen with < 3 indentation levels
9. Ownership hierarchy is clear and accountable
10. Working code ships before it's "perfect"
11. Technical arguments determine outcomes
12. Engineers say "obvious" and users say "stable"