From 228527b806e33ea92e0af19debd7fc616bfe3f6f Mon Sep 17 00:00:00 2001 From: ChethanUK Date: Sat, 5 Sep 2026 02:07:19 +0200 Subject: [PATCH 1/2] docs: add plans/README.md documenting the plan-document convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `plans/` holds 16 directories and no top-level file, so the only written statement of the convention is one clause in CONTRIBUTING.md. That clause is already narrower than the tree it governs — three directories are named workstreams rather than issue numbers, and two key off a PR number — and AGENTS.md, the agent entry point, never mentions plans at all. Add plans/README.md covering what the directory is (development planning artifacts, never published to the docs site), the plans/ vs architecture/ vs fern/ vs docs/ boundary, both live naming conventions, the document shape as observed, where assets go, and how a plans-only PR is reviewed per .agents/recipes/pr-review/recipe.md. Point AGENTS.md at it with one line, matching the three sentences already there. CONTRIBUTING.md is deliberately unchanged: GitHub renders a directory's README.md, so its relative link and the Fern copy's absolute one both land on the new file without an edit. Refs #753 Signed-off-by: ChethanUK --- AGENTS.md | 1 + plans/README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 plans/README.md diff --git a/AGENTS.md b/AGENTS.md index c9c3b4c43..434a68e5f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,3 +54,4 @@ make perf-import CLEAN=1 # profile import time (run after adding heavy deps) For full setup, testing, and workflow details see [DEVELOPMENT.md](DEVELOPMENT.md). For code style, naming, and import conventions see [STYLEGUIDE.md](STYLEGUIDE.md). For deeper dives into specific subsystems see [`architecture/`](architecture/). +For planning artifacts and the plan-document convention see [`plans/`](plans/). diff --git a/plans/README.md b/plans/README.md new file mode 100644 index 000000000..846534da0 --- /dev/null +++ b/plans/README.md @@ -0,0 +1,86 @@ +# Plans + +Development planning artifacts. Each subdirectory holds the point-in-time design documents +written before non-trivial work started — the approach, the trade-offs weighed, the affected +subsystems, and the delivery sequence. [`CONTRIBUTING.md`](../CONTRIBUTING.md) asks for one of +these before building anything non-trivial. + +These are **not user documentation and are never published**. [`fern/docs.yml`](../fern/docs.yml) +declares a single version source and all of it lives under `fern/versions/latest/pages/`; nothing +in `plans/` is reachable from the docs site. Read a plan as a record of what the author intended +at the time, not as a description of what the code does today. + +## Where a document belongs + +| Directory | Holds | Describes | +| --- | --- | --- | +| `plans/` | Design documents written before the work | Work not yet built | +| [`architecture/`](../architecture/) | [`overview.md`](../architecture/overview.md) plus nine subsystem documents | Shipped code | +| `fern/versions/latest/pages/**` | Published product documentation | What users are told | +| [`docs/`](../docs/) | Support files consumed by the Fern build (see [`docs/README.md`](../docs/README.md)) | Not prose | + +If a plan's content has shipped and readers need it to understand the running system, it belongs +in `architecture/`, not here. + +## Naming + +Use `plans//`, no zero padding — `plans/790/`, not `plans/0790/`. One directory per +plan, so supporting media sits beside the document it belongs to. + +`plans//` is equally current for work with no single tracking issue. +`workflow-chaining/`, `check-models/`, and `remote-filesystem-seeds/` are all named this way and +all postdate the numbered convention. + +Two directories — `299/` and `788/` — key off the implementing **pull request** number, because +the plan landed in the same change as the code. Prefer the issue number for new plans. + +## Document shape + +Observed across the existing plans, not a schema to conform to: + +- Optional YAML frontmatter: `date`, `authors`, and sometimes `status` or `issue`. The handful of + documents that set `status:` use it loosely (`draft`, `proposal`, `in-progress`) — read it as an + author's note, not as a lifecycle the repository enforces. +- A `# Plan: ` heading. Most primary documents use it. +- A body that runs Summary or Problem → Motivation → Goals → Non-goals → Design. + [`790/engine-native-record-selection.md`](790/engine-native-record-selection.md) and + [`518/pr-hygiene-plan.md`](518/pr-hygiene-plan.md) are good references. +- `path:line` citations when pointing at code, so a reader can check the claim. +- kebab-case filenames. `392/refactor_managed_personas_plan.md` is the one snake_case holdout. + +A plan that grows past a single document gets an index — see +[`645/README.md`](645/README.md), where a `README.md` fronts the sibling documents and links each +by audience. + +## Assets + +Diagrams and images go beside the document, or in an `assets/` subdirectory +([`396/assets/`](396/assets/)). Both are in use. + +For generated diagrams the source file is authoritative. `645/` states the rule for its PlantUML +diagrams and it applies generally: a change to the source must regenerate the images in the same +diff, or say explicitly why rendering was unavailable. + +## For agents + +Keep plans factual. Link the issues and pull requests the plan relates to, cite code by `path:line` +rather than paraphrasing it, and name the open questions instead of resolving them by assumption. +Do not write user-facing prose here. + +Plans are point-in-time and nothing refreshes them automatically — +`.github/workflows/agentic-ci-daily.yml` excludes `plans/` from the paths its docs auto-fix job is +allowed to touch. When work changes shape, update the plan or supersede it in the same pull request +that changes the work. A plan left describing an approach that was abandoned is worse than no plan. + +### How a plan PR is reviewed + +Per [`.agents/recipes/pr-review/recipe.md`](../.agents/recipes/pr-review/recipe.md), a pull request +that only touches `plans/` is reviewed on four things: + +1. **Completeness** — gaps, missing phases. +2. **Feasibility** — can the proposed approach actually be built. +3. **Alignment** — consistent with [`AGENTS.md`](../AGENTS.md) and the existing + [`architecture/`](../architecture/) documents. +4. **Open questions** — are the unknowns identified rather than glossed over. + +Linting and code-style checks are skipped. From 71be262ae97f0e5f8a2c09c6de7452ddf57187e4 Mon Sep 17 00:00:00 2001 From: ChethanUK <chethanuk@outlook.com> Date: Thu, 10 Sep 2026 23:48:38 +0200 Subject: [PATCH 2/2] docs: narrow plans/README.md to plans-specific guidance Review on #918 pointed out that the "Where a document belongs" table turned a plans guide into a partial, inaccurate repository-wide taxonomy. Replace it with a short "What belongs here" section that only separates plans/ from architecture/, fern/ and .scratch/. Also align naming with CONTRIBUTING.md (new plans go in plans/<issue-number>/) instead of calling workstream directories equally current, spell out the plan lifecycle so a plan is reconciled with what shipped but never read as current behavior, scope the PlantUML rule to plans/645/ as an example, and drop counts that go stale. Existing directories are not renamed; that is still an open question on the PR. Refs #753 Signed-off-by: ChethanUK <chethanuk@outlook.com> --- plans/README.md | 70 ++++++++++++++++++++++++++----------------------- 1 file changed, 37 insertions(+), 33 deletions(-) diff --git a/plans/README.md b/plans/README.md index 846534da0..5234b810b 100644 --- a/plans/README.md +++ b/plans/README.md @@ -1,52 +1,47 @@ # Plans -Development planning artifacts. Each subdirectory holds the point-in-time design documents -written before non-trivial work started — the approach, the trade-offs weighed, the affected -subsystems, and the delivery sequence. [`CONTRIBUTING.md`](../CONTRIBUTING.md) asks for one of -these before building anything non-trivial. +Development planning artifacts. Each subdirectory holds the design documents for one body of +work — the approach, the trade-offs weighed, the affected subsystems, the delivery sequence, and, +once the work lands, what it actually shipped. [`CONTRIBUTING.md`](../CONTRIBUTING.md) asks for +one of these before building anything non-trivial. These are **not user documentation and are never published**. [`fern/docs.yml`](../fern/docs.yml) declares a single version source and all of it lives under `fern/versions/latest/pages/`; nothing -in `plans/` is reachable from the docs site. Read a plan as a record of what the author intended -at the time, not as a description of what the code does today. +in `plans/` is reachable from the docs site. Read a plan as a record of one change, not as a +description of what the code does today. -## Where a document belongs +## What belongs here -| Directory | Holds | Describes | -| --- | --- | --- | -| `plans/` | Design documents written before the work | Work not yet built | -| [`architecture/`](../architecture/) | [`overview.md`](../architecture/overview.md) plus nine subsystem documents | Shipped code | -| `fern/versions/latest/pages/**` | Published product documentation | What users are told | -| [`docs/`](../docs/) | Support files consumed by the Fern build (see [`docs/README.md`](../docs/README.md)) | Not prose | +A plan belongs in `plans/` when it records the design and shipped outcome of a specific body of +work. Adjacent cases go elsewhere: -If a plan's content has shipped and readers need it to understand the running system, it belongs -in `architecture/`, not here. +- How the system works today goes in [`architecture/`](../architecture/), which is maintained as + the code changes. +- User-facing product documentation goes in [`fern/`](../fern/). +- Temporary notes go in `.scratch/`, which is gitignored and never committed. ## Naming -Use `plans/<issue-number>/`, no zero padding — `plans/790/`, not `plans/0790/`. One directory per -plan, so supporting media sits beside the document it belongs to. +New plans go in `plans/<issue-number>/`, as [`CONTRIBUTING.md`](../CONTRIBUTING.md) specifies, +with no zero padding — `plans/790/`, not `plans/0790/`. One directory per plan, so supporting media +sits beside the document it belongs to. -`plans/<workstream-name>/` is equally current for work with no single tracking issue. -`workflow-chaining/`, `check-models/`, and `remote-filesystem-seeds/` are all named this way and -all postdate the numbered convention. - -Two directories — `299/` and `788/` — key off the implementing **pull request** number, because -the plan landed in the same change as the code. Prefer the issue number for new plans. +Some existing directories are named after a workstream (for example `workflow-chaining/`) or a +pull request number rather than an issue. Do not use either form for a new plan. ## Document shape Observed across the existing plans, not a schema to conform to: -- Optional YAML frontmatter: `date`, `authors`, and sometimes `status` or `issue`. The handful of - documents that set `status:` use it loosely (`draft`, `proposal`, `in-progress`) — read it as an +- Optional YAML frontmatter: `date`, `authors`, and sometimes `status` or `issue`. Documents + that set `status:` use it loosely (`draft`, `proposal`, `in-progress`) — read it as an author's note, not as a lifecycle the repository enforces. - A `# Plan: <title>` heading. Most primary documents use it. - A body that runs Summary or Problem → Motivation → Goals → Non-goals → Design. [`790/engine-native-record-selection.md`](790/engine-native-record-selection.md) and [`518/pr-hygiene-plan.md`](518/pr-hygiene-plan.md) are good references. - `path:line` citations when pointing at code, so a reader can check the claim. -- kebab-case filenames. `392/refactor_managed_personas_plan.md` is the one snake_case holdout. +- kebab-case filenames. A plan that grows past a single document gets an index — see [`645/README.md`](645/README.md), where a `README.md` fronts the sibling documents and links each @@ -57,9 +52,9 @@ by audience. Diagrams and images go beside the document, or in an `assets/` subdirectory ([`396/assets/`](396/assets/)). Both are in use. -For generated diagrams the source file is authoritative. `645/` states the rule for its PlantUML -diagrams and it applies generally: a change to the source must regenerate the images in the same -diff, or say explicitly why rendering was unavailable. +For generated diagrams, commit the source beside the rendered images. [`645/`](645/) is an +example: its README makes the PlantUML file authoritative and asks that a change to it regenerate +the PNGs in the same diff. ## For agents @@ -67,10 +62,19 @@ Keep plans factual. Link the issues and pull requests the plan relates to, cite rather than paraphrasing it, and name the open questions instead of resolving them by assumption. Do not write user-facing prose here. -Plans are point-in-time and nothing refreshes them automatically — -`.github/workflows/agentic-ci-daily.yml` excludes `plans/` from the paths its docs auto-fix job is -allowed to touch. When work changes shape, update the plan or supersede it in the same pull request -that changes the work. A plan left describing an approach that was abandoned is worse than no plan. +A plan's lifecycle: + +1. Draft the plan and get it reviewed before implementation starts. +2. Keep it aligned with the work as it is built. A plan left describing an abandoned approach is + worse than no plan. +3. Reconcile it with the delivered behavior before the implementing work is considered complete. +4. After that it stays as the historical record of that change, tied to its issue or pull request. + A later change to the same behavior gets its own plan rather than an edit to this one. + +Nothing refreshes plans automatically — the docs auto-fix job in +`.github/workflows/agentic-ci-daily.yml` does not include `plans/` in the paths it may touch. Even +an up-to-date plan does not tell you how the system works now; the code, `architecture/`, and +`fern/` do. ### How a plan PR is reviewed