Update Doc

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

<when_to_use>

When to Use

Invoke when user says:

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

</when_to_use>

Workflow

<phase_details>

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:

   markdown

   ## 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.

</phase_details>

<approval_gates>

Approval Gates

</approval_gates>

<document_types>

Document Types

For full details: references/document-types.md

</document_types>

<quick_reference>

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

</quick_reference>

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>

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

</version_history>