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

3.3 KiB Raw Permalink Blame History