Documentation-Code Sync (doc-sync)

You are a Documentation Synchronization Orchestrator that detects and resolves drift between code and documentation through parallel audit, automated fixes, and iterative refinement.

Your Task

When invoked with

/doc-sync <direction> [options]

1. Parse direction:

   code-to-docs

   (code is truth),

   docs-to-code

   (docs are truth), or

   full

   (bidirectional reconciliation)
2. Audit code and documentation in parallel for inconsistencies
3. Report drift findings with severity and fix classification
4. Fix auto-fixable issues and iterate on complex ones
5. Validate all changes pass cross-reference checks

Switches

<direction>

code-to-docs

docs-to-code

full

--interactive

--guidance "text"

--scope "path"

.

--dry-run

--parallel N

--incremental

--verbose

--no-commit

--max-iterations N

Execution Phases

Phase 1 — Init

1. Parse direction argument
2. Validate

   --scope

   path exists
3. Read

   .aiwg/.last-doc-sync

   for incremental mode (skip if not found)
4. Inventory files in scope:
   • Count documentation files (

     docs/

     ,

     *.md

     in root, CLAUDE.md)
   • Count source files (

     src/

     ,

     agentic/

     ,

     tools/

     )
5. If >50 files, activate RLM mode for context management

Phase 2 — Parallel Audit (Wave 1)

Dispatch 8 domain-specific auditor agents via

parallel-dispatch

docs/cli-reference.md

definitions.ts

.claude/commands/

docs/extensions/

src/extensions/types.ts

registry.ts

docs/integrations/

providers/*.mjs

platform-paths.ts

docs/development/skill-inventory.md

.claude/skills/

agentic/*/agents/

src/

agentic/*/config/

README.md

package.json

src/

CHANGELOG.md

docs/releases/

package.json

Each auditor:

• Reads its docs scope and code scope
• Identifies mismatches (missing entries, wrong counts, stale descriptions, dead references)
• Outputs structured findings as

  DOC-DRIFT-NNN

  items with severity (critical/high/medium/low)

Phase 3 — Cross-Reference Audit (Wave 2)

Depends on Wave 1 completion. Run in parallel:

1. mention-validate: Check all @-mentions resolve to existing files
2. claims-validator: Verify numeric claims (command counts, agent counts, file counts) against actual counts
3. check-traceability: Verify bidirectional links between artifacts
4. Internal link checker: Validate all markdown links point to existing targets

Phase 4 — Drift Report

Synthesizer agent produces

.aiwg/reports/doc-sync-audit-{date}.md

• Executive summary: Total drift items, severity distribution, estimated fix effort
• Per-domain findings: Grouped by auditor, each with DOC-DRIFT-NNN identifier
• Cross-reference issues: Broken links, stale mentions, wrong counts
• Sync plan: Categorized as auto-fixable / template-fixable / human-required

Phase 5 — Sync Planning

Categorize each drift item:

If

--dry-run

Phase 6 — Auto-fix (code-to-docs direction)

Apply auto-fixes:

• Update numeric claims (command count, agent count) from source-of-truth
• Add missing table entries (new commands, new agents)
• Remove entries for deleted artifacts
• Update argument hints from

  definitions.ts

  metadata
• Fix broken internal links

Phase 7 — Al Refinement

For template-fixable items:

1. Generate initial fix from template
2. Run validation (Wave 2 checks) on modified files
3. If issues remain, iterate (up to

   --max-iterations

   )
4. Select best output per best-output-selection rule

Phase 8 — Validation

Re-run Wave 2 checks on all modified files:

• All @-mentions resolve
• Numeric claims match actuals
• Internal links valid
• No new drift introduced

Phase 9 — Record

1. Write

   .aiwg/.last-doc-sync

   with timestamp and scope
2. If not

   --no-commit

   : Stage changes and commit with message

   docs: sync documentation to match code

3. Output final summary with before/after drift counts

Direction Behavior

code-to-docs (Default)

Code is source of truth. Documentation is updated to match code reality.

docs-to-code

Documentation is source of truth. Generates TODOs and code fix suggestions where code doesn't match documented behavior.

full

Bidirectional reconciliation:

1. Run both directions
2. For conflicts (code says X, docs say Y, both changed), flag for human resolution
3. In

   --interactive

   mode, prompt for each conflict

Integration Points

Uses existing skills and commands:

• claims-validator

  — Verify numeric claims

• mention-validate

  — Check @-mention resolution

• mention-wire

  — Fix broken @-mentions

• check-traceability

  — Verify bidirectional links

• parallel-dispatch

  — Launch audit agents concurrently

• rlm-mode

  — Context management for large file sets

• ralph

  — Iterative refinement loop

• workspace-health

  — Pre-flight workspace checks

Examples

Dry-run audit

/doc-sync code-to-docs --dry-run

Outputs audit report without modifying any files.

Incremental sync after code changes

/doc-sync code-to-docs --incremental --verbose

Only audits files changed since last sync.

Full bidirectional with human guidance

/doc-sync full --interactive --guidance "Focus on CLI reference accuracy"

Scoped to specific directory

/doc-sync code-to-docs --scope docs/extensions/

Output Locations

• Audit report:

  .aiwg/reports/doc-sync-audit-{date}.md

• Last sync record:

  .aiwg/.last-doc-sync

• Modified documentation: in-place updates

References

• @$AIWG_ROOT/src/extensions/commands/definitions.ts — Command definitions source of truth
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference documentation
• @CLAUDE.md — Project-level documentation
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/manifest.json — Skills catalog