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/:

Search existing paths and titles for similar names or overlapping topics.
If overlap exists → update the existing file (amend in place).
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.

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.

2.8 KiB Raw Permalink Blame History