update-docs

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:
2. .plans/**/*.md - Plan documents
3. **/CLAUDE.md - Claude-specific guidelines
4. docs/**/* - General documentation
5. .tasks/**/* - Task tracking files
6. Any other doc files the user specifies

1. Git analysis (if applicable):
2. Check when docs were last modified
3. Identify code changes since last doc update
4. Use git log to understand what changed

1. Create comprehensive todo list - One item per document to review
2. 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:
2. Ensure all docs use consistent terminology
3. Verify no conflicting information between docs
4. Check that cross-references are valid

1. Coverage analysis:
2. Identify features/code that lack documentation
3. Find orphaned docs (no corresponding code)
4. Note gaps in documentation coverage

1. Link validation:
2. Verify internal references point to existing files
3. Check that example code paths are correct
4. 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