62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# 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`.
|
|
|