source-command-dev-docs-sync

name	source-command-dev-docs-sync
description	Sync documentation with project state using ICAV workflow. Usage: /dev-docs-sync [cleanup=true]

source-command-dev-docs-sync

Use this skill when the user asks to run the migrated source command dev-docs-sync.

Command Template

Documentation Sync and Update

Synchronize documentation with actual project state using the ICAV (Inventory-Compare-Adapt-Validate) workflow.

ICAV Workflow

INVENTORY → COMPARE → ADAPT → VALIDATE → COMMIT

Core principle: Project state is truth. Docs follow reality. Every doc claim must trace to an artifact.

Preferred Tools (Priority Order)

Task	Primary Tool	Fallback
Find files	Glob	ls
Search patterns	Grep	-
List directories	ls	-
Read files	Read	-

Parameters

Parameter	Values	Default	Description
cleanup	true, false	false	Remove completed TODOs and obsolete content

---

Phase 1: INVENTORY

Goal: Collect project facts and list documentation files.

1.1 Load Project Context

cat VERSION
git log --oneline -20

Read project.yaml for the documentation language:

language:
  docs: English  # or Chinese / 中文

Default if missing: English. Aliases: Chinese ≡ 中文. All documentation content written or edited in Phase 3 MUST be in language.docs. File names remain English regardless.

1.2 Inventory Project Artifacts

# Documentation files
ls docs/

# Repository references
ls repos/

# Repo metadata
ls repos-meta/ 2>/dev/null

# Slash commands
ls .Codex/commands/*.md

# Skills
ls -d .Codex/skills/*/ 2>/dev/null

# Project files
ls *.md VERSION .gitignore

1.3 Inventory Documentation Files

File	Purpose
AGENTS.md	AI dev guide — conventions, structure, rules
README.md	Project overview — purpose, structure
docs/XXX-*.md	Design documents — technical specs, architecture
CHANGELOG.md	Release history (managed by /dev-bump)

Excluded from sync:

• CHANGELOG.md (managed by /dev-bump)
• repos/ and repos-meta/ (external references, protected)

---

Phase 2: COMPARE

Goal: Find mismatches between docs and reality.

CRITICAL: Each comparison must run a concrete command against a specific doc section. Do NOT skip any row.

Source-of-Truth Map

AGENTS.md

Doc Section	Source of Truth	Command
File naming convention	filesystem	ls docs/ — verify all follow XXX-name.md pattern
Protected directories	filesystem	ls repos/ repos-meta/ — verify they exist
Git commit rules	git log	git log --oneline -5 — verify conventions followed

README.md

Doc Section	Source of Truth	Command
Project description	docs/ contents	Compare README overview with actual doc topics
Directory structure	filesystem	ls -la vs README tree listing
Version	VERSION file	cat VERSION vs README version mention

docs/ files

Doc Section	Source of Truth	Command
File numbering	filesystem	ls docs/ — verify sequential, no gaps
Cross-references	docs content	grep -r 'docs/' docs/ — verify internal links valid
Referenced repos	repos/	ls repos/ vs repo mentions in docs

2.1 Git Diff Focus (Optional Acceleration)

git diff --name-only $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~20)..HEAD

Use to prioritize which rows to check first, but always check all rows.

---

Phase 3: ADAPT

Goal: Fix every mismatch found in Phase 2.

For each mismatch:

1. Read the doc section
2. Read the source of truth
3. Edit the doc to match reality
4. Preserve surrounding formatting and style

Rules:

• Never change project artifacts to match docs — docs follow reality
• Preserve existing doc structure (tables stay tables, trees stay trees)
• Don't add new sections — only update existing content
• If a doc file is missing an entire topic, note it in the report but don't create new sections
• Write documentation content in the language from project.yaml → language.docs (default: English). File names remain English regardless of docs language.

Cleanup (if cleanup=true)

• Remove completed TODO items
• Remove obsolete content referencing deleted features
• No dates, no status badges, compact formatting

---

Phase 4: VALIDATE

Goal: Verify sync succeeded.

4.1 Re-run Failed Comparisons

For every mismatch fixed in Phase 3, re-run the comparison command to verify the fix.

4.2 Check Internal Links

# Find all markdown links in docs/
grep -rohP '\[.*?\]\(([^)]+)\)' docs/*.md | grep -oP '\(([^)]+)\)' | tr -d '()'

Verify each relative link target exists.

4.3 Generate Report

Documentation Sync Report
==========================

Comparisons Run: [N]
Mismatches Found: [N]
Mismatches Fixed: [N]

Changes:
- [file]: [what changed]
- [file]: [what changed]

Verified: [all fixed / N remaining]

4.4 Commit

/dev-commit "sync docs with project state"

---

Checklist

INVENTORY
[ ] VERSION, git log loaded
[ ] Documentation files listed
[ ] Repository references inventoried
[ ] Slash commands listed

COMPARE (Source-of-Truth Map — every row)
[ ] AGENTS.md: naming convention, protected dirs, git rules
[ ] README.md: description, structure, version
[ ] docs/ files: numbering, cross-references, repo mentions

ADAPT
[ ] All mismatches fixed
[ ] Cleanup applied (if requested)

VALIDATE
[ ] Fixed comparisons re-verified
[ ] Internal links valid
[ ] Report generated
[ ] Changes committed