# Documentation Compression Workflow

## When to run

After any major cleanup session that makes audit/planning docs stale:
- Baseline cleanup completed (deleted legacy files, unified focus)
- Build passes with banned pattern scan at zero
- Audit docs reference files/screens that no longer exist

## Process

### 1. Inventory all root MDs
```bash
ls *.md | wc -l && wc -l *.md
```

### 2. Categorize each MD
- **SSOT (keep):** `PROJECT_STATE.md`, `ARCHITECTURE.md`, `README.md`
- **Migration plan (compress):** `HTML_TV_ARCHITECTURE_MIGRATION_PLAN.md` — strip completed items, keep remaining
- **Stale audits (delete):** any audit doc whose findings are fully resolved

### 3. Merge knowledge into ARCHITECTURE.md
Before deleting an audit MD, extract any durable knowledge (pitfalls, patterns, architecture decisions) into `ARCHITECTURE.md`. Don't preserve session-specific findings — only reusable patterns.

### 4. Delete stale MDs
```bash
rm UI_AUDIT.md UNSPOOLED_SSTEM_BRIEF.md UNSPOOLED_UI_UX_FULL_AUDIT_REBUILD.md
```
Verify no other files reference them:
```bash
grep -r "UI_AUDIT\|SYSTEM_BRIEF\|UX_FULL_AUDIT" *.md
```

### 5. Update PROJECT_STATE.md
- Replace "run git log" with actual commit hash
- Add/update "Documentation" section with current file inventory
- Note which files were deleted and why

### 6. Compress migration plan
Reduce `HTML_TV_ARCHITECTURE_MIGRATION_PLAN.md` from verbose phase tracker to:
- **Completed** section (brief, done = done)
- **Remaining** section (actionable future work)

### 7. Banned pattern scan (final)
```bash
grep -rn "moveFocus(" app/src/main/java/ --include='*.kt' | grep -v '^\s*//' | wc -l
grep -rn "FocusRequester.Default" app/src/main/java/ --include='*.kt' | grep -v 'StreamSection\|^\s*//' | wc -l
```
Must return 0 on all counts.

### Result
Root MDs: typically 7 → 4 after this workflow. No stale references remain.