Update Documentation

CRITICAL: Oracle-First Protocol

BEFORE making ANY changes to documentation, you MUST consult the Oracle to understand what exists and what must be preserved.

Documentation often contains hard-won knowledge, historical context, and decisions that aren't obvious from code alone. Blindly updating docs risks losing this irreplaceable information.

Mandatory Pre-Update Oracle Consultation

For EACH significant document (especially CLAUDE.md, architecture docs, decision records):

Task(
  subagent_type: "general-purpose",
  model: "opus",
  prompt: """
  You are The Oracle - analyze this documentation before it gets updated.

  DOCUMENT PATH: [path]
  DOCUMENT CONTENT:
  [full content]

  ANALYSIS REQUIRED:

  1. **Critical Knowledge Inventory**
     - What unique insights/decisions does this document contain?
     - What historical context would be lost if overwritten?
     - What hard-won lessons or gotchas are documented?
     - What non-obvious information exists that code doesn't reveal?

  2. **Preservation Requirements**
     - List specific sections/paragraphs that MUST be preserved
     - Identify any warnings, caveats, or "don't do X" guidance
     - Note any project-specific conventions explained here
     - Flag any links to external resources or related docs

  3. **Safe to Update**
     - What sections are purely factual and safe to update from code?
     - What sections are demonstrably outdated based on codebase?
     - What can be verified objectively vs. requires human judgment?

  4. **Update Recommendations**
     - Specific guidance for updating this document safely
     - Sections to leave untouched without human approval
     - Suggested merge strategy (preserve + add vs. replace)

  Be thorough. Assume any knowledge lost here is lost forever.
  """
)

When Oracle Consultation is MANDATORY

• ALWAYS for: CLAUDE.md files, architecture docs, decision records, onboarding guides
• ALWAYS for: Any doc >200 lines or last modified >30 days ago
• ALWAYS for: Docs with sections titled "Why", "History", "Decisions", "Gotchas", "Warnings"
• RECOMMENDED for: All other significant documentation

When You Can Skip Oracle (rare)

• Trivial typo fixes
• Adding new sections (not modifying existing)
• Updating version numbers or dates
• Fixing broken links to known-good targets

Instructions

Systematically review and update all project documentation to ensure accuracy, completeness, and alignment with current codebase state.

Phase 0: Oracle Pre-Analysis (NEW - MANDATORY)

Before touching ANY documentation:

1. Identify high-value documents - CLAUDE.md, architecture docs, decision records
2. Run Oracle analysis on each high-value document
3. Create preservation checklist from Oracle findings
4. Add preservation requirements to TodoWrite - these are non-negotiable

Example TodoWrite entries from Oracle:

- [ ] PRESERVE: Authentication decision rationale in CLAUDE.md (lines 45-67)
- [ ] PRESERVE: Database migration warnings in architecture.md
- [ ] PRESERVE: "Why we don't use X" section in conventions.md
- [ ] SAFE TO UPDATE: API endpoint list (verify against code)

Phase 1: Discovery & Analysis

1. Find all documentation files:

   • .plans/**/*.md - Plan documents
   • **/CLAUDE.md - Claude-specific guidelines
   • docs/**/* - General documentation
   • .tasks/**/* - Task tracking files
   • Any other doc files the user specifies

2. Git analysis (if applicable):

   • Check when docs were last modified
   • Identify code changes since last doc update
   • Use git log to understand what changed

3. Create comprehensive todo list - One item per document to review

   • Include Oracle preservation requirements from Phase 0

Phase 2: Systematic Document Review

For EACH document in the todo list:

Step 1: Read & Understand

• Fully read the document
• Understand its purpose and scope
• Note any references to code, features, or architecture
• Check Oracle preservation list for this document

Step 2: Validate Against Codebase

Audit the codebase to check if documentation is:

• Misleading: Claims something that isn't true
• Outdated: References old code, deprecated patterns, or removed features
• Wrong: Contains factual errors about implementation
• Missing: Lacks important information about current state
• Redundant: Duplicates information found elsewhere

CRITICAL: Cross-reference with Oracle preservation list. If something seems outdated but Oracle flagged it as "preserve", DO NOT modify without explicit confirmation.

Step 3: Check Compliance

Verify document follows guidelines in CLAUDE.md:

• Naming conventions
• Architecture patterns
• Code style requirements
• File organization rules

Step 4: Special Handling for Plan Documents

Plans in .plans/ require careful status tracking:

Investigation:

• Thoroughly audit codebase to determine implementation status
• Check each item in the plan against actual code
• NEVER assume - verify everything with code inspection

Status Categorization:

• Todo (rename to *.todo.md): Plan not yet implemented or partially implemented
• Done (rename to *.done.md): Plan completely implemented and verified
• Obsolete (rename to *.obsolete.md): Plan no longer relevant or superseded

Progress Marking:

• Mark implemented items with ✅ prefix
• Keep unimplemented items without checkmark
• Be conservative - only mark as done with 100% confirmation

CRITICAL: NEVER mark a plan as done until you have 100% confirmation through code audit that EVERY item is implemented.

Step 5: Update Document (WITH PRESERVATION PROTOCOL)

Before ANY edit, verify:

• Oracle preservation requirements are honored
• No "Why", "History", or "Decision" sections are being removed
• Warnings and gotchas are being kept
• You're ADDING to existing knowledge, not replacing it

Safe update patterns:

• Fix factual errors (wrong file paths, outdated API signatures)
• Add new information alongside existing
• Update status markers and dates
• Fix broken links

Dangerous patterns (require confirmation):

• Deleting any paragraph >2 sentences
• Rewriting explanatory sections
• Removing "deprecated" or "don't use" warnings
• Changing architectural guidance

Step 6: Validate Changes

• Ensure changes are accurate
• Verify Oracle preservation requirements were followed
• Verify no information was lost
• Check that references/links still work

Step 7: Document Changes

Add to running change log:

• File: [path]
• Changes made: [description]
• Reason: [why it was updated]
• Preserved sections: [what was kept per Oracle guidance]

Step 8: Mark Complete

Update todo list to mark this document as completed

Phase 3: Cross-Document Analysis

After reviewing all individual documents:

1. Consistency check:

   • Ensure all docs use consistent terminology
   • Verify no conflicting information between docs
   • Check that cross-references are valid

2. Coverage analysis:

   • Identify features/code that lack documentation
   • Find orphaned docs (no corresponding code)
   • Note gaps in documentation coverage

3. Link validation:

   • Verify internal references point to existing files
   • Check that example code paths are correct
   • Validate any external links

Phase 4: Summary & Recommendations

1. Generate update summary:

# Documentation Update Summary - [Date]

## Oracle Consultation
- Documents analyzed: X
- Critical sections preserved: Y
- Preservation requirements followed: ✅/❌

## Files Updated: X
## Changes Made:

### Plans Status
- ✅ Done: [list]
- 📋 Todo: [list]
- ⚠️ Obsolete: [list]

### Updates by Document
- **[file path]**
  - Fixed: [what was wrong]
  - Added: [what was missing]
  - Removed: [what was redundant]
  - **Preserved**: [what was kept per Oracle]

### Coverage Gaps
- [Undocumented features]
- [Orphaned documentation]

### Recommendations
1. [Suggested improvements]
2. [New docs needed]

2. Save summary to .docs-updates/update-[timestamp].md

Phase 5: Validation

1. Build check - Ensure any doc-related code samples build correctly
2. Link check - Verify all internal references work
3. Completeness check - Confirm all todos were addressed
4. Preservation check - Verify Oracle requirements were honored

Critical Principles

• ORACLE FIRST - Always consult Oracle before modifying significant docs
• PRESERVE OVER REPLACE - Add new info, don't delete old wisdom
• 100% VERIFICATION REQUIRED - Never mark plans as done without complete code audit
• NEVER SKIP DOCUMENTS - Review every file in the todo list
• BE CONSERVATIVE - When in doubt about plan status, keep as todo
• THOROUGH INVESTIGATION - Actually read the code to verify claims
• PRESERVE INTENT - Keep the original purpose while updating facts
• TRACK CHANGES - Document what was changed and why
• COMPLIANCE FIRST - ALWAYS follow CLAUDE.md guidelines
• NO ASSUMPTIONS - Verify everything against actual code

The Documentation Preservation Hierarchy

NEVER delete without explicit approval:

1. Architectural decisions and their rationale
2. "Why we did X" explanations
3. Warnings, gotchas, and "don't do this" guidance
4. Historical context and migration notes
5. Non-obvious conventions and their reasons

Safe to update freely:

1. Code examples (verify against actual code)
2. File paths and line numbers
3. Version numbers and dates
4. Status markers and checkboxes
5. Broken links (to known-good targets)

Plan Status Decision Tree

Is EVERY item in the plan implemented?
├─ YES (verified in code) → Mark items with ✅
│  └─ Are ALL items marked ✅?
│     ├─ YES → Rename to .done.md
│     └─ NO → Rename to .todo.md (still has work)
│
├─ NO (some items not implemented) → Rename to .todo.md
│  └─ Mark implemented items with ✅
│
└─ Plan is superseded or irrelevant → Rename to .obsolete.md

Mermaid Diagrams in Documentation

When updating documentation, add or update Mermaid diagrams to visualize complex concepts.

When to Add Diagrams

Document Type	Diagram Use
Architecture docs	Component relationships, data flow
API documentation	Request/response sequences
Process guides	Workflow flowcharts
Decision records	Before/after state diagrams

Diagram Maintenance

When updating docs:

1. Check existing diagrams - Are they still accurate?
2. Update outdated diagrams - Reflect current architecture
3. Add missing diagrams - Where text alone is insufficient
4. Remove obsolete diagrams - If they show removed features

Example: Architecture Update

## Current Architecture

```mermaid
flowchart TD
    subgraph Frontend
        A[React App] --> B[API Client]
    end
    subgraph Backend
        B --> C[Express Server]
        C --> D[PostgreSQL]
        C --> E[Redis Cache]
    end
```

Note: Diagrams in documentation should be verified against actual code, just like text.

---

Supporting Tools Integration

• Use Task (Oracle) to analyze docs before modification
• Use Grep to search for TODOs or implementation evidence
• Use Glob to find related files
• Use Bash for git operations
• Use Read to examine code thoroughly
• Use Edit to update documentation
• Use TodoWrite to track review progress AND preservation requirements