yaze/docs/internal/agents/doc-hygiene.md

Documentation Hygiene & Spec Rules

Purpose: keep docs/internal lean, discoverable, and aligned with active work. Use this when creating or updating any internal spec/plan.

Canonical sources first

• Check existing coverage: update an existing spec before adding a new file. Search docs/internal for keywords and reuse templates.
• One source of truth per initiative: tie work to a board entry and, if multi-day, a single spec (e.g., initiative-*.md or a plan under docs/internal/plans/).
• Ephemeral task lists live in z3ed agent todo or the coordination board, not new Markdown stubs.

Spec & plan shape

• Header block: Status (ACTIVE/IN_PROGRESS/ARCHIVE), Owner (Agent ID), Created, Last Reviewed, Next Review (≤14 days by default), and link to the coordination-board entry.
• Keep the front page tight: Summary, Decisions/Constraints, Deliverables, and explicit Exit Criteria. Push deep design notes into appendices.
• Use the templates: initiative-template.md for multi-day efforts, release-checklist-template.md for releases. Avoid custom one-off formats.

Lifecycle & archiving

• Archive on completion/abandonment: move finished or idle (>14 days without update) specs to docs/internal/agents/archive/ (or the relevant sub-archive). Add the date to the filename when moving.
• Consolidate duplicates: if multiple docs cover the same area, merge into the newest spec and drop redirects into the archive with a short pointer.
• Weekly sweep: during board maintenance, prune outdated docs referenced on the board and archive any that no longer have an active entry.

Coordination hygiene

• Every spec links back to the coordination board entry; every board entry points to its canonical spec. No parallel shadow docs.
• Release/initiative docs must include a test/validation section instead of ad-hoc checklists scattered across files.
• When adding references in other docs, point to the canonical spec instead of copying sections.

Anti-spam guardrails

• No gamified/leaderboard or duplicative status pages in agents/—keep status in the board and the canonical spec.
• Prefer updating docs/internal/README.md or the nearest index with short summaries instead of creating new directories.
• Cap new doc creation per initiative to one spec + one handoff; everything else belongs in comments/PRs or the board.
• Filenames: avoid ALL-CAPS except established anchors (README, AGENTS, GEMINI, CLAUDE, CONTRIBUTING, etc.); use kebab-case for new docs.