# 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:
```bash
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:

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