Documentation Audit Workflow¶

This workflow defines the repeatable process for auditing documentation to ensure accuracy, relevance, and organization.

Purpose: Identify outdated, inaccurate, or legacy information in /root/tower-fleet/docs/ and maintain documentation quality over time.

Frequency: Execute periodically (quarterly or after major infrastructure changes).

Methodology Overview¶

Phase 1: Discovery & Inventory¶

Generate manifest and cross-reference analysis to prioritize audit work.

Phase 2: Reality Testing¶

Validate commands, paths, and architecture against actual infrastructure.

Phase 3: Content Audit¶

Human-in-the-loop evaluation with severity scoring and recommendations.

Phase 4: Execution¶

Controlled changes in batches with git commits and user approval.

Phase 1: Discovery & Inventory¶

1.1 Generate File Manifest¶

Create inventory of all documentation files:

cd /root/tower-fleet/docs
find . -name '*.md' -type f -exec ls -lh {} \; | awk '{print $9, $5}' > /tmp/doc-manifest.txt

Collect metadata: - File path - Size (KB) - Last modified date - Line count - Category (workflow, reference, ops, applications, etc.)

1.2 Cross-Reference Analysis¶

High-priority docs (referenced in CLAUDE.md): - Extract all doc references from /root/CLAUDE.md - These are actively used and must be accurate

Internal references:

# Find all markdown links to other docs
grep -r '\[.*\](.*\.md)' docs/ | grep -v node_modules

Orphaned docs: - Files with zero incoming references - Candidates for deletion or archival

Legacy indicators:

# Find docs mentioning deprecated tech
grep -r "LXC\|lxc\|container-based" docs/ | grep -v "legacy\|deprecated"
grep -r "/opt/\|/home/\|container exec" docs/

1.3 Prioritization¶

Sort docs by: 1. Critical: Referenced in CLAUDE.md 2. Important: Referenced by multiple other docs 3. Orphaned: No references, unclear purpose 4. Legacy: Contains deprecated patterns

Phase 2: Reality Testing¶

For each document, validate against actual infrastructure:

2.1 Command Validation¶

Safe to execute (read-only): - kubectl get, kubectl describe - ls, cat, find, grep - git log, git status - pct list, qm list, zfs list

DO NOT execute (write operations): - kubectl apply, kubectl delete - pct create, qm create - git push, git commit - Any command that creates/modifies/deletes resources

Testing approach: - Copy command from doc - Verify syntax is correct - Execute safe commands and verify output matches documentation - For unsafe commands, verify syntax only

2.2 Path Validation¶

Check if referenced files/directories exist:

# Extract file paths from doc
grep -oE '`(/[^`]+)`' doc.md | sed 's/`//g' | while read path; do
  if [ -e "$path" ]; then echo "✓ $path"; else echo "✗ $path (missing)"; fi
done

2.3 Architecture Validation¶

Common architecture shifts to check: - LXC → Host-based development: Docs should reference /root/projects/, not container IDs - MkDocs → OtterWiki: Remove MkDocs-specific instructions - Old Supabase → K8s Supabase: Verify namespace references (supabase vs supabase-sandbox) - Service URLs: Verify ingress URLs match current config

2.4 Credentials/Config Validation¶

Verify: - Namespace names (e.g., supabase-sandbox, supabase) - Service names (e.g., kong.supabase.svc.cluster.local) - Port numbers (e.g., :8000 for Kong) - Secret names (e.g., supabase-secrets)

Phase 3: Content Audit¶

For each document, assign severity and recommendation.

3.1 Severity Scoring¶

🔴 CRITICAL: Contains dangerous/broken commands that could harm infrastructure
🟡 STALE: Outdated information but not harmful (e.g., old paths, deprecated patterns)
🟢 VALID: Accurate and current
⚪ ORPHAN: No references, unclear purpose or value

3.2 Recommendations¶

For each doc, recommend ONE action:

KEEP: Document is accurate and valuable
UPDATE: Document needs corrections (specify what)
MERGE: Consolidate with another doc (specify target)
DELETE: No longer relevant (move to archive first)
RECATEGORIZE: Move to different section (specify new location)

3.3 Audit Template¶

For each document, create audit report:

## /root/tower-fleet/docs/path/to/file.md

**Status**: 🟡 STALE
**References**: 3 incoming (CLAUDE.md, other-doc.md, another-doc.md)
**Last Modified**: 2024-11-15

**Issues Found**:
- Line 23: References `/opt/app` (should be `/root/projects/app`)
- Line 45: Command `kubectl get pods -n old-namespace` (namespace renamed)
- Section "LXC Setup": Entire section deprecated

**Recommendation**: UPDATE
- Remove "LXC Setup" section
- Update paths to `/root/projects/`
- Update namespace references
- Add note about architecture change

**Estimated Effort**: 15 minutes

Phase 4: Execution¶

4.1 Batch Processing¶

Work in batches of 5 docs at a time: 1. Make changes to docs 2. Test updated commands/paths 3. Git commit with clear message 4. User approval before proceeding to next batch

4.2 Archival Process¶

Before deleting, move to archive:

# Create archive directory if needed
mkdir -p /root/tower-fleet/docs/archive/deprecated/$(date +%Y-%m)

# Move doc to archive
mv docs/path/to/file.md docs/archive/deprecated/$(date +%Y-%m)/

# Update any references to archived doc
grep -r "path/to/file.md" docs/ | grep -v archive

4.3 Git Commit Format¶

git add -A
git commit -m "docs: audit batch N - [brief summary]

- Updated: file1.md (paths, commands)
- Updated: file2.md (architecture)
- Archived: file3.md (deprecated LXC content)
- Merged: file4.md → file5.md

Refs: documentation-audit workflow"

4.4 Verification¶

After each batch: 1. Verify markdown syntax is valid 2. Check for broken internal links 3. Test commands in updated sections 4. Update audit tracking document

Audit Tracking¶

Create audit log: /root/tower-fleet/docs/audit-log.md

# Documentation Audit Log

## 2025-12-08 - Initial Audit

**Auditor**: Claude Code
**Scope**: All docs (started with high-priority)
**Files Audited**: 0/45
**Status**: In Progress

### Batch 1 (2025-12-08)
- ✓ Updated: workflows/creating-new-app.md
- ✓ Archived: legacy/lxc-setup.md
- ⏳ In Progress: ...

### Issues Summary
- 12 files with path updates needed
- 5 files with deprecated LXC content
- 3 orphaned files (candidates for deletion)
- 2 files to merge (duplicate content)

Tools & Scripts¶

Extract High-Priority Docs from CLAUDE.md¶

# Find all doc references in CLAUDE.md
grep -oE '/root/tower-fleet/docs/[^)]+\.md' /root/CLAUDE.md | sort -u

Find Orphaned Docs¶

# All docs
find docs/ -name '*.md' > /tmp/all-docs.txt

# Referenced docs
grep -rh '\[.*\](.*\.md)' docs/ | grep -oE '[^(]+\.md' | sort -u > /tmp/referenced-docs.txt

# Orphaned = All - Referenced
comm -23 /tmp/all-docs.txt /tmp/referenced-docs.txt

Bulk Path Updates¶

# Update all instances of old path to new path
find docs/ -name '*.md' -exec sed -i 's|/opt/app|/root/projects/app|g' {} \;

Best Practices¶

One document at a time: Don't rush through multiple docs
Test commands: Verify read-only commands actually work
Preserve history: Archive, don't delete immediately
Document changes: Clear commit messages and audit log
Seek feedback: When uncertain, ask for user input

Future Enhancements¶

Automated link checker: Script to validate all internal links
Command validator: Parse and syntax-check bash commands in docs
Freshness indicator: Add "Last Verified" date to each doc
CI integration: Automated checks on doc commits

References¶

/root/CLAUDE.md - Primary navigation document
/root/tower-fleet/docs/reference/documentation-maintenance.md - How to update docs
This workflow document - For periodic audits