From 87a079e809aa8f52a4944e202cbc489617ecd5f8 Mon Sep 17 00:00:00 2001 From: "Earl Tankard, Jr., Ph.D" <45021016+primetimetank21@users.noreply.github.com> Date: Sat, 13 Jun 2026 02:44:24 -0400 Subject: [PATCH 1/2] docs: add docs/plans convention doc (front-matter schema, status vocab) This implements WI-1 of the approved Phase 2 docs-alignment plan. Defines the canonical front-matter schema (issue, title, status, created, updated) and locked status vocabulary (draft, ready, in-progress, implemented, superseded). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/plans/README.md | 81 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/plans/README.md diff --git a/docs/plans/README.md b/docs/plans/README.md new file mode 100644 index 0000000..1f138e9 --- /dev/null +++ b/docs/plans/README.md @@ -0,0 +1,81 @@ +# docs/plans -- Plan Document Convention + +This folder contains per-issue vertical slice plans for primetimetank21/dev-setup. Plans are +the pre-implementation spec; they capture scope decisions, design decisions, and acceptance +criteria for a given issue before code is written. + +--- + +## Front-Matter Schema + +Every plan doc must begin with a YAML front-matter block: + +```yaml +--- +issue: +title: "Short human-readable title" +status: +created: +updated: +--- +``` + +No other fields are required. `supersedes: ` is optional when a plan replaces +a prior one. + +--- + +## Status Vocabulary + +| Status | Meaning | +|-------------|--------------------------------------------------| +| draft | In progress; not ready for implementation | +| ready | Grill-passed or otherwise approved; ready impl | +| in-progress | Implementation underway (PR open) | +| implemented | Shipped to develop; doc kept for reference | +| superseded | Replaced by another plan doc (note supersedes) | + +--- + +## File Naming + +``` +NNN-slug.md +``` + +Where NNN is the GitHub issue number (zero-padded to 3 digits) and slug is a short +kebab-case descriptor. Example: 468-customizable-install.md + +--- + +## Layout + +Flat files in docs/plans/. No per-feature subfolders unless a plan accumulates +supplementary assets (diagrams, data tables) that cannot live inline. Threshold: >10 plans +or attached binary assets. + +--- + +## Grill / Review History + +Do NOT commit grill-panel review changelogs to plan docs. The HQ coordinator maintains +review history externally. Plan docs contain only the living spec; revision history is +captured in git log and front-matter `updated` field. + +--- + +## What Belongs Here + +- Problem statement +- Scope (IN / OUT) +- Design decisions (with rationale) +- Algorithm / data structures / pseudocode as needed +- Test plan / acceptance criteria +- Out-of-scope items (tracked issues) + +## What Does NOT Belong Here + +- Review panel names, cast names, or griller attributions +- Version changelog blocks (vN Changes sections) +- Process notes (merge decisions, admin notes, coordinator instructions) +- Implementation progress updates (use the GitHub issue for that) From d7e045a89442cabe862ed320c1be525dae12e6bd Mon Sep 17 00:00:00 2001 From: "Earl Tankard, Jr., Ph.D" <45021016+primetimetank21@users.noreply.github.com> Date: Sat, 13 Jun 2026 02:52:28 -0400 Subject: [PATCH 2/2] docs: genericize review terminology in docs/plans convention doc Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/plans/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/plans/README.md b/docs/plans/README.md index 1f138e9..d97953f 100644 --- a/docs/plans/README.md +++ b/docs/plans/README.md @@ -30,7 +30,7 @@ a prior one. | Status | Meaning | |-------------|--------------------------------------------------| | draft | In progress; not ready for implementation | -| ready | Grill-passed or otherwise approved; ready impl | +| ready | Approved; ready to implement | | in-progress | Implementation underway (PR open) | | implemented | Shipped to develop; doc kept for reference | | superseded | Replaced by another plan doc (note supersedes) | @@ -56,9 +56,9 @@ or attached binary assets. --- -## Grill / Review History +## Review History -Do NOT commit grill-panel review changelogs to plan docs. The HQ coordinator maintains +Do NOT commit review-panel changelogs to plan docs. The HQ coordinator maintains review history externally. Plan docs contain only the living spec; revision history is captured in git log and front-matter `updated` field. @@ -75,7 +75,7 @@ captured in git log and front-matter `updated` field. ## What Does NOT Belong Here -- Review panel names, cast names, or griller attributions +- Reviewer names, cast names, or review attributions - Version changelog blocks (vN Changes sections) - Process notes (merge decisions, admin notes, coordinator instructions) - Implementation progress updates (use the GitHub issue for that)