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 <base>...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 <base> 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."
2. Gather context on what changed:

git diff <base>...HEAD --stat
git log <base>..HEAD --oneline
git diff <base>...HEAD --name-only

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

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

4. 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
5. 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 — not "Updated README.md" but "README.md: added /new-feature to features table, updated count from 9 to 10, fixed path to config/."

Never auto-update:

• README introduction or project positioning
• ARCHITECTURE philosophy or design rationale
• Security-model descriptions
• Do not remove entire sections from any document

Step 4: Ask About Risky/Questionable Changes

For each risky update in the Step 2 askUser bucket, use AskUserQuestion with:

• Context: project name, branch, which doc file, what you're reviewing
• The specific documentation decision
• RECOMMENDATION: Choose [X] because [one-line reason]
• Options including C) Skip — leave as-is

Risky updates include:

• Tone rewrites (changing voice, re-pitching features)
• Restructuring (moving sections, reordering content)
• Big additions (>10 lines of new narrative)
• Removing or replacing entire sections
• Changes to security/philosophy/positioning language

Apply each approved change right after the answer.

Step 5: CHANGELOG Voice Polish

CRITICAL — NEVER CLOBBER CHANGELOG ENTRIES.

This step tightens voice. It does NOT rewrite, replace, or regenerate CHANGELOG content.

If CHANGELOG.md does not exist in the repo: skip this step entirely.

If CHANGELOG.md exists but was NOT modified on this branch: skip this step.

Rules when polishing:

1. Read the entire CHANGELOG.md first. Know what is already there.
2. Only adjust wording inside existing entries. Never delete, reorder, or replace entries.
3. Never regenerate a CHANGELOG entry from scratch. It was written from the actual diff and commit history — it is the source of truth. You polish prose, you don't rewrite history.
4. If an entry looks wrong or incomplete, use AskUserQuestion — do NOT silently "fix" it.
5. Use the Edit tool with exact old_string matches — never Write over CHANGELOG.md.

If CHANGELOG was modified on this branch, review the entry for voice:

• Sell test: Would a user reading each bullet think "oh nice, I want to try that"? If not, rewrite the wording (not the content).
• Lead with what the user can now do — not implementation details.
• "You can now..." not "Refactored the..."
• Flag and rewrite any entry that reads like a commit message.
• Internal/contributor changes belong in a separate "### For contributors" subsection.
• Auto-fix minor voice adjustments. Use AskUserQuestion if a rewrite would change meaning.

Step 6: Cross-Doc Consistency & Discoverability Check

Once files are audited individually, do a cross-doc consistency pass:

1. Does the README's feature/capability list match what CLAUDE.md describes?
2. Does ARCHITECTURE's component list match CONTRIBUTING's project-structure description?
3. Do dev-setup instructions agree across all docs?
4. Does CHANGELOG's latest version match the VERSION file (if both exist)?
5. Discoverability: Is every documentation file reachable from README.md or CLAUDE.md? If docs/X.md exists but neither README nor CLAUDE.md links to it, flag it. Every doc should be reachable from one of the two entry-point files.
6. Flag any contradictions between documents. Auto-fix clear factual mismatches (e.g., a version mismatch). Use AskUserQuestion for narrative contradictions.

Step 7: TODOS.md Cleanup

If TODOS.md does not exist at the repo root (or wherever the project keeps it), skip this step.

1. Completed items not yet marked: Cross-reference the diff against open TODO items. If a TODO is clearly completed by this branch, move it to the Completed section with **Completed:** vX.Y.Z (YYYY-MM-DD) (or the project's completion format). Stay conservative — only mark items with clear evidence in the diff.
2. Items needing description updates: If a TODO references files or components that changed significantly, its description may be stale. Use AskUserQuestion to confirm whether the TODO should be updated, completed, or left as-is.
3. New deferred work: Scan the diff for TODO, FIXME, HACK, and XXX comments. For each one that represents meaningful deferred work (not a trivial inline note), use AskUserQuestion to ask whether it should be captured in TODOS.md.

Step 8: VERSION Bump Question

CRITICAL — NEVER BUMP VERSION WITHOUT ASKING.

1. If VERSION does not exist in the repo: skip silently.
2. Check whether VERSION was already modified on this branch:

git diff <base>...HEAD -- VERSION

3. If VERSION was NOT bumped: Use AskUserQuestion. Read the diff semantically to form a recommendation:

   • PATCH (X.Y.Z+1) — bug fixes, doc updates, small tweaks
   • MINOR (X.Y+1.0) — new features, backward-compatible additions
   • MAJOR (X+1.0.0) — breaking changes, removed APIs, incompatible behavior

   Options:

   • A) Bump PATCH (X.Y.Z+1) — small changes
   • B) Bump MINOR (X.Y+1.0) — new features
   • C) Bump MAJOR (X+1.0.0) — breaking changes
   • D) Skip — no version bump needed

   Include RECOMMENDATION: Choose [X] because [semver analysis based on diff].

4. If VERSION was already bumped: Do NOT skip silently. Check whether the bump still covers the full scope of changes:

   a. Read the CHANGELOG entry for the current VERSION. What features does it describe? b. Read the full diff (git diff <base>...HEAD --stat and --name-only). Are there significant changes (new features, major refactors) that the CHANGELOG entry for the current version does NOT mention? c. If the CHANGELOG entry covers everything: Skip — output "VERSION: Already bumped to vX.Y.Z, covers all changes." d. If significant changes are uncovered: Use AskUserQuestion explaining what the current version covers vs what's new:

   • A) Bump to next patch (X.Y.Z+1) — give the new changes their own version
   • B) Keep current version — fold the new changes into the existing CHANGELOG entry
   • C) Skip — leave version as-is, handle later

   Key insight: a VERSION bump set for "feature A" should not silently absorb "feature B" if feature B is substantial enough to deserve its own version entry.

Step 9: Commit & Output

Empty check first: Run git status --porcelain (never -uall). If no documentation files were modified by any previous step, output "All documentation is up to date." and exit without committing.

Commit:

1. Stage modified documentation files by name (never git add -A or git add .).
2. Create a single commit — if the user wants the updates committed at all; when that's unclear, ask whether to commit now or leave the edits staged for review:

git commit -m "$(cat <<'EOF'
docs: update project documentation

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
EOF
)"

Match the project's own commit-message and trailer convention (check recent git log for the prevailing subject style and whether commits carry a Co-Authored-By: trailer at all) rather than assuming the one above. If a VERSION was bumped in Step 8, include the version in the commit subject: docs: update project documentation for vX.Y.Z.

Final output — doc health summary:

Output a scannable summary showing every documentation file's status:

Documentation health:
  README.md       [status] ([details])
  CLAUDE.md       [status] ([details])
  ARCHITECTURE.md [status] ([details])
  CONTRIBUTING.md [status] ([details])
  CHANGELOG.md    [status] ([details])
  TODOS.md        [status] ([details])
  VERSION         [status] ([details])

Status values:

• Updated — with a description of what changed
• Current — no changes needed
• Voice polished — wording adjusted
• Not bumped — user chose to skip
• Already bumped — version was set earlier
• Skipped — file does not exist or was out of scope

Next Steps — Review Chaining

After updating documentation, this skill usually closes out the pipeline. If the user hasn't shipped yet, hand back to /ship to merge and create/update the PR. If the audit surfaced structural concerns that go beyond wording — a missing module the docs imply should exist, a contradiction that points at a code defect — recommend the user route those to /plan-review rather than patching prose to match a possibly-wrong implementation.

Important Rules

1. Read before editing. Always read a file's full content before modifying it.
2. Never clobber content. Polish and correct, never replace wholesale. Especially CHANGELOG — never delete, reorder, or regenerate entries.
3. Never bump VERSION silently. Always ask. Even when it's already bumped, check whether it covers the full scope of changes.
4. Be explicit about what changed. Every edit gets a one-line summary of what specifically changed.
5. Voice: friendly, user-forward — unless the project has its own established doc voice. Default to writing like you're explaining to a smart person who hasn't seen the code, leading with what the user can do; if the repo already has a consistent documentation tone or a writing-style guide, match that instead.
6. Generic heuristics, not project-specific. The audit checks work on any repo.
7. Discoverability matters. Every doc file should be reachable from README or CLAUDE.md.
8. Stage specific files. Never git add -A or git add ..
9. Never create docs the user didn't ask for. Only update existing ones.
10. Fix factual staleness, defer subjective calls. Typos, renames, path updates → auto. Tone, structure, philosophy → ask.
11. Inline by default; fan out only on explicit opt-in. The interactive spine — AskUserQuestion gates, VERSION/TODO/CHANGELOG decisions, and every file Edit/Write — always lives in the main loop. Background Workflow agents can neither talk to the user nor write files, so they only ever do headless audit compute.