Doc Sync

Maintains the CLAUDE.md navigation hierarchy and README.md invisible knowledge docs across a repository. This skill is self-contained and performs all documentation work directly.

Documentation Conventions

For authoritative CLAUDE.md and README.md format specification:

The conventions/ directory contains all universal documentation standards.

Scope Resolution

Determine scope FIRST:

User Request Scope

"sync docs" / "update documentation" / no specific path REPOSITORY-WIDE

"sync docs in src/validator/" DIRECTORY: src/validator/ and descendants

"update CLAUDE.md for parser.py" FILE: single file's parent directory

For REPOSITORY-WIDE scope, perform a full audit. For narrower scopes, operate only within the specified boundary.

Workflow

Phase 1: Discovery

Map directories requiring CLAUDE.md verification:

Find all directories (excluding .git, node_modules, pycache, etc.)

find . -type d ( -name .git -o -name node_modules -o -name pycache -o -name .venv -o -name target -o -name dist -o -name build ) -prune -o -type d -print

For each directory in scope, record:

• Does CLAUDE.md exist?

• If yes, does it have the required table-based index structure?

• What files/subdirectories exist that need indexing?

Phase 2: Audit

For each directory, check for drift and misplaced content:

<audit_check dir="[path]"> CLAUDE.md exists: [YES/NO] Has table-based index: [YES/NO] Files in directory: [list] Files in index: [list] Missing from index: [list] Stale in index (file deleted): [list] Triggers are task-oriented: [YES/NO/PARTIAL] Contains misplaced content: [YES/NO] (architecture/design docs that belong in README.md) README.md exists: [YES/NO] README.md warranted: [YES/NO] (invisible knowledge present?) </audit_check>

Phase 3: Content Migration

Critical: If CLAUDE.md contains content that does NOT belong there, migrate it:

Content that MUST be moved from CLAUDE.md to README.md:

• Architecture explanations or diagrams

• Design decision documentation

• Component interaction descriptions

• Overview sections with prose (beyond one sentence)

• Invariants or rules documentation

• Any "why" explanations beyond simple triggers

• Key Invariants sections

• Dependencies sections (explanatory -- index can note dependencies exist)

• Constraints sections

• Purpose sections with prose (beyond one sentence)

• Any bullet-point lists explaining rationale

Content that MAY stay in CLAUDE.md (operational sections):

• Build commands specific to this directory

• Test commands specific to this directory

• Regeneration/sync commands (e.g., protobuf regeneration)

• Deploy commands

• Other copy-pasteable procedural commands

Test: Ask "is this explaining WHY or telling HOW?" Explanatory content (architecture, decisions, rationale) goes to README.md. Operational content (commands, procedures) stays in CLAUDE.md.

Migration process:

• Identify misplaced content in CLAUDE.md

• Create or update README.md with the architectural content

• Strip CLAUDE.md down to pure index format

• Add README.md to the CLAUDE.md index table

Phase 4: Index Updates

For each directory needing work:

Creating/Updating CLAUDE.md:

• Use the appropriate template (ROOT or SUBDIRECTORY)

• Populate tables with all files and subdirectories

• Write "What" column: factual content description

• Write "When to read" column: action-oriented triggers

• If README.md exists, include it in the Files table

Creating README.md (when invisible knowledge exists):

• Verify invisible knowledge exists (semantic trigger, not structural)

• Document architecture, design decisions, invariants, tradeoffs

• Apply the content test: remove anything visible from code

• Keep as concise as possible while capturing all invisible knowledge

• Must be self-contained: do not reference external authoritative sources

Phase 5: Verification

After all updates complete, verify:

• Every directory in scope has CLAUDE.md

• All CLAUDE.md files use table-based index format (pure navigation)

• No drift remains (files <-> index entries match)

• No misplaced content in CLAUDE.md (explanatory prose moved to README.md)

• README.md files are indexed in their parent CLAUDE.md

• CLAUDE.md contains only: one-sentence overview + tabular index + operational sections

• README.md exists wherever invisible knowledge was identified

• README.md files are self-contained (no external authoritative references)

Output Format

Doc Sync Report

Scope: [REPOSITORY-WIDE | directory path]

Changes Made

• CREATED: [list of new CLAUDE.md files]
• UPDATED: [list of modified CLAUDE.md files]
• MIGRATED: [list of content moved from CLAUDE.md to README.md]
• CREATED: [list of new README.md files]
• FLAGGED: [any issues requiring human decision]

Verification

• Directories audited: [count]
• CLAUDE.md coverage: [count]/[total] (100%)
• CLAUDE.md format: [count] pure index / [count] needed migration
• Drift detected: [count] entries fixed
• Content migrations: [count] (prose moved to README.md)
• README.md files: [count] (wherever invisible knowledge exists)
• Self-contained: [YES/NO] (no external authoritative references)

Exclusions

DO NOT create CLAUDE.md for:

• Generated files directories (dist/, build/, compiled outputs)

• Vendored dependencies (node_modules/, vendor/, third_party/)

• Git internals (.git/)

• IDE/editor configs (.idea/, .vscode/ unless project-specific settings)

• Stub directories (contain only .gitkeep or no code files) - these do not require CLAUDE.md until code is added

DO NOT index (skip these files in CLAUDE.md):

• Generated files (.generated., compiled outputs)

• Vendored dependency files

DO index:

• Hidden config files that affect development (.eslintrc, .env.example, .gitignore)

• Test files and test directories

• Documentation files (including README.md)

Anti-Patterns

Index Anti-Patterns

Too vague (matches everything):

| config/ | Configuration | Working with configuration |

Content description instead of trigger:

| cache.rs | Contains the LRU cache implementation | - |

Missing action verb:

| parser.py | Input parsing | Input parsing and format handling |

Correct Examples

| cache.rs | LRU cache with O(1) get/set | Implementing caching, debugging misses, tuning eviction | | config/ | YAML config parsing, env overrides | Adding config options, changing defaults, debugging config loading |

When NOT to Use This Skill

• Single file documentation (inline comments, docstrings) - handle directly

• Code comments - handle directly

• Function/module docstrings - handle directly

• This skill is for CLAUDE.md/README.md synchronization specifically

Reference

For additional trigger pattern examples, see references/trigger-patterns.md .