name: sync-docs description: "Sync documentation with code. Use when user asks to update docs, check docs, fix stale documentation, update changelog, or after code changes." version: 5.0.0 argument-hint: "[report|apply] [--scope=all|recent|before-pr] [--include-undocumented]" allowed-tools: Bash(git:*), Read, Grep, Glob

OpenCode Note: Invoke agents using @agent-name syntax. Available agents: task-discoverer, exploration-agent, planning-agent, implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent Example: @exploration-agent analyze the codebase

sync-docs

Unified skill for syncing documentation with code state. Combines discovery, analysis, and CHANGELOG update into a single workflow.

Parse Arguments

(JavaScript reference - not executable in OpenCode)

Quick Start - Agent Instructions

Step 1: Get changed files (use Bash):

# Recent changes (default scope)
git diff --name-only origin/main..HEAD 2>/dev/null || git diff --name-only HEAD~5..HEAD

# Or for all files
git ls-files '*.md'

Step 2: Find docs that reference changed files (use Grep):

• •Search for filenames, function names, class names in *.md files
• •Check README.md, CHANGELOG.md, docs/*.md

Step 3: Analyze each doc for issues:

• •Version mismatches (compare doc versions to package.json)
• •Removed exports (symbols in docs but not in code)
• •Outdated code examples
• •Import path changes

Step 4: Check CHANGELOG:

• •Look for ## [Unreleased] section
• •Compare recent commit messages to CHANGELOG entries

Step 5: If repo-map exists ({stateDir}/repo-map.json - platform state directory):

• •Load it to get accurate export list
• •Find exports not mentioned in any documentation
• •Report as undocumented-export issues

Input

Arguments: [report|apply] [--scope=all|recent|before-pr] [--include-undocumented]

• •Mode: report (default) or apply
• •Scope:
  • •recent (default): Files changed since last commit to main
  • •all: Scan all docs against all code
  • •before-pr: Files in current branch, optimized for /next-task Phase 11
• •--include-undocumented: Find exports not mentioned in any docs (uses repo-map)

Architecture

This skill orchestrates all documentation sync operations:

sync-docs skill
    |-- Phase 1: Detect project context
    |-- Phase 2: Find related docs (lib/collectors/docs-patterns)
    |-- Phase 3: Analyze issues
    |-- Phase 3.5: Find undocumented exports (repo-map integration)
    |-- Phase 4: Check CHANGELOG
    |-- Phase 5: Return structured results

The skill MUST NOT apply fixes directly. It returns structured data for the orchestrator to decide what to do.

Implementation Details (Reference)

The sections below describe the internal JavaScript implementation for reference only. Agents should follow the Quick Start instructions above using Bash, Read, and Grep tools.

Phase 1: Detect Project Context

Detect project type and find documentation files.

Phase 1.5: Ensure Repo-Map

Before analyzing issues, ensure repo-map is available for accurate symbol detection:

• •Use AskUserQuestion tool for user input

User Interaction (only if ast-grep not installed):

Use AskUserQuestion:

• •Header: "ast-grep Required"
• •Question: "ast-grep not found. Install for better doc sync accuracy?"
• •Options:
  • •"Yes, show instructions" - Display platform-specific install instructions
  • •"No, use regex fallback" - Continue with less accurate regex-based detection

If user declines or repo-map unavailable, the system falls back to regex-based export detection automatically.

(JavaScript reference - not executable in OpenCode)

This phase gathers context about the project without requiring external scripts.

Phase 2: Find Related Documentation

Use lib/collectors/docs-patterns to find docs related to changed files:

(JavaScript reference - not executable in OpenCode)

Phase 3: Analyze Documentation Issues

For each related doc, check for issues:

(JavaScript reference - not executable in OpenCode)

Issue types detected:

• •outdated-version: Version string doesn't match current
• •removed-export: References removed symbol
• •code-example: Code example may be outdated
• •import-path: Import path changed
• •undocumented-export: Export exists in code but not mentioned in any docs (requires repo-map)

Phase 4: Check CHANGELOG

(JavaScript reference - not executable in OpenCode)

Phase 5: Return Structured Results

Combine all results into a single output:

{
  "mode": "report|apply",
  "scope": "recent|all|before-pr|path",
  "context": {
    "projectType": "javascript|python|rust|go|unknown",
    "docFiles": ["README.md", "CHANGELOG.md"]
  },
  "repoMap": {
    "available": true,
    "fallbackReason": null,
    "stats": { "files": 142, "symbols": 847 }
  },
  "discovery": {
    "changedFilesCount": 5,
    "relatedDocsCount": 3,
    "relatedDocs": [
      { "doc": "README.md", "referencedFile": "src/api.js", "referenceTypes": ["filename", "import"] }
    ]
  },
  "issues": [
    {
      "type": "outdated-version",
      "severity": "low",
      "doc": "README.md",
      "line": 15,
      "current": "1.0.0",
      "expected": "1.1.0",
      "autoFix": true,
      "suggestion": "Update version from 1.0.0 to 1.1.0"
    }
  ],
  "undocumentedExports": [
    {
      "type": "undocumented-export",
      "severity": "low",
      "file": "src/utils.js",
      "name": "formatDate",
      "line": 25,
      "certainty": "MEDIUM",
      "suggestion": "Export 'formatDate' in src/utils.js is not mentioned in any documentation"
    }
  ],
  "fixes": [
    {
      "file": "README.md",
      "type": "update-version",
      "line": 15,
      "search": "1.0.0",
      "replace": "1.1.0"
    }
  ],
  "changelog": {
    "exists": true,
    "hasUnreleased": true,
    "undocumented": ["feat: add new feature"],
    "status": "needs-update|ok"
  },
  "summary": {
    "issueCount": 3,
    "fixableCount": 2,
    "bySeverity": { "high": 0, "medium": 1, "low": 2 }
  }
}

Output Format

Output the result as JSON between markers:

=== SYNC_DOCS_RESULT ===
{JSON output}
=== END_RESULT ===

Usage by Agents

sync-docs-agent (standalone /sync-docs)

Skill: sync-docs
Args: report --scope=recent

/next-task Phase 11

Skill: sync-docs
Args: apply --scope=before-pr

The orchestrator receives the structured result and spawns simple-fixer if fixes are needed.

Constraints

1. •Report mode by default - Never modify files unless explicitly in apply mode
2. •Structured output - Always return JSON between markers
3. •No direct fixes - Return fix instructions, let orchestrator decide
4. •Preserve formatting - Fix suggestions should preserve existing style
5. •Safe changes only - Only auto-fixable issues get fix entries

Error Handling

• •No git: Exit with error "Git required for change detection"
• •No docs found: Report empty docFiles, suggest creating README.md
• •No changed files: Report scope as "empty", suggest using --scope=all