e2e-doc-sync

E2E Doc Sync — Documentation Gap Scanner, Writer & Verifier

Routing

Input	Route
bare invocation	→ Full Sync
--fix	→ Full Sync (alias for bare — kept for backward compat)
--check	→ Report Only (no writes)
--probe-only	→ Verify Existing Docs (skip Phases 1-3 and 5, run Phase 4 on all existing docs, then Phase 6)
--auto	→ Full Sync (skip confirmation)
--section <doc-file>	→ Targeted Sync (one doc file)
--diff <ref>	→ Use explicit git diff base instead of auto-detect

Phase 1: Static Scan

Step 0 — Diff-Aware Pre-Processing (automatic)

Before inventorying files, compute a diff of changed skill/agent content since the last version tag. This catches behavioral branches and other features that surface-level extraction (flags, headings) would miss.

Find diff base:

# Auto-detect: find the most recent e2e-pipeline version tag
DIFF_BASE=$(git -C ${CLAUDE_PLUGIN_ROOT} tag -l "e2e-pipeline-v*" --sort=-v:refname | head -1)
# If --diff <ref> provided, use that instead
# If no tags exist, use HEAD~10 as fallback — warn user: "No version tags found, using HEAD~10. Diff coverage may be incomplete for older changes."

Extract changed content:

git -C ${CLAUDE_PLUGIN_ROOT} diff ${DIFF_BASE}..HEAD \
  -- 'skills/*/SKILL.md' 'agents/*.md' \
  | grep '^+' | grep -v '^+++' | sed 's/^+//'

Group added lines by source file. Cap diff summary at 2000 chars.

Step 1 — Inventory & Cross-Reference

1. Read references/doc-sync-context.md → load Source Map, Doc Structure, Probe Config, Post-Sync Hooks
2. Inventory source files:
   • Glob skills/*/SKILL.md → for each: extract skill name, description, all --flags, modes (from routing tables), key concepts
   • Glob agents/*.md → for each: extract agent name, tools, input contract fields, dispatch trigger
   • Glob hooks/ → for each: extract event type, trigger condition, affected tools
3. Inventory documentation:
   • Glob docs/*.md + README.md → for each: extract title, section headings, mentioned features, example count
4. Cross-reference: for each Source Map entry, search its Doc Target for coverage of every extracted feature
   • If diff summary exists: additionally check whether diff-added content has doc coverage
   • Orphan check: source files found in Step 2 inventory but absent from Source Map → classify as Critical gap ("source exists, no Source Map entry — doc target unknown"). Include file path and inferred doc target in gap report. This catches newly added skills/agents that Phase 5 hasn't registered yet.
5. Classify gaps:
   • Critical: source feature exists, zero mention in any doc
   • Warning: mentioned in one doc but not explained (e.g., flag listed in table but no usage guide)
   • Info: documented but could be improved (missing example, stale cross-reference)
6. Meta-doc consistency check: verify CLAUDE.md skill/agent counts, README docs table completeness, plugin.json description accuracy