Documentation Sync

Review code changes and update project documentation for consistency.

Mode

Delta Mode Baseline

Identify changed files using merge-base (not a fixed commit count):

# Branch changes since diverging from main
git diff --name-only $(git merge-base HEAD origin/main)...HEAD
# Plus staged + unstaged
git diff --name-only --cached
git diff --name-only

Combine the results into a single list of changed files. Then use the Impact Mapping to identify which docs may need updates.

Impact Mapping

Map changed areas to the docs they affect:

Cross-Reference Pairs

Always verify consistency between these paired docs:

1. CLAUDE.md Commands section <-> AGENTS.md Commands section (same entries)
2. CLAUDE.md Documentation Map paths <-> actual files on disk
3. CLAUDE.md Hard Rules <-> AGENTS.md Hard rules
4. ARCHITECTURE.md monorepo layout <-> actual apps/ + packages/ dirs
5. specs/DESIGN.md table <-> actual specs/design-specs/ + specs/designs/ contents
6. specs/design-specs/index.md table <-> actual design files
7. specs/product-specs/index.md table <-> actual specs/product-specs/*.md files
8. specs/PLANS.md table <-> specs/exec-plans/{active,completed}/ contents
9. specs/FRONTEND.md Pages table <-> apps/web/src/app.tsx routes

Scope Filters

When the user specifies a scope keyword, limit the check to that area:

Rules

1. Never remove forward-looking documentation — ask if uncertain whether content is aspirational or stale.
2. Preserve original language (English/Chinese) and writing style of existing docs.
3. For backend API updates, treat apps/controller as the source of truth; do not reference removed legacy package paths.
4. Always verify CLAUDE.md <-> AGENTS.md consistency after any update to either file.
5. Do NOT auto-commit — present the diff summary and let the user decide when to commit.

Workflow

1. Determine mode from user request (default: delta).
2. If delta mode: run the git diff commands above, collect changed files.
3. Map changed files to affected docs using the Impact Mapping.
4. Read each affected doc and compare against current code.
5. Check all Cross-Reference Pairs for consistency.
6. Present findings: what's outdated, what's missing, what's inconsistent.
7. Apply fixes with user approval.
8. After fixes, re-verify Cross-Reference Pairs touched by changes.