Update Doc

Update Doc

Transform any markdown document into an AI-optimized version using research-backed best practices.

When to Use

Invoke when user says:

• "update doc"
• "optimize doc"
• "rewrite for claude"
• "AI optimize"
• "make this doc AI-friendly"

Workflow

Phase Details

Phase 0: File Selection

1. Use Glob to find .md files modified in last 30 days
2. Exclude: node_modules/, .git/, *.optimized.md, *.backup.md
3. Use AskUserQuestion to present top 10 most recently modified files
4. Store selected file path for subsequent phases

Phase 1: Analysis

1. Read the selected document completely
2. Detect document type (see references/document-types.md):
   • CLAUDE.md → Apply progressive disclosure rules
   • Skill file → Ensure frontmatter and XML tags
   • Pattern file → Add [OK]/[FAIL] examples
   • General markdown → Apply standard optimization
3. Count lines, headings, code blocks, links

Phase 1.5: Accuracy Verification (Pattern Files)

For pattern files only (claude-patterns/ path), verify content against codebase:

1. Use AskUserQuestion: "This is a pattern file. Verify accuracy against codebase first?"

   • Yes (Recommended): Proceed to verification
   • Skip: Jump to Phase 2

2. If verifying, spawn Explore agent with Task tool:

   • Extract key claims from pattern (function names, file paths, type names, workflows)
   • Search codebase for actual implementations
   • Compare pattern claims vs actual code

3. Report findings:

   ## Accuracy Check
   
   | Claim                 | Status      | Finding                         |
   | --------------------- | ----------- | ------------------------------- |
   | Uses `functionName()` | ✅ Verified | Found at `src/path/file.ts:123` |
   | Type `TypeName`       | ❌ Outdated | Type renamed to `NewTypeName`   |
   

4. If inaccuracies found:

   • Fix the original file first (correct function names, type names, file paths)
   • Then proceed to Phase 2 with accurate content

Why this matters: Optimizing inaccurate documentation propagates errors. The email-patterns.md bug showed pattern files can drift from code over time.

Phase 2: Transformation

Apply rules from references/transformation-rules.md:

1. Structure: Fix heading hierarchy, convert prose to tables/bullets
2. Content: Consistent terminology, explicit references, imperative form
3. Format: XML tags, fenced code blocks, target length

Write output to [original-name].optimized.md in same directory.

Phase 3: Comparison

Follow references/comparison-checklist.md:

1. Extract all elements from original (headings, code, commands, links, facts)
2. Verify each element present in optimized (may be reformatted)
3. Create gap list of missing items

Phase 4: Second Pass

For each gap identified:

1. Determine if omission was intentional (redundant, outdated)
2. If needed, add missing content to optimized document
3. Apply formatting rules to added content

Phase 5: Summary

Present to user:

## Optimization Summary

**Original**: [filename] ([X] lines)
**Optimized**: [filename].optimized.md ([Y] lines)
**Reduction**: [Z]%

### Key Changes

1. [Change 1]
2. [Change 2]
3. [Change 3]

### Content Verified

- Headings: [count] preserved
- Code examples: [count] intact
- Commands: [count] included
- Links: [count] working

Phase 6: Finalization

Based on user choice:

• Replace: Rename original to .backup.md, rename optimized to original name, then delete the backup
• Keep both: Leave both files in place
• Discard: Delete .optimized.md, keep original unchanged

Important: After successful replacement, delete the .backup.md file. The backup is only needed temporarily during the rename operation. Keeping backups clutters the repository.

Approval Gates

Document Types

For full details: references/document-types.md

Quick Reference

Transformation Rules Summary

Structure:

• Strict heading hierarchy (H1 → H2 → H3, avoid H4+)
• Blockquote summary after H1 title
• Tables over prose
• Bullets over paragraphs
• Single topic per section
• End-load actionable instructions (checklists, summaries at END)

Content:

• Consistent terminology (no synonyms)
• Eliminate vague pronouns (it, this, that, they → specific nouns)
• Imperative form ("Run X" not "You should run X")
• Positive framing ("Use X" not "Don't use Y")

Format:

• XML tags for semantic sections
• Fenced code blocks with language
• Target length by type

For full rules: references/transformation-rules.md

References

• references/transformation-rules.md - Complete transformation rules
• references/document-types.md - Type detection and handling
• references/comparison-checklist.md - Gap detection and validation

Version History

• v1.3.0 (2026-01-18): Add accuracy verification phase

  • New Phase 1.5: Verify pattern file accuracy against codebase before optimizing
  • Spawn Explore agent to check function names, types, file paths
  • Fix inaccuracies before optimization (prevents propagating errors)
  • Added Task tool to allowed-tools for agent spawning

• v1.2.0 (2025-01-18): Research-backed transformation updates

  • Add blockquote summary rule after H1 (llms.txt standard)
  • Add end-loading rule for actionable instructions (U-shaped attention)
  • Enhance pronoun elimination guidance
  • Update heading hierarchy to avoid H4+

• v1.1.0 (2025-01-09): Delete backup after replacement

  • Backup files are now deleted after successful replacement
  • Prevents repository clutter from accumulating .backup.md files

• v1.0.0 (2025-01-09): Initial release

  • 6-phase workflow with file selection
  • Support for CLAUDE.md, skill, pattern, and general markdown
  • Comparison-based gap detection
  • Backup on replace