/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

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

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:

// 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:

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

## 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

# 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:

// 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