Doc Sync

Doc Sync — Post-Ship Documentation Update

You operate after the code lands (committed, with a PR open or imminent) but before merge. The mission: make every documentation file in the project accurate, current, and written in a warm, user-facing voice.

Posture: Largely hands-off automation. Apply obvious factual fixes yourself. Pause only for the calls that are genuinely risky or subjective. You refine and correct — you never clobber, wholesale-rewrite, or regenerate content from nothing.

Pause only for:

• Risky or debatable doc edits (narrative, philosophy, security, removals, large rewrites)
• The VERSION bump decision (when not already bumped)
• New TODO items worth capturing
• Cross-doc contradictions that are narrative rather than factual

Never pause for:

• Factual corrections the diff makes obvious
• Adding rows to tables or items to lists
• Fixing paths, counts, line-number references, version numbers
• Repairing stale cross-references
• Light CHANGELOG voice tightening (minor wording)
• Marking TODOs done
• Cross-doc factual mismatches (e.g., a version number that disagrees)

Never do:

• Overwrite, replace, or regenerate CHANGELOG entries — tighten wording only, keep all content
• Bump VERSION without asking — always route version changes through AskUserQuestion
• Use the Write tool on CHANGELOG.md — always Edit with exact old_string matches
• Delete whole sections from any document
• Create new documentation files unless the user explicitly requests them

---

Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. Auto-detect what you safely can from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. Ask, don't assume, for the rest. Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise AskUserQuestion (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):

• Base branch to diff against — auto-detected in Step 0 from the PR/MR target or repo default; only confirm when detection is genuinely ambiguous (no clear default branch, or multiple plausible candidates) rather than silently falling back to main.
• Documentation voice / house style — whether to match the project's own established documentation tone, or apply the default warm, user-forward voice; check for a STYLEGUIDE / writing-conventions doc to follow before rewording anything.
• Whether to commit, and the commit/trailer convention — whether to commit the doc updates at all (vs leave them staged for the user to review), and what commit-message format and co-author trailer the project uses, rather than assuming a fixed one.
• Versioning & changelog conventions — whether the project versions via a VERSION file + CHANGELOG and what semver / completed-item format it follows, before proposing any bump or marking TODOs done.

---

How this runs (interactive spine stays in the main loop)

Whatever you choose, the interactive spine always lives in the main conversation — that is what keeps the skill usable. The VERSION bump question (Step 8), the risky-change ceremonies (Step 4), the CHANGELOG voice confirmations (Step 5), the TODO capture prompts (Step 7), and the cross-doc narrative-contradiction calls (Step 6) all need a direct answer via AskUserQuestion, so they never leave the main loop.

The only part that is pure, non-interactive compute is the per-file documentation audit (Step 2) — each doc is an independent read-and-classify pass, so sequential execution is just latency. By default, do those passes inline, one file at a time. Before spawning any subagent or Workflow, stop and ask the user, for example:

> This is large ([K doc files against a sizable diff]). I can audit them inline here (cheaper, slower) or fan out [M] parallel agents (faster, more tokens). Which do you want?

Spawn subagents/workflows only after an explicit yes. If the user declines or doesn't answer, do the whole job inline. When the user does opt in, run the Step 2 passes as a dynamic Workflow instead, then come back to the main loop to apply edits and decide.

Hard rule whenever you do launch a Workflow: Workflow agent() calls run in the background — they cannot call AskUserQuestion, cannot talk to the user, and cannot write files. So every gate, ceremony, VERSION question, TODO capture, narrative-contradiction call, and every file Edit/Write (README, CLAUDE.md, ARCHITECTURE, CHANGELOG, TODOS.md, VERSION) stays in the main loop. The workflow only does headless compute (read each doc, cross-reference the diff, classify, propose) and returns structured results; you apply the edits and make the calls. Always set model: 'opus' on agent() calls (never let a lighter tier leak through), and pass data in via args — Workflow scripts have no Date.now/Math.random/filesystem access, so timestamps and file writes happen back in the main loop. Fanning out only removes the waiting: the UX is identical, whether the audit runs inline or in parallel.

Arguments

Check $ARGUMENTS:

• A PR number / commit ref / feature name → use it to scope the diff under review (treat it as ...HEAD context, or the named PR/MR).
• A file path → restrict the audit to that documentation file (still run the full cross-doc and VERSION steps).
• A mode hint — "voice only" / "changelog only" → focus on Step 5; "version" → jump to Step 8; "audit only" / "report" → run Steps 1-2 and present the doc-health summary without applying edits.
• Empty → audit the current branch against its base branch and run all steps.

---

Step 0: Detect platform and base branch

Detect the git hosting platform from the remote URL:

git remote get-url origin 2>/dev/null

• URL contains "github.com" → GitHub
• URL contains "gitlab" → GitLab
• Otherwise, check CLI availability:
• gh auth status 2>/dev/null succeeds → GitHub (covers GitHub Enterprise)
• glab auth status 2>/dev/null succeeds → GitLab (covers self-hosted)
• Neither → unknown (use git-native commands only)

Determine the base branch (PR/MR target, or repo default):

If GitHub:

1. gh pr view --json baseRefName -q .baseRefName — if it succeeds, use it
2. gh repo view --json defaultBranchRef -q .defaultBranchRef.name — if it succeeds, use it

If GitLab:

1. glab mr view -F json 2>/dev/null → extract target_branch — if it succeeds, use it
2. glab repo view -F json 2>/dev/null → extract default_branch — if it succeeds, use it

Git-native fallback (unknown platform or CLI fails):

1. git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'
2. git rev-parse --verify origin/main 2>/dev/null → use main
3. git rev-parse --verify origin/master 2>/dev/null → use master
4. Fall back to main — but if no default branch could be confidently detected (no origin/HEAD, and neither main nor master present), confirm the base branch with the user before proceeding rather than silently assuming main.

Print the detected base branch. Substitute it for `` in every subsequent command.

---

Step 1: Pre-flight & Diff Analysis

1. Check the current branch. If you're on the base branch, abort: "You're on the base branch. Run from a feature branch."

1. Gather context on what changed:

git diff ...HEAD --stat
git log ..HEAD --oneline
git diff ...HEAD --name-only

1. Discover every documentation file in the repo (root + docs/):

find . -maxdepth 3 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" | sort

1. Sort the changes into documentation-relevant buckets:

• New features — new files, new components, new API endpoints, new commands
• Changed behavior — modified services, updated APIs, config changes
• Removed functionality — deleted files, dropped features
• Infrastructure — build system, dependencies, CI, test infrastructure

1. Output: "Analyzing N files changed across M commits. Found K documentation files to review."

---

Step 2: Per-File Documentation Audit

Read each documentation file and cross-reference it against the diff. Classify each file as stale, accurate, or partially-stale.

These per-file checks are independent analytical passes — one per documentation file. By default, run them inline in this context, one file at a time. If the user opted into parallelism (see How this runs), fan the audit out as a Workflow (one agent per file) instead. Either way, you then apply auto-updates and walk the user through risky items in the main loop, exactly as Steps 3-4 describe. Fanning out only removes the waiting; it never edits files and never asks the user anything (background agents can do neither).

The per-file audit rubric:

README.md:

• Does it describe every feature and capability visible in the diff?
• Are install/setup instructions consistent with the changes?
• Are examples, demos, and usage descriptions still valid?
• Are listed scripts (in package.json or equivalent) described accurately?
• Are troubleshooting steps still correct?

CLAUDE.md / project instructions:

• Does the project-structure section match the real file tree?
• Are the listed commands and scripts accurate?
• Do conventions match current code patterns?
• Are architecture descriptions still correct?
• Do build/test instructions match what's in package.json (or equivalent)?

ARCHITECTURE.md (if present):

• Do ASCII diagrams and component descriptions match the current code?
• Are design decisions and "why" explanations still accurate?
• Stay conservative — only change what the diff clearly contradicts. Architecture docs describe things that rarely move.

CONTRIBUTING.md / DEVELOPMENT_STANDARDS.md — new-contributor smoke test:

• Walk the setup instructions as if you were a brand-new contributor.
• Are the listed commands accurate? Would each step actually succeed?
• Do test-tier descriptions match the current test infrastructure?
• Are workflow descriptions current?
• Flag anything that would fail or confuse a first-timer.

**docs/.md and any other .md files:*

• Read the file, infer its purpose and audience.
• Cross-reference against the diff for contradictions.

For each file, split needed updates into two buckets:

• Auto-update — factual corrections the diff clearly warrants: typos, renames, line-number references, moved paths, counts, lists, project-structure trees.
• Ask user — tone rewrites, narrative changes, section removals, security-model changes, restructuring, big additions (more than ~10 lines in one section), ambiguous relevance, entirely new sections.

The audit fan-out (only when the user opted into parallelism)

export const meta = {
  name: 'doc-sync-doc-audit',
  description: 'Parallel per-file documentation audit — one agent per doc file, cross-referenced against the diff',
  phases: [{ title: 'Audit' }],
}
const AUDIT_SCHEMA = {
  type: 'object',
  properties: {
    file: { type: 'string' },
    classification: { type: 'string' },                                // stale | accurate | partially-stale
    autoUpdates: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          summary: { type: 'string' },                                 // one-line "what specifically changed"
          oldString: { type: 'string' },                               // exact text to replace (for Edit)
          newString: { type: 'string' },                               // replacement text
        },
        required: ['summary', 'oldString', 'newString'],
      },
    },
    askUser: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          decision: { type: 'string' },                                // the risky/subjective decision to surface
          recommendation: { type: 'string' },                          // RECOMMENDATION: Choose [X] because [reason]
          reason: { type: 'string' },
        },
        required: ['decision', 'recommendation'],
      },
    },
  },
  required: ['file', 'classification', 'autoUpdates', 'askUser'],
}
const audits = await parallel(args.files.map(f => () =>
  agent(
    `You are auditing ONE documentation file for post-ship accuracy. Do NOT edit any file and do NOT ` +
    `ask the user anything — return findings only; the main loop applies edits and walks risky items ` +
    `interactively afterward.\n\n` +
    `DOC FILE TO AUDIT: ${f.path}\n` +
    `FILE PURPOSE/RUBRIC: ${f.rubric}\n\n` +
    `DIFF CONTEXT (what shipped on this branch):\n` +
    `  changed files: ${args.changedFiles}\n` +
    `  commit log: ${args.commitLog}\n` +
    `  diff stat: ${args.diffStat}\n` +
    `  change categories: ${args.categories}\n\n` +
    `Read ${f.path} in full, cross-reference it against the diff, and classify it as ` +
    `"stale", "accurate", or "partially-stale". Then split needed updates into TWO buckets:\n` +
    `  - autoUpdates: clear factual low-risk corrections warranted by the diff (typos, renames, ` +
    `line-number references, moved paths, counts, list items, project-structure trees, stale ` +
    `cross-references). For each, give a one-line "what specifically changed" summary plus an EXACT ` +
    `oldString (verbatim from the file, uniquely matching) and its newString, ready for the Edit tool.\n` +
    `  - askUser: risky/subjective changes (tone rewrites, narrative changes, section removals, ` +
    `security/philosophy/positioning language, restructuring, additions >10 lines, ambiguous relevance, ` +
    `entirely new sections). For each, state the decision and a "RECOMMENDATION: Choose [X] because [reason]".\n\n` +
    `NEVER propose an autoUpdate for: the README introduction or project positioning, ARCHITECTURE ` +
    `philosophy or design rationale, security-model descriptions, or removal of any entire section — ` +
    `those go in askUser. Never propose regenerating content wholesale; polish and correct only.`,
    { label: `audit:${f.label}`, phase: 'Audit', model: 'opus', schema: AUDIT_SCHEMA }
  )
))
return audits.filter(Boolean)

Pass args: { files: [{ path, rubric, label }, ...], changedFiles, commitLog, diffStat, categories } where each rubric is the matching per-file rubric above (verbatim) and the diff-context fields come from Step 1. Exclude CHANGELOG.md, TODOS.md, and VERSION from args.files — those are owned by their dedicated steps (5, 7, 8). When the workflow returns, carry each file's autoUpdates into Step 3 and each file's askUser into Step 4.

If you ran the audit inline instead, you already have the same per-file autoUpdates and askUser buckets — proceed straight to Step 3. If a fan-out workflow fails or times out, fall back to auditing the files sequentially in the main loop using the same rubric.

---

Step 3: Apply Auto-Updates

Make every clear, factual, low-risk update directly with the Edit tool, drawing the proposed autoUpdates from the Step 2 audit. Read each file before editing it and confirm the oldString still matches exactly. Examples:

• Typos and grammar fixes
• Renames (variable, function, file, command)
• Line-number references that drifted
• File paths that moved
• Counts and list items that changed
• Project-structure trees that no longer match the filesystem
• Stale cross-references between docs

For every file you touch, output a one-line summary of **what specifically changed

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: napnap11
• Source: napnap11/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.