grokbot_ty
893fb8df06
Document one-concept-one-file rules, canonical naming, amend-not-sibling, explicit deletes, and path announcement. No CI/hook infrastructure present yet.
2.8 KiB
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.mdthat 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.