From 11a84e669d1a62275096112aec3c73982640b2a5 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sat, 20 Jun 2026 13:21:08 +0300 Subject: [PATCH] docs(planning): architecture/ promotion ships in the implementing PR, not on merge Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 4 ++-- planning/README.md | 10 ++++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1e816f1..836ee01 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,9 +18,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Workflow -Per-feature: brainstorming → spec in `planning/changes/YYYY-MM-DD.NN-/design.md` → writing-plans → plan in `planning/changes/YYYY-MM-DD.NN-/plan.md` → executing-plans / subagent-driven-development → requesting-code-review → finishing-a-development-branch. Each change is a folder bundle; `` is a kebab-case description, not a story ID; `.NN` is a zero-padded intra-day counter that breaks same-date ties so the timeline sorts stably. `summary:` is written when the change is created (it is the change's one-liner); the implementing PR then sets `status: shipped`, fills `pr:` and `outcome:` in-branch, and promotes its conclusions into the affected `architecture/.md` — that promotion is the only ship-time step (there is no folder move), and the hand-edit is what keeps `architecture/` true. See [`planning/README.md`](planning/README.md) for the conventions (run `just index` for the change listing) and [`planning/_templates/`](planning/_templates/) for copy-and-fill starting points. +Per-feature: brainstorming → spec in `planning/changes/YYYY-MM-DD.NN-/design.md` → writing-plans → plan in `planning/changes/YYYY-MM-DD.NN-/plan.md` → executing-plans / subagent-driven-development → requesting-code-review → finishing-a-development-branch. Each change is a folder bundle; `` is a kebab-case description, not a story ID; `.NN` is a zero-padded intra-day counter that breaks same-date ties so the timeline sorts stably. `summary:` is written when the change is created (it is the change's one-liner); the implementing PR then sets `status: shipped`, fills `pr:` and `outcome:` in-branch, and promotes its conclusions into the affected `architecture/.md` **in the same PR, alongside the code** — the only ship-time step (there is no folder move), reviewed in the implementing diff rather than applied after merge; that hand-edit is what keeps `architecture/` true. See [`planning/README.md`](planning/README.md) for the conventions (run `just index` for the change listing) and [`planning/_templates/`](planning/_templates/) for copy-and-fill starting points. -**Spec** (`design.md`) captures the *thinking* — why we are doing this, what the design is, what trade-offs were considered, what is out of scope. Written before code; rarely revised after merge. **Plan** (`plan.md`) captures the *sequencing* — the ordered checklist of tasks an executor (human or agent) walks. References the spec for the "why"; never re-explains it. **`architecture/`** captures the *invariants* of shipped systems — the living truth, promoted from a change on merge. A plan paragraph that would still read correctly with all task numbers and checkboxes removed is design content and belongs in the spec. +**Spec** (`design.md`) captures the *thinking* — why we are doing this, what the design is, what trade-offs were considered, what is out of scope. Written before code; rarely revised after merge. **Plan** (`plan.md`) captures the *sequencing* — the ordered checklist of tasks an executor (human or agent) walks. References the spec for the "why"; never re-explains it. **`architecture/`** captures the *invariants* of shipped systems — the living truth, promoted in the change's implementing PR alongside the code. A plan paragraph that would still read correctly with all task numbers and checkboxes removed is design content and belongs in the spec. **Three lanes.** Scale the artifact to the change. **Full** — a `design.md` + `plan.md` bundle — for real design judgment, a new file/module, a public-API change, cross-cutting/multi-file work, or non-trivial test design. **Lightweight** — a single `change.md` — for small-but-real changes (≲30 LOC net, ≤2 files, no new file, no public-API change, a single straightforward test). **Tiny** — no bundle, just a conventional commit — for a typo fix, dep bump, linter/formatter/CI tweak, a mechanical rename to satisfy a just-landed convention, or a single-line config change. Heavier lane wins on ambiguity; a `change.md` that outgrows its lane splits into `design.md` + `plan.md`. diff --git a/planning/README.md b/planning/README.md index c21b6b0..87a142f 100644 --- a/planning/README.md +++ b/planning/README.md @@ -14,13 +14,15 @@ at the repo root; this directory records *how it got there*. ### Two axes, never mixed - **`architecture/` (repo root) — the present.** One file per capability, - living prose, updated whenever a change ships. The truth home. + living prose, updated in the same PR that ships the change. The truth home. - **`planning/changes/` — the past-and-pending.** One folder per change, kept in place after ship. -Shipping a change **promotes** its conclusions into the affected -`architecture/.md` by hand. That hand-edit is what keeps -`architecture/` true; the bundle stays in `changes/` as the *why*. +A change **promotes** its conclusions into the affected +`architecture/.md` by hand **in the implementing PR, alongside the +code** — the edit rides in the same diff and is reviewed with it, never applied +as a separate post-merge step. That hand-edit is what keeps `architecture/` +true; the bundle stays in `changes/` as the *why*. ### Change bundles