From f4438843fee206a13d25878fffc8be7065fe130b Mon Sep 17 00:00:00 2001 From: Sam Date: Fri, 21 Aug 2026 22:20:48 +1000 Subject: [PATCH] docs: let scope discipline permit design where none is settled (#533) The Scope discipline section used to open by declaring the architecture documentation "complete and authoritative ... not a draft to extend", and then banned producing "new architecture documents, migration plans ... decision records" outright. That was already false in this tree. docs/architecture/migration-decisions.md is titled "Active migration inventory" and exists to record "what remains to be decided before Archie's current implementation can be migrated into the approved domain-oriented structure". The Architecture section of this same file points agents at it for "the recorded position and what was agreed next". docs/prds/ holds an active PRD and docs/archive/prds/ shows PRDs are a normal artifact here. So the rule asserted the design was finished while the repo shipped an open decision register, and banned the exact artifact type that register is made of. What changed in MEANING: the gate used to be "is this a document" and is now "is there a settled design for this". Where a settled design exists, nothing changes -- implement it, and prose instead of a diff is still the failure. Where none exists (new capability, or an open item in migration-decisions.md) designing first is now REQUIRED rather than prohibited. The old ban was a proxy. What it meant to stop was prose substituting for a diff, and it stopped that by banning the artifact instead of the behaviour. Proxy rules hold right up until the work is genuinely new -- which is when this one broke, and when designing first matters most: accreting diffs toward a new architecture without deciding its shape is how the flat internal/ layout happened, and CLAUDE.md already says undoing that is measured in weeks. The anti-sprawl teeth are kept and made checkable rather than categorical: one page, it decides rather than surveys, it lands in a named home (docs/prds/ or migration-decisions.md), it is unfinished until a diff follows, and anything a reader could have learned from the code gets cut. Ownership ledgers, inventories, current-state traces, review campaigns and planning/refactor issues stay prohibited -- none of those were ever design. AGENTS.md is a symlink to this file, so every harness picks this up. --- CLAUDE.md | 65 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 50 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c4d228d26..47e9baff0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,22 +22,57 @@ the code alone. ## Scope discipline (read this before planning anything) -The architecture documentation in `docs/architecture/` is **complete and -authoritative**. It is a design to implement against — not a draft to extend. +`docs/architecture/` is authoritative for everything it covers: implement +against it, don't re-litigate it, don't restate it in a new document. -- Do **not** produce new architecture documents, migration plans, ownership - ledgers, field-level inventories, current-state traces, decision records, or - review campaigns. If a design question isn't answered in `docs/architecture/`, - ask the maintainer in one sentence — don't write a document to resolve it. -- Do **not** open planning, review, or refactor issues. Open issues only for - concrete bugs and user-facing features. -- This is a **solo project**. There is no review board, no handoff to a - zero-context engineer, no compliance requirement. Prefer the smallest change - that works over the most defensible one. -- Default to producing a diff. If a task's output would be a document rather - than code, confirm that's actually wanted before starting. -- Issues are tracked in GitHub Issues, grouped issues can be linked under an epic, - with subtasks linked to the epic. +It does not cover everything, and this section used to claim it did — it +called the design "complete" and banned design documents outright. That was +wrong on its face: this repo is mid-migration to a domain-oriented structure, +and `docs/architecture/migration-decisions.md` is an **open decision +register** whose entire job is holding design that is not settled yet. A rule +asserting the design is finished, in a tree that ships a list of what remains +to be decided, pushed every genuinely new capability through a prohibition +aimed only at sprawl. The ban was a proxy: what it meant to stop was prose +substituting for a diff, not thinking before building something new. + +So the test is **is there a settled design for this**, never **is this a +document**: + +- **Settled design exists** → implement it. Producing prose instead of a diff + is the failure. If one detail is missing, ask the maintainer in a sentence; + don't write a document to resolve a sentence-sized question. +- **No settled design exists** — genuinely new capability, or an open item in + `migration-decisions.md` → design first, briefly and decisively. This is + required, not merely tolerated. Accreting diffs toward a new architecture + without deciding its shape is how the flat `internal/` layout happened, and + undoing that is measured in weeks. + +A design artifact earns its place by being short, decisive, and followed by +code: + +- One page, and it **decides**. It does not survey options, inventory fields, + or trace current state — the code is the current state, so a document + restating it is stale on arrival. +- It lands in a named home: `docs/prds/` for new capability, an entry in + `docs/architecture/migration-decisions.md` for an open migration question. + Promote it into `docs/architecture/` only once it is built and true. +- It is not finished until a diff follows it. Design with no implementation is + the same sprawl in better clothes. +- Failure test: cut anything a reader could have learned by reading the code. + +Still prohibited, and none of these were ever design: + +- Ownership ledgers, field-level inventories, current-state traces, parity + matrices written for their own sake, and review campaigns. +- Planning, review, or refactor **issues**. Open issues only for concrete bugs + and user-facing features. + +This is a **solo project**. There is no review board, no handoff to a +zero-context engineer, no compliance requirement. Prefer the smallest change +that works over the most defensible one. + +Issues are tracked in GitHub Issues; grouped issues can be linked under an +epic, with subtasks linked to the epic. ## Deployment model