# 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`.