document-sync

Document Sync Skill for Claude Code

Overview

This skill provides comprehensive documentation synchronization by analyzing your actual codebase, tech stack, configuration, and architecture to ensure all documentation remains current and accurate. It operates on a "verify, never assume" principle, performing end-to-end comparisons against real code and dependencies to detect documentation drift automatically.

Core Principles

• Verify, Never Assume: Documentation is only updated after end-to-end comparison against real, current code and dependencies
• Deep System Introspection: Checks languages, frameworks, APIs, DBs, config, code patterns, and deployment targets
• Doc Trust Score: Every doc gets a trust rating based on evidence found in the codebase and config files

Quick Start

Natural Language Commands:

• "Run document sync analysis on my project"
• "Update docs so every API route matches the code"
• "Check if any doc mentions features no longer in the app"
• "List undocumented config variables"

Slash Commands:

• /docs-sync — Runs analysis and outputs a complete report on outdated/inaccurate sections
• /docs-update-strict — Suggests only changes verified by found code/config evidence
• /docs-rewrite-missing — Fills gaps for undocumented features based on live source
• /docs-patch-pr — Makes all doc changes as a PR, zero surprises

Operation Workflow

Phase 1: Full System Scan

Execute the system scanning script to analyze your codebase:

# Run comprehensive system scan
python3 .claude/skills/document-sync/scripts/system_scan.py

This phase automatically:

1. Tech Stack Detection - Parse package.json, requirements.txt, pom.xml, etc. for frameworks, DBs, and build tools
2. Project Structure Analysis - Map src/, lib/, app/, and config/ directories for real usage
3. Architecture Detection - Identify data flows, auth methods, sync strategies, and cloud/on-prem deployment

Key Outputs: system_state.json and code_features_report.md

Phase 2: Documentation Verification

Execute the documentation verification script:

# Verify all documentation against code
python3 .claude/skills/document-sync/scripts/verify_docs.py

This phase:

1. Docs Content Inventory - List all Markdown, docs/, and README files
2. Technical Validation - Cross-reference each doc claim with real code/config
3. Relevance & Quality Scoring - Rate every doc: current, needs update, obsolete, or missing

Key Outputs: doc_verification_report.md and docs_update_plan.md

Phase 3: Automated or Assisted Document Updating

Based on the verification results, choose your update approach:

# Dry run - see what would change
python3 .claude/skills/document-sync/scripts/update_docs.py --mode=dry-run

# Suggest mode - get suggestions for review
python3 .claude/skills/document-sync/scripts/update_docs.py --mode=suggest

# Auto-update with backups
python3 .claude/skills/document-sync/scripts/update_docs.py --mode=auto-update

Configuration

Create .claude/document-sync-skill.yml in your project root:

mode: suggest  # suggest | dry-run | auto-update
protected_docs:
  - README.md
  - docs/security.md
review_required_for:
  - section removal
  - breaking doc changes
output_reports:
  - doc_verification_report.md
  - docs_update_plan.md

Safety & Controls

• Never deletes or rewrites without firm code evidence
• Always creates a diff and backup before change
• User sets conservatism level: dry-run, suggest-only, or auto-update
• All changes are traceable—committed separately with actionable summaries

Output Examples

doc_verification_report.md

Doc Section	Status	Evidence Found	Action
/docs/api.md GET /users	Current	Endpoint in code (src/routes/)	Keep
/docs/db-setup.md PouchDB	Outdated	No mention in codebase	Remove/Update
/README.md Feature X	Missing	Found in src/feature-x.ts	Add details

docs_update_plan.md

• Remove obsolete DB doc: /docs/db-setup.md (no longer in code)
• Add section to /README.md for unlisted Feature X
• Rewrite /docs/config.md section on env vars (now using .env.local)
• Confirm all code-blocks in /docs/usage.md still run

Resources

This skill includes specialized scripts and references for comprehensive document synchronization:

scripts/

• system_scan.py - Comprehensive codebase analysis and tech stack detection
• verify_docs.py - Documentation verification and validation against code
• update_docs.py - Automated document updating with safety controls

references/

• tech_detection_patterns.md - Patterns for identifying frameworks and technologies
• doc_validation_rules.md - Rules for validating documentation accuracy
• update_templates.md - Templates for common documentation updates

assets/

• report_templates/ - Markdown templates for verification and update reports
• config_schemas/ - JSON schemas for configuration validation

Safety Checklist

• Full project scan completed
• All doc claims matched to real code/config
• Backups created before overwriting docs
• No deletions/rewrites without clear code evidence
• All updates and removals require user review
• All code examples in docs validated with real source

Success Metrics

• 100% doc claims match code/config truth
• 0 obsolete/incorrect references in doc set
• All new features in code are documented within 2 days
• Doc update effort reduced by >60% for every release

---

MANDATORY USER VERIFICATION REQUIREMENT

Policy: No Fix Claims Without User Confirmation

CRITICAL: Before claiming ANY issue, bug, or problem is "fixed", "resolved", "working", or "complete", the following verification protocol is MANDATORY:

Step 1: Technical Verification

• Run all relevant tests (build, type-check, unit tests)
• Verify no console errors
• Take screenshots/evidence of the fix

Step 2: User Verification Request

REQUIRED: Use the AskUserQuestion tool to explicitly ask the user to verify the fix:

"I've implemented [description of fix]. Before I mark this as complete, please verify:
1. [Specific thing to check #1]
2. [Specific thing to check #2]
3. Does this fix the issue you were experiencing?

Please confirm the fix works as expected, or let me know what's still not working."

Step 3: Wait for User Confirmation

• DO NOT proceed with claims of success until user responds
• DO NOT mark tasks as "completed" without user confirmation
• DO NOT use phrases like "fixed", "resolved", "working" without user verification

Step 4: Handle User Feedback

• If user confirms: Document the fix and mark as complete
• If user reports issues: Continue debugging, repeat verification cycle

Prohibited Actions (Without User Verification)

• Claiming a bug is "fixed"
• Stating functionality is "working"
• Marking issues as "resolved"
• Declaring features as "complete"
• Any success claims about fixes

Required Evidence Before User Verification Request

1. Technical tests passing
2. Visual confirmation via Playwright/screenshots
3. Specific test scenarios executed
4. Clear description of what was changed

Remember: The user is the final authority on whether something is fixed. No exceptions.