sync-docs

sync-docs

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

Parse Arguments

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const mode = args.find(a => ['report', 'apply'].includes(a)) || 'report';
const scope = args.find(a => a.startsWith('--scope='))?.split('=')[1] || 'recent';
const includeUndocumented = args.includes('--include-undocumented');

Quick Start - Agent Instructions

Pre-check: Ensure Repo-Intel

Before starting analysis, check if the repo-intel map exists:

const fs = require('fs');
const path = require('path');

const cwd = process.cwd();
const stateDir = ['.claude', '.opencode', '.codex']
  .find(d => fs.existsSync(path.join(cwd, d))) || '.claude';
const mapFile = path.join(cwd, stateDir, 'repo-intel.json');

if (!fs.existsSync(mapFile)) {
  const response = await AskUserQuestion({
    questions: [{
      question: 'Generate repo-intel?',
      description: 'No repo-intel map found. Generating one enables doc-drift detection (identifies stale docs by code coupling). Takes ~5 seconds.',
      options: [
        { label: 'Yes, generate it', value: 'yes' },
        { label: 'Skip', value: 'no' }
      ]
    }]
  });

  if (response === 'yes' || response?.['Generate repo-intel?'] === 'yes') {
    try {
      const { binary } = require('@agentsys/lib');
      const output = binary.runAnalyzer(['repo-intel', 'init', cwd]);
      const stateDirPath = path.join(cwd, stateDir);
      if (!fs.existsSync(stateDirPath)) fs.mkdirSync(stateDirPath, { recursive: true });
      fs.writeFileSync(mapFile, output);
    } catch (e) {
      // Binary not available - proceed without
    }
  }
}

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 the repo-intel artifact exists ({stateDir}/repo-intel.json):

• Load it to get accurate export list for undocumented-export detection
• Filter through the analyzer's entry-points query so Cargo [[bin]] targets, main() functions, and framework-loaded configs aren't flagged as missing prose docs (they're execution surfaces, not library APIs)

Step 6: Load analyzer signals in one batch via lib/collectors/analyzer-queries:

• stale-docs — per-doc per-line findings where a referenced symbol no longer exists (rename/deletion-aware). Lifted directly as removed-export issues rather than re-derived from git show HEAD~1 diffs.
• doc-drift — docs with low code coupling, pre-filtered to exclude versioned_docs/, tests/fixtures/, generated/, and append-only CHANGELOG.md (where low coupling is by design, not drift).
• slop-fixes — when a doc mentions a symbol the analyzer has proved is dead (orphan-export) or is a single-call wrapper (passthrough-wrapper), surface as documents-dead-code / documents-wrapper with high/medium severity respectively.

If the agent-analyzer binary or repo-intel.json is missing, the bundle is marked available: false and all analyzer-sourced checks return empty arrays. No silent regex fallback — better to report zero findings than to invent bad ones.

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:

const { ensureRepoMap } = require('../../lib/collectors/docs-patterns');

// Try to get repo-map (will auto-init if ast-grep available)
const repoMapStatus = await ensureRepoMap({
  cwd: process.cwd(),
  askUser: async (opts) => {
    // Use AskUserQuestion tool
    const answer = await AskUserQuestion({
      question: opts.question,
      header: opts.header,
      options: opts.options
    });
    return answer;
  }
});

if (repoMapStatus.installInstructions) {
  // User wants to install ast-grep, show instructions
  console.log(repoMapStatus.installInstructions);
  // Wait for user to confirm installation, then retry
}

// repoMapStatus.available indicates if repo-map can be used
// repoMapStatus.fallbackReason explains why if not available

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.

const fs = require('fs');
const path = require('path');
const glob = require('glob');

// Detect documentation files
const docFiles = [];
const commonDocs = ['README.md', 'CHANGELOG.md', 'CONTRIBUTING.md', 'docs/**/*.md'];

for (const pattern of commonDocs) {
  // Use glob to find matching files
  const matches = glob.sync(pattern, { cwd: process.cwd() });
  docFiles.push(...matches);
}

// Detect project type from package.json, Cargo.toml, go.mod, etc.
let projectType = 'unknown';
if (fs.existsSync('package.json')) projectType = 'javascript';
else if (fs.existsSync('Cargo.toml')) projectType = 'rust';
else if (fs.existsSync('go.mod')) projectType = 'go';
else if (fs.existsSync('pyproject.toml') || fs.existsSync('setup.py')) projectType = 'python';

const context = { docFiles, projectType };

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:

// Use relative path from skill directory to plugin lib
// Path: skills/sync-docs/ -> ../../lib
const { collectors } = require('../../lib');
const docsPatterns = collectors.docsPatterns;

// Get changed files based on scope
let changedFiles;
if (scope === 'all') {
  changedFiles = await exec("git ls-files '*.js' '*.ts' '*.py' '*.go' '*.rs' '*.java'");
} else if (scope === 'before-pr') {
  changedFiles = await exec("git diff --name-only origin/main..HEAD");
} else {
  // recent (default): get the default branch name
  let base = 'main';
  try {
    const { stdout: refOutput } = await exec("git symbolic-ref refs/remotes/origin/HEAD");
    // Parse "refs/remotes/origin/branch-name" to extract "branch-name"
    const rawBase = refOutput.trim().split('/').pop();
    // Sanitize branch name to prevent shell injection (only allow alphanumeric, dash, underscore, dot)
    if (/^[a-zA-Z0-9._-]+$/.test(rawBase)) {
      base = rawBase;
    }
  } catch (e) {
    base = 'main'; // fallback to main if symbolic-ref fails
  }
  changedFiles = await exec(`git diff --name-only origin/${base}..HEAD 2>/dev/null || git diff --name-only HEAD~5..HEAD`);
}

// Find related docs
const relatedDocs = docsPatterns.findRelatedDocs(changedFiles.split('\n').filter(Boolean), {
  cwd: process.cwd()
});

Phase 3: Analyze Documentation Issues

Load the analyzer bundle once and thread it through. All analyzer queries (stale-docs, doc-drift, entry-points, slop-fixes) run in a single batch; downstream analysis reads from the indexed maps rather than shelling out per doc.

const analyzer = analyzerQueries.collect({
  cwd: process.cwd(),
  staleDocsTop: 1500,   // bump for large repos; default 500
  docDriftTop: 50
});

const allIssues = [];

for (const { doc, referencedFile } of relatedDocs) {
  const issues = docsPatterns.analyzeDocIssues(doc, referencedFile, {
    cwd: process.cwd(),
    analyzer       // lifts per-doc entries from analyzer.staleDocsByDoc
  });

  issues.forEach(issue => {
    allIssues.push({
      ...issue,
      doc,
      referencedFile
    });
  });
}

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

const changelogResult = docsPatterns.checkChangelog(changedFiles.split('\n').filter(Boolean), {
  cwd: process.cwd()
});

// changelogResult contains:
// - exists: boolean
// - hasUnreleased: boolean
// - documented: string[]
// - undocumented: string[]
// - suggestion: string | null

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"
    }
  ],
  "docDrift": [
    {
      "path": "README.md",
      "codeCoupling": 0,
      "lastChanged": "2026-01-15T10:00:00Z",
      "changes": 5
    }
  ],
  "documentsDeadCode": [
    {
      "type": "documents-dead-code",
      "severity": "high",
      "doc": "README.md",
      "reference": "legacyHandler",
      "file": "src/legacy.js",
      "certainty": "HIGH",
      "suggestion": "'legacyHandler' is documented but the analyzer proves it is unused - remove the doc mention or inline the code"
    }
  ],
  "documentsWrapper": [
    {
      "type": "documents-wrapper",
      "severity": "medium",
      "doc": "docs/api.md",
      "reference": "getUser",
      "file": "src/api/users.rs",
      "certainty": "MEDIUM",
      "suggestion": "'getUser' is documented but is a single-call passthrough - describe the underlying call or inline the wrapper"
    }
  ],
  "analyzer": {
    "available": true,
    "reason": null,
    "mapFile": ".claude/repo-intel.json",
    "counts": { "staleDocs": 42, "docDriftFiltered": 8, "entryPoints": 12, "orphanExports": 3, "passthroughWrappers": 1 }
  },
  "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