dss/docs/DOCUMENTATION_GUIDE.md

Documentation Governance & Anti-Bloat Rules

This guide prevents the documentation chaos from recurring.

---

The Rule of One

Every piece of information must exist in exactly ONE place. No duplicates, no "also documented in...".

Documentation Categories

TIER 1: Foundational Contracts (docs/01_core/)

• API_CONTRACTS.md → API endpoints, status codes, authentication
• ARCHITECTURE.md → System design, technology choices, boundaries
• PRINCIPLES.md → Design philosophy, core values, invariants

These files:

• Change only via semantic versioning (major.minor.patch)
• Must include "Version X.Y.Z" at the top
• Should never contradict each other
• Are the single source of truth for their domain

TIER 2: Current State (docs/02_status/)

• PROJECT_STATUS.md → Deployment status, roadmap, open bugs, current phase
• IMPLEMENTATION_SUMMARY.md → Inventory of completed features (phases 1-5C)
• README.md (root) → Quick start, project overview

These files:

• Update frequently (daily/weekly)
• Always reflect production reality
• Include "Last Updated: YYYY-MM-DD" timestamp
• Are curated (old status removed, new status added)

TIER 3: Reference Guides (docs/03_reference/)

• INTEGRATION_GUIDE.md → How to use DSS in external projects
• MIGRATION_GUIDE.md → How to migrate from legacy systems
• MCP_TOOLS_SPEC.md → Model Context Protocol tool specifications
• PRODUCTION_READINESS.md → Deployment checklist, monitoring

These files:

• Change when guidance needs updating
• Include examples and common patterns
• Link to Tier 1 for architectural context

TIER 4: Archive (docs/archive/)

• pre_optimization/ → Phase reports, old deployment guides
• Snapshot files from past sprints

These files:

• Are READ-ONLY (append dates, don't modify)
• Serve historical context only
• Are NEVER loaded for current work
• Prefixed with date: 2025-12-08_PHASE_5C_COMPLETION.md

---

The Anti-Bloat Process

When a Phase Ends

1. ✅ Update docs/02_status/PROJECT_STATUS.md with new baseline
2. ✅ Merge architectural patterns into docs/01_core/ARCHITECTURE.md
3. ✅ Update docs/02_status/IMPLEMENTATION_SUMMARY.md with new features
4. ⛔ DO NOT create PHASE_X_COMPLETION_REPORT.md (this bloats docs)
5. ⛔ DO NOT keep "Phase X Final Report" in root (archive it immediately)

Example: Instead of creating PHASE_5C_FINAL_REPORT.md, update:

docs/02_status/PROJECT_STATUS.md  → "Phase 5C complete: X, Y, Z features"
docs/02_status/IMPLEMENTATION_SUMMARY.md → "Phase 5C: Added endpoints A, B, C"

Then archive the phase-specific planning doc:

mv PHASE_5C_PLANNING.md docs/archive/pre_optimization/2025-12-08_PHASE_5C_PLANNING.md

When Adding a New Feature

1. ✅ Update docs/01_core/API_CONTRACTS.md with new endpoint(s)
2. ✅ Update docs/01_core/ARCHITECTURE.md if design changed
3. ✅ Update docs/02_status/IMPLEMENTATION_SUMMARY.md with feature inventory
4. ⛔ DO NOT create NEW_FEATURE_IMPLEMENTATION_NOTES.md
5. ⛔ DO NOT add "Feature X Details" to root

Example: For new POST /api/projects endpoint:

docs/01_core/API_CONTRACTS.md → Add full endpoint spec
docs/01_core/ARCHITECTURE.md → Update "Project Management" section if needed
docs/02_status/IMPLEMENTATION_SUMMARY.md → "Phase 6: Added project persistence"

When Fixing a Bug

1. ✅ Update docs/02_status/PROJECT_STATUS.md under "Open Issues" or "Fixed"
2. ⛔ DO NOT create BUG_FIX_SUMMARY.md
3. ⛔ DO NOT add "Fixed: ..." to root

When Documenting a Decision

1. ✅ Add rationale to docs/01_core/ARCHITECTURE.md or docs/01_core/PRINCIPLES.md
2. ✅ If complex, store decision record in .knowledge/decisions/ADR-NNN.json
3. ⛔ DO NOT create DECISION_LOG.md or WHY_WE_CHOSE_X.md

---

Red Flags: Files That Shouldn't Exist in Root

If you see any of these, move them to docs/archive/ immediately:

Pattern	Why Bad	What To Do
DEPLOYMENT_*.md	Dated snapshots	Move to archive, update PROJECT_STATUS instead
*_COMPLETE.md	Historical (Phase is done)	Move to archive
*_REPORT.md	Phase snapshots	Move to archive
WEEK_*_SUMMARY.md	Time-based clutter	Move to archive
MVP*_*.md	Obsolete after Phase 1-2	Move to archive
PHASE_*_*.md	Temporary planning docs	Move to archive
TODO.md	Should be in PROJECT_STATUS	Merge + delete
TASKS.md	Should be in PROJECT_STATUS	Merge + delete
ROADMAP.md	Should be in PROJECT_STATUS	Merge + delete

---

File Lifecycle

CREATED (in working branch)
  ↓
  Is it a phase/deployment snapshot?
    YES → Merge value into Tier 2, archive source
    NO → Continue
  ↓
  Is it a permanent guide?
    YES → Place in Tier 3, reference from relevant Tier 1 files
    NO → Continue
  ↓
  Is it a specification/principle?
    YES → Add to Tier 1, ensure it doesn't duplicate existing content
    NO → This file may not be needed
  ↓
MERGED & COMMITTED

6 MONTHS LATER
  ↓
  Is this still actively used?
    YES → Keep in docs/
    NO → Archive it

---

Maintenance Checklist

Every month, run this command to audit documentation:

# Find markdown files in root older than 30 days
find . -maxdepth 1 -name "*.md" -mtime +30 -type f

# Any files here should be reviewed for archival

---

The Hierarchy in One Picture

AI Agent starts session
  ↓
  Read: QUICK_REFERENCE.md (this file's companion)
  ↓
  Context loaded: Tier 1 + Tier 2
  ↓
  Working on feature? Load relevant Tier 3 guide
  ↓
  Historical research? Only then access Tier 4 archive

---

Questions This Answers

"Where do I document this?"

• Principles → docs/01_core/PRINCIPLES.md
• API changes → docs/01_core/API_CONTRACTS.md
• Architecture changes → docs/01_core/ARCHITECTURE.md
• Current bugs → docs/02_status/PROJECT_STATUS.md
• How-to guide → docs/03_reference/
• Phase snapshot → docs/archive/ (after extracting value)

"Can I create a new file for X?"

• If X belongs in an existing Tier file → NO, add to that file
• If X is a new guide type → MAYBE, add to Tier 3 and update QUICK_REFERENCE.md
• If X is temporary → NO, update PROJECT_STATUS instead

"How old can docs be?"

• Tier 1 files → Should be current (versioned if changed)
• Tier 2 files → Must be current (updated weekly minimum)
• Tier 3 files → Can be older, but should note "Last Verified: DATE"
• Tier 4 files → Frozen in time, append dates

---

Governance Rule Enforcement

For PR Reviews

Check that no PR adds files matching these patterns to root:

• *_REPORT.md
• *_COMPLETE.md
• PHASE_*.md
• DEPLOYMENT_*.md
• MVP_*.md
• TODO.md, TASKS.md, ROADMAP.md

If found, request refactor: "Please move this to docs/archive/ or merge value into docs/02_status/"

For Session Start

Load ONLY:

1. QUICK_REFERENCE.md (this directs you)
2. docs/02_status/PROJECT_STATUS.md (current state)
3. docs/01_core/PRINCIPLES.md (philosophy)

Everything else is on-demand.

---

Victory Metrics

• ✅ Root directory has <15 markdown files (down from 40+)
• ✅ docs/ subdirectories organized by Tier
• ✅ No deprecated files in root
• ✅ New docs automatically placed in correct Tier
• ✅ QUICK_REFERENCE.md is the single entry point
• ✅ Context window reduced from ~50k to ~15k lines

---

Last Updated: 2025-12-08 Approved By: Gemini 3 Pro, Deep Think Analysis