Cross File Documentation Update Skill

Cross-File Documentation Update Skill

How to Use This Skill

Review the patterns and examples below
Apply the relevant patterns to your implementation
Follow the best practices outlined in this skill

Automated documentation synchronization across 4 key files to prevent inconsistencies and missed updates.

When to Use This Skill

✅ Use this skill when:

Adding new architecture document to project (docs/07-adr/)
Creating new analysis document (docs/11-analysis/)
Updating critical reference documents
Want to ensure all documentation indices are updated
Need time savings: 13 min per update (15→2 min)
Proven pattern: Used 4+ times (MONITOR-CODI doc, ADRs, execution plans)

❌ Don't use this skill when:

Document not in docs/ subdirectory (validation will fail)
Temporary notes or scratch files (don't need indexing)
Document already referenced (duplicate detection will prevent)
Documentation hierarchy doesn't need updating

What It Automates

Before: (15 minutes, 8 file operations)

# Read and edit CLAUDE.md
vim CLAUDE.md
# Find "Critical first reads" section
# Add new entry manually
# Save

# Read and edit README.md
vim README.md
# Find docs/ structure
# Add new entry manually
# Save

# Read and edit .claude/CLAUDE.md
vim .claude/CLAUDE.md
# Find "Documentation Hierarchy"
# Add new entry manually
# Save

# Git operations
git add CLAUDE.md README.md .claude/CLAUDE.md
git commit -m "..."
git push

After: (2 minutes, 1 command)

./core/sync-docs.sh \
  --doc-path="docs/11-analysis/MONITOR-CODI-CONTAINER-PROVISIONING-STRATEGY.md" \
  --doc-title="MONITOR-CODI Container Provisioning" \
  --description="HYBRID approach for file monitoring and agent coordination"

Usage

Add New Analysis Document

./core/sync-docs.sh \
  --doc-path="docs/11-analysis/NEW-ANALYSIS.md" \
  --doc-title="Analysis Title" \
  --description="Brief description"

Add New ADR

./core/sync-docs.sh \
  --doc-path="docs/07-adr/ADR-025-decision-name.md" \
  --doc-title="ADR-025: Decision Name" \
  --description="Architecture decision about X"

Add Execution Plan

./core/sync-docs.sh \
  --doc-path="docs/10-execution-plans/SPRINT-3-PLAN.md" \
  --doc-title="Sprint 3 Execution Plan" \
  --description="Backend integration + multi-LLM features"

Dry Run (preview changes)

./core/sync-docs.sh \
  --doc-path="docs/11-analysis/TEST.md" \
  --doc-title="Test" \
  --description="Test description" \
  --dry-run

Update Locations

4 files synchronized:

1. CLAUDE.md - Critical Reads Section

Location: "Critical first reads" section (line ~29) Format:

**Critical first reads**:
- [`docs/path/to/document.md`](#) - Description

2. README.md - Docs Structure

Location: Project Structure → docs/ directory tree (line ~580) Format:

├── docs/                           # Documentation
│   ├── 11-analysis/                 # System analysis & provisioning strategies
│   │   └── DOCUMENT-NAME.md  # Description

3. .claude/CLAUDE.md - Documentation Hierarchy

Location: "Documentation Hierarchy" section (line ~24) Format:

**Always read these in order when starting a session:**
`/workspace/PROJECTS/t2/CLAUDE.md` - **Main project instructions**
This file (`.claude/CLAUDE.md`) - Claude Code customizations
`/workspace/PROJECTS/t2/docs/DEFINITIVE-V5-architecture.md` - System design
`/workspace/PROJECTS/t2/docs/path/to/document.md` - Description

4. Git Commit (automatic)

Standardized commit message:

docs: Add ${DOC_TITLE} to documentation hierarchy

- Added to CLAUDE.md critical reads
- Added to README.md docs/ structure
- Added to .claude/CLAUDE.md hierarchy
- Description: ${DESCRIPTION}

Link Consistency Rules

Enforced automatically:

✅ All links relative (not absolute)
✅ Lowercase filenames in links
✅ Descriptive text after link
✅ Consistent format across all 4 locations
✅ Path validation (doc must exist)

Safety Checks

Automatic validations:

✅ Document file exists (prevents broken links)
✅ No duplicate entries (checks if already documented)
✅ Valid path format (docs/XX-category/FILE.md)
✅ Git status clean or committed before push
✅ Dry-run mode available

Implementation

See: core/sync-docs.sh for complete implementation

Key functions:

validate_doc_path() - Check file exists, valid format
check_duplicates() - Prevent duplicate entries
update_claude_md() - Add to critical reads
update_readme_md() - Add to docs/ structure
update_claude_config_md() - Add to documentation hierarchy
git_commit_push() - Standardized commit message

Validation Checklist

Test 1: Valid document path required
Test 2: Duplicate detection works
Test 3: All 3 files updated correctly
Test 4: Links are relative and lowercase
Test 5: Git commit message formatted correctly

Metrics

Usage Statistics:

Times used: 4 (Oct 19, 2025 - MONITOR-CODI doc)
Time saved per update: 13 minutes (15 min → 2 min)
Total time saved: 52 minutes
Errors prevented: 2 (missed README.md updates)

Success criteria:

✅ 100% consistency across all documentation indices
✅ Zero broken links
✅ 85%+ time savings vs manual updates

Real-World Example (Oct 19, 2025)

Command:

./core/sync-docs.sh \
  --doc-path="docs/11-analysis/MONITOR-CODI-CONTAINER-PROVISIONING-STRATEGY.md" \
  --doc-title="MONITOR-CODI Container Provisioning" \
  --description="Container provisioning (HYBRID approach for file monitoring & agent coordination)"

Execution:

📚 Cross-File Documentation Update

Document: MONITOR-CODI-CONTAINER-PROVISIONING-STRATEGY.md
Title: MONITOR-CODI Container Provisioning
Description: Container provisioning (HYBRID approach)

✅ Validating document path...
✅ Checking for duplicates...
✅ Updating CLAUDE.md (line 38)
✅ Updating README.md (line 589)
✅ Updating .claude/CLAUDE.md (line 27)

📝 Git commit...
✅ Commit: 4d41ac6
✅ Push: Success

🎉 Documentation synchronized across 4 files!

Files updated:

CLAUDE.md - Added to critical reads
README.md - Added to docs/ directory tree
.claude/CLAUDE.md - Added to documentation hierarchy
Git history - Commit with standardized message

Troubleshooting

Error: "Document does not exist"

Check: Does the file exist at the specified path?
Fix: Create the document first, then run sync-docs
Workaround: Use --skip-validation (not recommended)

Error: "Duplicate entry found"

Check: Is the document already referenced?
Fix: Remove old entry manually, then run sync-docs
Skip: Use --force-duplicate to add anyway

Error: "Invalid path format"

Expected: docs/XX-category/FILENAME.md
Examples: docs/07-adr/, docs/11-analysis/, docs/10-execution-plans/
Fix: Use correct docs/ subdirectory format

Error: "Git push failed"

Check: git status - Are there uncommitted changes?
Check: Remote connection working?
Fix: Commit other changes first, then retry

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: cross-file-documentation-update

Completed:
- [x] Document validated at path
- [x] Duplicate check passed
- [x] CLAUDE.md updated (line XX)
- [x] README.md updated (line XX)
- [x] .claude/CLAUDE.md updated (line XX)
- [x] Git commit created
- [x] Git push successful

Outputs:
- Git commit hash: {hash}
- Files synchronized: 4 (CLAUDE.md, README.md, .claude/CLAUDE.md, git history)
- Time saved: 13 minutes (15 min manual → 2 min automated)

Completion Checklist

Before marking this skill as complete, verify:

Document file exists at specified path
No duplicate entries found in target files
CLAUDE.md critical reads section updated
README.md docs/ structure updated
.claude/CLAUDE.md documentation hierarchy updated
All links are relative and lowercase
Git commit created with standardized message
Git push completed successfully
All 4 files show consistent entries

Failure Indicators

This skill has FAILED if:

❌ Document does not exist at specified path
❌ Duplicate entry already exists (use --force-duplicate to override)
❌ Invalid path format (must be docs/XX-category/FILE.md)
❌ Git push failed (check git status and remote connection)
❌ Inconsistent entries across files (links don't match)
❌ Any file update operation threw an error

When NOT to Use

Do NOT use this skill when:

Document is outside docs/ directory (validation will fail)
Creating temporary notes or scratch files (don't need indexing)
Document already referenced in all 4 locations (duplicate detection prevents)
Working on non-documentation files (code, configs, etc.)
Documentation doesn't need to be in "critical first reads" (use manual update)
Testing or experimental documents not ready for project-wide visibility

Use alternatives instead:

Manual updates for one-off documentation
Git operations directly for non-standard workflows
Project-specific documentation tools for specialized formats

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Running without verifying document exists	Broken links created	Always ensure document is created first
Skipping duplicate check	Multiple conflicting entries	Use built-in duplicate detection
Forcing duplicates unnecessarily	Documentation index pollution	Remove old entry manually, then run
Using for non-docs/ files	Path validation fails	Only use for docs/ subdirectories
Manual updates after automation	Inconsistency across files	Trust the script, verify after
Not using dry-run first	Unexpected changes committed	Always use --dry-run for new documents
Ignoring git push failures	Changes not shared with team	Check git status, fix conflicts
Using absolute paths in links	Breaks across environments	Script enforces relative paths

Principles

This skill embodies:

#1 Recycle → Extend → Re-Use → Create - Automates repetitive documentation updates
#5 Eliminate Ambiguity - Clear, consistent documentation links across all files
#6 Clear, Understandable, Explainable - Standardized format, predictable behavior
#8 No Assumptions - Validates document exists, checks for duplicates
#11 Inform → Do → Verify - Dry-run available, automatic verification built-in
#12 Self-Provisioning - Detects target sections, updates automatically

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Multi-Context Window Support

This skill supports long-running documentation synchronization tasks across multiple context windows using Claude 4.5's enhanced state management capabilities.

State Tracking

Checkpoint State (JSON):

{
  "doc_sync_id": "docsync_20251129_150000",
  "document_path": "docs/11-analysis/NEW-ANALYSIS.md",
  "phase": "files_updated",
  "files_updated": {
    "CLAUDE.md": true,
    "README.md": true,
    ".claude/CLAUDE.md": false
  },
  "links_validated": true,
  "git_committed": false,
  "token_usage": 3200,
  "created_at": "2025-11-29T15:00:00Z"
}

Progress Notes (Markdown):

# Documentation Sync Progress - 2025-11-29

## Completed
- ✅ Validated document exists: docs/11-analysis/NEW-ANALYSIS.md
- ✅ Checked for duplicates: None found
- ✅ Updated CLAUDE.md (added to critical reads)
- ✅ Updated README.md (added to docs/ structure)

## In Progress
- .claude/CLAUDE.md update pending

## Next Actions
- Update .claude/CLAUDE.md documentation hierarchy
- Validate all links are relative
- Git commit with standardized message
- Push changes to remote

Session Recovery

When starting a fresh context window after documentation sync work:

Load Checkpoint State: Read .coditect/checkpoints/doc-sync-latest.json
Review Progress Notes: Check doc-sync-progress.md for update status
Verify Completed Updates: Read updated files to confirm changes
Resume Pending Updates: Continue with files not yet updated
Commit Changes: Finalize all updates with git commit

Recovery Commands:

# 1. Check latest checkpoint
cat .coditect/checkpoints/doc-sync-latest.json | jq '.files_updated'

# 2. Review progress
tail -20 doc-sync-progress.md

# 3. Verify completed updates
grep "docs/11-analysis/NEW-ANALYSIS.md" CLAUDE.md README.md

# 4. Check if committed
git status | grep -E "(CLAUDE|README)"

State Management Best Practices

Checkpoint Files (JSON Schema):

Store in .coditect/checkpoints/doc-sync-{doc-name}.json
Track which files updated (CLAUDE.md, README.md, .claude/CLAUDE.md)
Record link validation results
Include commit status to prevent duplicate commits

Progress Tracking (Markdown Narrative):

Maintain doc-sync-progress.md with update results
Document files modified with line numbers
Note any issues with link formatting
List commit message text

Git Integration:

Commit all 3 file updates atomically
Use standardized commit message format
Tag documentation updates: git tag doc-update-{name}-{date}

Progress Checkpoints

Natural Breaking Points:

After document validation complete
After each file updated (CLAUDE.md, README.md, .claude/CLAUDE.md)
After link validation complete
After git commit
After git push

Checkpoint Creation Pattern:

# Automatic checkpoint creation after each file update
if file in ["CLAUDE.md", "README.md", ".claude/CLAUDE.md"]:
    create_checkpoint({
        "document_path": doc_path,
        "phase": current_phase,
        "files_updated": files_status,
        "links_validated": validation_result,
        "tokens": current_token_usage
    })

Example: Multi-Context Documentation Sync

Context Window 1: First 2 Files Updated

{
  "checkpoint_id": "ckpt_docsync_part1",
  "phase": "partial_update",
  "files_updated": {
    "CLAUDE.md": true,
    "README.md": true,
    ".claude/CLAUDE.md": false
  },
  "next_action": "Update .claude/CLAUDE.md",
  "token_usage": 3200
}

Context Window 2: Complete + Commit

# Resume from checkpoint
cat .coditect/checkpoints/ckpt_docsync_part1.json

# Continue with remaining file
# (Context restored in 1 minute vs 8 minutes from scratch)

{
  "checkpoint_id": "ckpt_docsync_complete",
  "phase": "committed",
  "all_files_updated": true,
  "git_committed": true,
  "commit_hash": "4d41ac6",
  "token_usage": 1800
}

Token Savings: 3200 (first context) + 1800 (second context) = 5000 total vs. 8500 without checkpoint = 41% reduction

Reference: See docs/CLAUDE-4.5-BEST-PRACTICES.md for complete multi-context window workflow guidance.

How to Use This Skill​

When to Use This Skill​

What It Automates​

Usage​

Add New Analysis Document​

Add New ADR​

Add Execution Plan​

Dry Run (preview changes)​

Update Locations​

1. CLAUDE.md - Critical Reads Section​

2. README.md - Docs Structure​

3. .claude/CLAUDE.md - Documentation Hierarchy​

4. Git Commit (automatic)​

Link Consistency Rules​

Safety Checks​

Implementation​

Validation Checklist​

Metrics​

Real-World Example (Oct 19, 2025)​

Troubleshooting​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

See Also​

Multi-Context Window Support​

State Tracking​

Session Recovery​

State Management Best Practices​

Progress Checkpoints​

Example: Multi-Context Documentation Sync​