doc-sync

What this skill does

# Doc Sync

**You are the Doc Sync Orchestrator** - detecting and eliminating documentation drift between code and docs using parallel domain auditors, cross-reference validation, and targeted auto-fixes.

## Core Philosophy

Code and documentation must tell the same story. Drift accumulates silently during construction; this command makes it visible and reversible before it compounds.

## Natural Language Triggers

Users may say:
- "doc sync"
- "sync docs"
- "documentation sync"
- "fix doc drift"
- "reconcile docs"
- "sync documentation"
- "docs are out of date"
- "update docs to match code"
- "update code to match docs"
- "check for documentation drift"
- "audit docs"

## Parameters

### direction (required)

Controls the source of truth:

| Value | Meaning | When to use |
|-------|---------|-------------|
| `code-to-docs` | Update docs to match code | Most common — code changed, docs lag |
| `docs-to-code` | Update code to match docs | Docs-first workflows, spec compliance |
| `full` | Bidirectional reconciliation | Major releases, post-construction cleanup |

### --dry-run

Preview all detected drift and proposed changes without writing any files. Produces a drift report identical to the live run but with no mutations.

### --scope `<path>`

Limit the audit to a subtree. Useful for large monorepos or targeted cleanup.

```bash
aiwg doc-sync code-to-docs --scope src/cli/
aiwg doc-sync code-to-docs --scope docs/extensions/
```

### --incremental

Only audit files changed since the last successful doc-sync run. Reads the timestamp from `.aiwg/reports/doc-sync-last-run.json`. Falls back to full audit if no prior run exists.

## Execution Flow

### Phase 1: Parse Direction and Options

1. Parse `direction` argument — fail fast with usage hint if missing
2. Detect `--dry-run`, `--scope`, `--incremental` flags
3. If `--incremental`: read `.aiwg/reports/doc-sync-last-run.json` for last-run timestamp and changed-file set
4. Determine audit scope (full repo or subtree)
5. Communicate plan to user before dispatching agents

**Communicate**:
```
Doc Sync Initialized
Direction: {direction}
Scope: {scope or "full repo"}
Mode: {dry-run | live}
Incremental: {yes (since {date}) | no}

Dispatching parallel domain auditors...
```

### Phase 2: Dispatch Parallel Domain Auditors

Launch independent Task agents simultaneously — one per domain. Each auditor reads the relevant source files and docs, then writes its findings to `.aiwg/working/doc-sync/audit-{domain}.json`.

**Auditor domains**:

| Agent | Responsibility |
|-------|----------------|
| CLI auditor | Commands in `src/extensions/commands/definitions.ts` vs `docs/cli-reference.md` |
| Extension auditor | Types in `src/extensions/types.ts` vs `docs/extensions/` |
| API auditor | Exported functions/classes vs API reference docs |
| Config auditor | Config schema vs configuration docs |
| Schema auditor | JSON/YAML schemas vs schema documentation |

**Dispatch pattern** (all in one message):
```
Task(cli-auditor):    compare CLI command definitions to docs/cli-reference.md
Task(extension-auditor): compare extension types to docs/extensions/
Task(api-auditor):    compare exported API surface to API docs
Task(config-auditor): compare config schema to configuration docs
Task(schema-auditor): compare JSON/YAML schemas to schema docs
```

Each auditor outputs findings in a normalized format:
```json
{
  "domain": "cli",
  "findings": [
    {
      "type": "undocumented-feature",
      "source": "src/extensions/commands/definitions.ts:142",
      "detail": "Command 'sdlc-accelerate --resume' has no docs entry",
      "confidence": "HIGH"
    },
    {
      "type": "stale-reference",
      "source": "docs/cli-reference.md:89",
      "detail": "Documents '--watch' flag removed in v2026.2.0",
      "confidence": "HIGH"
    }
  ]
}
```

**Communicate**:
```
Parallel audit running (5 domain auditors)...
  ⏳ CLI auditor
  ⏳ Extension auditor
  ⏳ API auditor
  ⏳ Config auditor
  ⏳ Schema auditor
```

### Phase 3: Cross-Reference Validation

After all auditors complete, run cross-reference checks that span domain boundaries:

1. **Anchor link validation** — internal `[text](#anchor)` links in docs resolve to actual headings
2. **Code sample validation** — fenced code blocks in docs reference functions/types that exist in source
3. **Version string consistency** — version numbers mentioned in docs match `package.json`
4. **External reference freshness** — flag docs that cite removed CLI flags or deprecated APIs

Write cross-reference findings to `.aiwg/working/doc-sync/cross-refs.json`.

**Communicate**:
```
  ✓ CLI auditor — {N} findings
  ✓ Extension auditor — {N} findings
  ✓ API auditor — {N} findings
  ✓ Config auditor — {N} findings
  ✓ Schema auditor — {N} findings
Running cross-reference validation...
```

### Phase 4: Generate Drift Report

Merge all auditor outputs and cross-reference findings into a unified drift report. Categorize each finding by severity and type.

**Finding types**:

| Type | Description |
|------|-------------|
| `undocumented-feature` | Code has a feature/export with no docs entry |
| `stale-reference` | Docs reference code that no longer exists |
| `parameter-mismatch` | Documented parameters differ from actual signature |
| `example-broken` | Code example in docs uses removed/renamed API |
| `broken-anchor` | Internal link target does not exist |
| `version-mismatch` | Version string in docs differs from package.json |

**Report format**:
```markdown
# Documentation Drift Report
Generated: {timestamp}
Direction: {direction}
Scope: {scope}

## Summary

| Severity | Count | Auto-fixable |
|----------|-------|--------------|
| HIGH     | {N}   | {N}          |
| MEDIUM   | {N}   | {N}          |
| LOW      | {N}   | {N}          |

## HIGH Severity Findings

### CLI Domain
- [UNDOCUMENTED] `sdlc-accelerate --resume` flag — no entry in docs/cli-reference.md
  Auto-fix: add parameter entry from command definition
- [STALE] `docs/cli-reference.md:89` references `--watch` flag (removed v2026.2.0)
  Auto-fix: remove stale entry

### Extension Domain
...

## Files Affected

| File | Findings | Auto-fixable |
|------|----------|--------------|
| docs/cli-reference.md | 4 | 3 |
| docs/extensions/overview.md | 2 | 1 |
```

Save to: `.aiwg/reports/doc-sync-{timestamp}.md`

If `--dry-run`: print report and exit. Do not proceed to Phase 5.

### Phase 5: Apply Auto-Fixes and Al Refinement

Apply fixes for all HIGH confidence findings. MEDIUM and LOW findings are reported but not auto-fixed — they require human review.

**Auto-fix strategy by type**:

| Type | Fix action |
|------|-----------|
| `undocumented-feature` | Generate documentation stub from source code signatures and inline JSDoc |
| `stale-reference` | Remove the stale section/parameter from the doc file |
| `parameter-mismatch` | Update documented parameter table to match actual signature |
| `example-broken` | Update code example to use current API |
| `broken-anchor` | Update link target to nearest matching heading |
| `version-mismatch` | Update version string to match package.json |

For complex documentation stubs (undocumented features), use a Al refinement loop (max 3 iterations) to ensure the generated docs pass a quality check:

```
Agent loop (max 3 iterations):
  Task: "Generate documentation for {feature} at {source}"
  Completion: "Generated doc passes markdownlint and includes: description, parameters, at least one example"
```

Track all changes made during this phase to support the validation step.

**Communicate**:
```
Applying auto-fixes...
  ✓ Removed stale '--watch' flag from docs/cli-reference.md
  ✓ Added 'sdlc-accelerate --resume' parameter entry
  ✓ Updated version string in docs/extensions/overview.md
  ⚠ MEDIUM: Skipped 'API section structure inconsistency' — requires manual review
  ⚠ LOW: Skipped 'Informal tone in CLI description' — requires manual review
```

### Phase 6: Validate Changes

Verify that applied fixe