/doc-sync

namespace: aiwg
name: doc-sync
description: Synchronize documentation and code with bounded, scope-first drift checks
commandHint:
  argumentHint: "<direction> [--dry-run] [--scope <path>] [--incremental] [--parallel N]"
  allowedTools: Task, Read, Write, Bash, Glob, Grep, Edit
  category: utilities
  orchestration: true
platforms: [all]

Doc Sync

Detect and resolve documentation drift without front-loading a full repository audit. Treat standard Claude Code Sonnet context as the baseline.

Triggers

Users may say:

• "doc sync"
• "sync docs"
• "fix doc drift"
• "reconcile docs"
• "update docs to match code"
• "update code to match docs"
• "check for documentation drift"

Parameters

`direction` is required:

• `code-to-docs`: update docs to match code
• `docs-to-code`: identify code gaps against docs
• `full`: bidirectional reconciliation with human review for conflicts

Options:

• `--dry-run`: report only, no file edits
• `--scope <path>`: limit the audit to a subtree or file group
• `--incremental`: start from changed files since the last sync, then current

git changed files if no last-run record exists

• `--parallel N`: cap concurrent auditors; default `2`, maximum `4`

Artifact root resolution

Treat every `.aiwg/...` path below as a logical artifact path. Before reading or writing sync state, working evidence, or reports, run `aiwg artifacts path` from the active workspace and use the returned absolute directory as `AIWG_ARTIFACT_ROOT`. Never write these payloads to a literal project-local `.aiwg/` when `AIWG_ARTIFACTS_PATH` or `.aiwg-location` redirects the corpus.

Context Budget Rules

• Start with `git status --short`, `git diff --name-only`, and

`git diff --cached --name-only`.

• If no `--scope` or `--incremental` is supplied, derive a candidate scope from

changed files and ask before expanding to the full repo.

• Use inventories (`rg --files`, `find`, git path lists) before reading file

bodies.

• Dispatch auditors only for domains implicated by the scoped files.
• Each auditor returns at most 10 findings and 600 words to the parent context.

Detailed evidence goes under `$AIWG_ARTIFACT_ROOT/working/doc-sync/`.

• Do not preload other skills into auditor agents.
• For combined doc-sync, blog, and commit requests, keep blog/release coverage

as one scoped lane and return a handoff summary for `commit-and-push`.

Workflow

1. Parse direction and options. 2. Build the cheap scope inventory from git path lists. 3. Select relevant lanes only: CLI/API docs, provider docs, skill/agent catalogs, README/changelog/release/blog material, or config/schema docs. 4. Run bounded auditors for selected lanes only. 5. Write `$AIWG_ARTIFACT_ROOT/reports/doc-sync-{timestamp}.md` with scope, findings, auto-fixable items, human-review items, and changed files. 6. If not `--dry-run`, apply high-confidence fixes only. 7. Validate modified files with targeted checks. 8. Record `$AIWG_ARTIFACT_ROOT/reports/doc-sync-last-run.json`. 9. Return report path, files changed, validation commands, and remaining review items.

Output Contract

Return:

• report path
• scope audited
• files changed
• validation commands run
• remaining human-review items
• recommended handoff skill, if any