Decisions Before the First Brick

"The architecture decisions are already made. Do not reopen naming, product boundary, framework, or v0 backend selection before the first brick."

The Player Was Built in Documents First

There's a common way to start a project: open an editor and type, and let the architecture emerge from the code. It feels fast and it is a slow-motion disaster — every fundamental question stays open, so every one gets re-litigated in the middle of unrelated work, and the design becomes an average of whatever you believed on the days you happened to touch each file.

Ashen Reel was built the other way. Before the first line of player code, three documents were written and frozen: the architecture invariant (product and data boundaries, the twelve invariants), the parity contract (what's in scope, the P0/P1/P2/Never tiers, how to compare), and the implementation plan (the build order and phase gates). The decisions that must not change were made first, on purpose, so the code could assume them instead of arguing with them.

Freeze the decisions that must not change before you write the code that assumes them. Architecture is the set of choices that are expensive to reverse. Making those choices deliberately and up front — and writing them down — is what stops them from being remade badly, one accidental commit at a time.

Three documents, three kinds of frozen:

The invariant doc is a contract with future-you. The implementation plan says it outright: do not reopen naming, product boundary, framework, or v0 backend before the first brick. That's not bureaucracy — it's a gift. It means a future session (including a future you who forgot the reasoning) can build confidently instead of re-deciding settled things. A written decision you can point at ends a debate; an unwritten one restarts it every week.

What Freezing Buys and What It Doesn't

Freezing the architecture doesn't mean freezing everything — the docs are careful to separate the invariant from the incidental. Dependency versions and file trees live in code, because they rot; the invariants live in the doc, because they're load-bearing. And the freeze isn't forever: the discipline is that you change an invariant in the same change that moves the boundary, and you bump the doc's verification date. So the rule isn't 'never change your mind.' It's 'don't quietly re-decide the foundations while building on them, and when the foundation genuinely must move, move it deliberately and write down that it moved.'

Code

What each document froze before any player code existed·text

Frozen BEFORE the first line of player code:

  DOCUMENT                       FREEZES...
  ASHENREEL-ARCHITECTURE.md      product & data boundaries, the 12 invariants
  ...-MOVIST-PARITY-CONTRACT.md  scope, P0/P1/P2/Never tiers, how to compare
  ...-IMPLEMENTATION-PLAN.md     build order, phase gates, first-brick definition

// The plan's own words:
//   'do not reopen naming, product boundary, framework, or v0 backend
//    before the first brick.'
//
// The docs are a contract with future-you: here is what you are NOT
// allowed to re-litigate in the middle of building. Decide once, up front.

Exercise

For a project you're on, list the three or four decisions that would be most expensive to reverse — the framework, the core data boundary, the primary storage, the deployment shape. For each, ask: is it written down with its reasoning, or does it live only in memory and habit? Write one of them up as a short decision record (what, why, what was rejected). Notice how much more confidently the next change can be made against a written foundation.

Hint

The decisions worth freezing are the ones that are expensive to reverse and that lots of other code assumes. If those live only in people's heads, they get silently re-decided by whoever touches the code next. Writing 'we chose X because Y' turns a foundation you have to defend in every review into one you can point at.

Decisions Before the First Brick

The Player Was Built in Documents First

What Freezing Buys and What It Doesn't

Code

External links

Exercise

Progress

Comments 0