---
description: Use when user asks to "update docs", "sync documentation", "fix outdated docs", "update changelog", "docs are stale", or after completing code changes that might affect documentation.
codex-description: 'Use when user asks to "update docs", "sync documentation", "fix outdated docs", "refresh README". Compares documentation to actual code and fixes discrepancies.'
argument-hint: "[report|apply] [--scope=recent|all|before-pr] [path]"
---

# /sync-docs - Documentation Sync

Sync documentation with actual code state. Finds docs that reference changed files, updates CHANGELOG, and flags outdated examples.

## Architecture

```
/sync-docs command (you are here)
    |
    v
sync-docs-agent (sonnet)
    |-- Invoke sync-docs skill
    |-- Return structured results
    |
    v
Command processes results
    |-- If apply mode + fixes: spawn simple-fixer
    |-- Present final results
```

## Constraints

1. **Preserve existing content** - Update references, don't rewrite sections
2. **Minimal changes** - Only fix what's actually outdated
3. **Evidence-based** - Every change linked to a specific code change
4. **Safe defaults** - Report mode by default

## Arguments

Parse from $ARGUMENTS:

- **Mode**: `report` (default) or `apply`
- **Scope**:
  - `--scope=recent` (default): Files changed since last commit to main
  - `--scope=all`: Scan all docs against all code
  - `--scope=before-pr`: Files in current branch (for /next-task integration)
  - `path`: Specific file or directory

## Execution

### Step 1: Parse Arguments

```javascript
const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const mode = args.includes('apply') ? 'apply' : 'report';
const scopeArg = args.find(a => a.startsWith('--scope='));
const scope = scopeArg ? scopeArg.split('=')[1] : 'recent';
const pathArg = args.find(a => !a.startsWith('--') && a !== 'report' && a !== 'apply');
```

### Step 2: Spawn sync-docs-agent

```javascript
const agentOutput = await Task({
  subagent_type: "sync-docs:sync-docs-agent",
  model: "sonnet",
  prompt: `Sync documentation with code state.
Mode: ${mode}
Scope: ${scope}
${pathArg ? `Path: ${pathArg}` : ''}

Execute the sync-docs skill and return structured results.`
});
```

### Step 3: Process Results

Parse the structured JSON from between `=== SYNC_DOCS_RESULT ===` markers:

```javascript
// Helper to extract JSON result from agent output
function parseSyncDocsResult(output) {
  const match = output.match(/=== SYNC_DOCS_RESULT ===[\s\S]*?({[\s\S]*?})[\s\S]*?=== END_RESULT ===/);
  if (!match) {
    throw new Error('No SYNC_DOCS_RESULT found in agent output');
  }
  return JSON.parse(match[1]);
}

const result = parseSyncDocsResult(agentOutput);
// result now contains: { mode, scope, validation, discovery, issues, fixes, changelog, summary }
```

### Step 4: Apply Fixes (if apply mode)

If mode is `apply` and fixes array is non-empty:

```javascript
if (mode === 'apply' && result.fixes.length > 0) {
  await Task({
    subagent_type: "next-task:simple-fixer",
    model: "haiku",
    prompt: `Apply these documentation fixes:
${JSON.stringify(result.fixes, null, 2)}

Use the Edit tool to apply each fix. Commit message: "docs: sync documentation with code changes"`
  });
}
```

### Step 5: Present Results

```markdown
## Documentation Sync ${mode === 'apply' ? 'Applied' : 'Report'}

### Scope
- Mode: ${mode}
- Scope: ${scope}
- Changed files analyzed: ${result.discovery.changedFilesCount}
- Related docs found: ${result.discovery.relatedDocsCount}

### Validation Results

**Count/Version Validation**
${result.validation.counts.status === 'ok' ? '[OK] Counts and versions aligned' : `[WARN] ${result.validation.counts.summary.issueCount} issues found`}

**Cross-Platform Validation**
${result.validation.crossPlatform.status === 'ok' ? '[OK] Cross-platform docs valid' : `[WARN] ${result.validation.crossPlatform.summary.issueCount} issues found`}

### Documentation Issues

${result.issues.length === 0 ? '[OK] No documentation issues detected' :
  result.issues.map(i => `- **${i.doc}:${i.line || '?'}** (${i.severity}): ${i.suggestion || i.type}`).join('\n')}

### CHANGELOG Status

${result.changelog.status === 'ok' ? '[OK] All changes documented' :
  `[WARN] ${result.changelog.undocumented.length} commits may need entries:\n${result.changelog.undocumented.map(c => `  - ${c}`).join('\n')}`}

${mode === 'apply' && result.fixes.length > 0 ? `
### Fixes Applied

${result.fixes.map(f => `- **${f.file}**: ${f.type}`).join('\n')}
` : ''}

${mode === 'report' && result.fixes.length > 0 ? `
## Do Next

- [ ] Run \`/sync-docs apply\` to fix ${result.fixes.length} auto-fixable issues
- [ ] Review flagged items manually
` : ''}
```

## Examples

```bash
# Check what docs might need updates (safe, no changes)
/sync-docs

# Check docs related to specific path
/sync-docs report src/auth/

# Apply safe fixes
/sync-docs apply

# Full codebase scan
/sync-docs report --scope=all

# For PR preparation
/sync-docs apply --scope=before-pr
```

## Integration

This command is also used by `/next-task` Phase 11:

```javascript
// Phase 11 invocation
await Task({
  subagent_type: "sync-docs:sync-docs-agent",
  prompt: "Sync docs for PR. Mode: apply, Scope: before-pr"
});
```

## Error Handling

- **No git**: Exit with "Git required for change detection"
- **No changed files**: "No changes detected. Use --scope=all to scan entire codebase"
- **No docs found**: "No documentation files found"
- **Agent failure**: Report error, suggest manual review