atelier/core/first-principles.md

Core — First Principles

Version: 1.0.0 Status: Foundational Audience: All agents and humans. Read this first.

1. Manifesto

There are eight principles from which all other principles derive. Every domain rule, every language rule, every review checklist traces back to one or more of these. When two rules conflict, the higher-precedence core principle wins. When a rule has no derivation here, it is orphaned and must be removed or re-derived.

These principles are universal. They apply to every language, every domain, every system. They are not opinions; they are the axioms of quality software.

2. The Principles

C1. Correctness

The system does what it is supposed to do, and nothing else.

• Correctness is the highest principle. No other principle overrides it.
• A correct system handles the specified cases, the edge cases, and the failure cases — all defined by the domain.
• Incorrect code that is fast, clear, or simple is still wrong.
• Security is a subset of correctness: code that is exploitable does not do what it was supposed to do.
• Correctness includes temporal correctness: a late answer is a wrong answer when the deadline mattered.

C2. Clarity

The intent of the code is obvious to its reader.

• Code is read more than it is written. Optimize for the reader.
• Names reveal intent. Comments explain why, not what.
• A stranger should understand the code without reading the documentation. The documentation should make the code unnecessary to read.
• Clarity serves correctness: unclear code is where bugs hide.

C3. Simplicity

The solution is as simple as possible, and no simpler.

• Complexity is the enemy of correctness. Every line of code is a liability.
• Simplicity is not laziness. It is the result of removing everything unnecessary.
• A simple solution handles the requirement completely. A simpler-than-necessary solution does not.
• Simplicity serves economy: less code, less to test, less to maintain.

C4. Locality

Decisions and their consequences live near each other.

• State, logic, and side effects that depend on each other live near each other.
• Locality serves clarity: to understand a piece of code, you should not need to read the whole system.
• Locality serves correctness: coupling that is far apart is coupling you cannot see.
• A change that requires touching many distant files is a locality violation.

C5. Reversibility

Every decision can be undone, and the cost of undoing is known.

• Reversibility serves safety: an irreversible decision is a bet you cannot hedge.
• Migrations, deployments, schema changes, and API changes are reversible by default.
• A decision that cannot be reversed is made with the maximum of evidence and the minimum of haste.
• Versioning, feature flags, and rollback paths are the mechanisms of reversibility.

C6. Composability

Parts combine into wholes, and the parts are reusable in new wholes.

• Composability serves scale: complex systems are built from simple, composable parts.
• A part that does one thing well composes. A part that does many things configures.
• The boundary of a part is its contract. Contracts are explicit and stable.
• Composability serves clarity: composable parts are understandable in isolation.

C7. Observability

The system's behavior is visible to the people who must understand it.

• Observability serves correctness: you cannot fix what you cannot see.
• Logs, metrics, and traces are first-class. They are designed in, not bolted on.
• Observability serves clarity: the system explains itself in production.
• An observable system answers "what happened, why, and what next?" without reading the source.

C8. Economy

The system uses no more resources than the task requires.

• Resources include time, memory, attention, money, and complexity.
• Economy serves simplicity: the cheapest solution is often the simplest.
• Economy is the most tradeable principle: it is sacrificed for correctness, clarity, and reversibility.
• But unbounded economy is a bug: unbounded growth in any resource is a defect.

3. Precedence

When principles conflict, the lower-numbered principle wins:

C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality >
C5 Reversibility > C6 Composability > C7 Observability > C8 Economy

• C1 (Correctness) is never sacrificed.
• C2 (Clarity) is sacrificed only for C1 (Correctness).
• C3 (Simplicity) is sacrificed only for C1 or C2.
• C4–C8 are tradeable among themselves, but always below C1–C3.
• The precedence is total: a violation of C1 is never justified by an appeal to C8.

See core/conflict-resolution.md for the formal conflict resolution procedure.

4. What Violates These Principles

Violation	Principle Breached
Code that "mostly works"	C1 Correctness
A function named doStuff	C2 Clarity
A 500-line function that could be 50	C3 Simplicity
Config in a distant repo, code reads it silently	C4 Locality
A migration with no rollback	C5 Reversibility
A component that reads global state implicitly	C6 Composability
A service with no logs	C7 Observability
Loading all records into memory	C8 Economy

5. Relationship to Domains

Every domain in Atelier derives its own P1–P10 principles from these eight. The mapping is recorded in matrix/principles-matrix.md. A domain rule that cannot be traced to a core principle is orphaned and must be removed.

The eight principles are the floor. The domain principles are the ceiling for their scope. Within a domain, the domain's precedence applies; across domains, the core precedence applies.