Adding Reference Mindsets
Reference mindsets are philosophical foundations for simplicity. They explain why less is more, giving agents deeper calibration beyond the mechanical checkpoints.
Where They Live
Mindsets live in @reference/. Each is a standalone file named by concept.
File Structure
---
description: One-sentence summary of the core insight and why it matters.
---
# Concept Name
## The Core Insight
The central idea in 1-2 sentences. Quotable. Memorable.
## Why This Matters
How this connects to avoiding complexity. Why an LLM should care.
What goes wrong when you ignore this principle.
## Practical Application
Concrete questions to ask or checks to apply.
How to use this mindset when evaluating design options.
## External References
Links to primary sources - talks, papers, books that originated or best explain this concept.Quality Checklist
Before adding a mindset:
- Counters over-engineering? Does it help resist the urge to add?
- Distinct from existing? Not redundant with current mindsets
- Concise? Can be explained in under 50 lines
- Memorable core insight? Has a quotable central principle
- Named by concept? Not by person or source
Good Candidates
Ideas that would make strong mindsets:
| Concept | Core Insight |
|---|---|
worse-is-better |
Shipping a simple thing beats perfecting a complex one |
essential-vs-accidental |
Most complexity is accidental and can be eliminated |
locality-of-behavior |
Code should be understandable without jumping around |
boring-technology |
Innovation tokens are limited; use boring tech by default |
separation-of-concerns |
Each piece should have one reason to change |
rule-of-three |
Don't abstract until you've seen the pattern three times |
What NOT to Add
Technology-specific advice → Belongs in project docs or tech-specific skills
- "React components should..."
- "In Rust, prefer..."
Process/workflow rules → Belongs in skills, not mindsets
- "Always run tests before..."
- "Use TDD when..."
Vague platitudes → If there's no actionable insight, skip it
- "Write clean code"
- "Think before you code"
Anything requiring context → Mindsets should be universal
- "In microservices architectures..."
- "When working with legacy code..."
The Test
A good mindset should help an agent answer: "Should I add this abstraction?"
If the mindset doesn't directly inform that question, it probably belongs somewhere else.
Source Material
Primary sources for simplicity thinking. Draw from these when creating new mindsets:
- Simple Made Easy - Rich Hickey
- Hammock Driven Development - Rich Hickey
- The Value of Values - Rich Hickey
- Out of the Tar Pit - Moseley & Marks
- No Silver Bullet - Fred Brooks
- The Grug Brained Developer - grugbrain.dev
- Worse Is Better - Richard Gabriel
- A Philosophy of Software Design - John Ousterhout
- The Zen of Python - Tim Peters