diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md new file mode 100644 index 0000000..47c0e21 --- /dev/null +++ b/docs/CONVENTIONS.md @@ -0,0 +1,60 @@ +# Docs conventions (anti-duplication) + +**Branch applicability:** whole repo; written on `planning-selfserve-audit` after repeated near-duplicate markdown sprawl. +**Scope:** `docs/**/*.md` (and any future top-level strategy markdown). + +These rules exist so agents and humans **do not** create sibling files like `…_PLAN.md` next to `…_CONCEPT.md` for the same subject. + +--- + +## 1. One concept = one file + +Before creating **any** new markdown file under `docs/`: + +1. Search existing paths and titles for **similar names** or **overlapping topics**. +2. If overlap exists → **update the existing file** (amend in place). +3. Only create a new file when the topic is genuinely new and no current file owns it. + +## 2. Naming — one canonical name per topic + +- Pick a **single** canonical filename per subject and stick to it. +- Do **not** create variants that differ mainly by role suffix, including but not limited to: `PLAN`, `CONCEPT`, `DRAFT`, `NOTES`, `OUTLINE`, `BRIEF`, `SPEC`, `V2`. +- Bad: `SELF_SERVE_AI_DISCOVERABILITY_PLAN.md` + `SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md`. +- Good: one `SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md` that holds both concept and phased plan. + +## 3. “Write a plan / concept / brief” means amend + +If a task says write a plan, concept, brief, or execution outline for something that **already has a file**, **amend that file**. Never add a sibling with a near-identical stem. + +Current example SoT: [`SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md`](./SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md). + +## 4. Deletes and consolidations + +- **Deleting** a docs file requires an **explicit** instruction (user or locked task). +- Consolidations: **merge** unique content into the surviving file, **then** delete the duplicate(s). Do not leave two near-names “for later.” + +## 5. Announce path before create + +Every new docs file must be **announced with its exact path** before creation (in the working chat/call). If the announced path overlaps an existing topic, stop and amend instead. + +--- + +## Quick checklist (agents) + +- [ ] Grepped / listed `docs/` for similar stems and topics +- [ ] Confirmed no PLAN/CONCEPT/DRAFT twin for the same subject +- [ ] Amending existing SoT when topic already exists +- [ ] Exact path announced before any `docs/` create +- [ ] Consolidation ends with a single surviving file + +--- + +## Automation note + +As of 2026-10-01 this repo has **no** Gitea Actions / `.gitea` / `.github` CI and only stock `.git/hooks/*.sample` files. Guardrails are **documented here** until CI or an active pre-commit hook is added. Prefer enforcing via this file + review rather than inventing hook infrastructure without a project standard. + +--- + +## Capture + +Added after consolidating the self-serve AI discoverability PLAN+CONCEPT duplicate on `planning-selfserve-audit`.