SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillssync-release-docs

sync-release-docs

Writing & research

View repository

Updated 10-16 01:35

About this skill

Skill: Sync docs after release

Purpose

After a code release or PR merge, ensure project documentation (README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md, CHANGELOG, TODOS) is consistent with delivered changes, maintaining discoverability and cross-document consistency.

Core Objective

Primary objective: Produce documentation updates consistent with release changes; factual corrections are done automatically, subjective or risky changes require user confirmation.

Success criteria(all requirements must be met):

  1. ✅ Base branch detected: Infer base branch from CLAUDE.md,.ai-cortex/config.yaml or gh ; see docs/guides/project-config.md
  2. ✅ Diff and per-file audit：git diff、git log executed; README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md checked against diff; classified as Auto-update or Ask user
  3. ✅ CHANGELOG polish only: Do not rewrite, delete, or replace existing entries; VERSION changes must be confirmed via AskUserQuestion
  4. ✅ Cross-document consistency: Version numbers, capability lists, discoverability links verified
  5. ✅ Changes committed: If there are modifications, a single commit and output doc health summary

Acceptance test: Can a new contributor correctly complete the first contribution process using only README/CONTRIBUTING?

Scope Boundaries

This skill is responsible for：

  • Post-release factual documentation updates (paths, counts, capability lists, examples)
  • CHANGELOG wording polish (not rewrite)
  • TODOS.md completed item marking, cross-references
  • Cross-document consistency checks and discoverability (README/CLAUDE links)
  • Documentation health status summary output

This skill is not responsible for：

  • Establishing or updating artifact specifications (use discover-docs-norms）
  • Documentation health assessment and gap planning (use assess-docs）
  • Bootstrapping documentation structure from scratch (use bootstrap-docs）
  • Committing code changes (this skill only updates documentation and commits)

Handoff point: After documentation sync is complete, hand off to the subsequent release process or the next task. If specification violations are found, recommend running assess-docs。

Use Cases

  • User requests post-release documentation updates, documentation sync, or post-ship docs
  • PR has been created or merged, and documentation needs to be ensured consistent with changes
  • CHANGELOG wording needs to be polished into a user-facing tone
  • Cross-document version numbers or capability lists are inconsistent and need fixing

Behavior

Prerequisite: Detect base branch

  1. If CLAUDE.md or .ai-cortex/config.yamlexists, read it first base_branch
  2. Otherwise:gh pr view --json baseRefName -q .baseRefName(if there is a PR); if that fails, gh repo view --json defaultBranchRef -q .defaultBranchRef.name; if both fail, main
  3. Output the detected base branch

Step 1: Pre-flight and Diff Analysis

  1. If currently on the base branch, abort: "Please run on a feature branch."
  2. Execute:git diff <base>...HEAD --stat、git log <base>..HEAD --oneline、git diff <base>...HEAD --name-only
  3. Discover documentation files:find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" | sort
  4. Classify changes: new features, behavior changes, removals, infrastructure
  5. Output: "Analyzed N file changes, M commits, found K documents pending review."

Step 2: Per-file Documentation Audit

For README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md, and other .md files in the project:

  • README: Do the capabilities/features list match the diff? Are the installation/examples still correct?
  • ARCHITECTURE: Do the component and design descriptions match the code? Only update content explicitly contradicted by the diff
  • CONTRIBUTING: Can a new contributor succeed by following the steps? Are the commands valid?
  • CLAUDE.md: Are the project structure and commands accurate?

Classify each update as Auto-update(factual, explicit in the diff) or Ask user(narrative, large-scale rewrite, security model, ambiguous).

Step 3: Apply Auto-update

For explicit factual updates, modify directly using the Edit tool. Output a one-line summary for each modification (specifically what was changed).

Prohibit auto-update: README positioning, ARCHITECTURE design rationale, security model, deleting entire sections.

Step 4: Risk Change Confirmation

For items marked as Ask user in Step 2, use AskUserQuestion, with RECOMMENDATION and options (including Skip). Apply immediately after user confirmation.

Step 5: CHANGELOG Wording Polish

Prohibit rewriting or replacing CHANGELOG entries.

  • Only modify wording within existing entries; do not delete, reorder, or replace wholesale
  • Tone: user-facing; emphasize "what can be done" rather than implementation details
  • If there are issues, use AskUserQuestion; do not fix silently

Step 6: Cross-document Consistency and Discoverability

  • Is the README capabilities list consistent with CLAUDE.md?
  • Is the ARCHITECTURE structure consistent with CONTRIBUTING?
  • Is the CHANGELOG version consistent with the VERSION file?
  • Is each document reachable via a link from README or CLAUDE?

Step 7: TODOS.md Cleanup

If TODOS.md exists: move items explicitly completed by the diff to Completed; mark conservatively. Optional: check whether TODO/FIXME in the diff should go into TODOS.

Step 8: VERSION bump Confirmation

Prohibit bumping VERSION without authorization.

  • If VERSION has already been modified on this branch: check whether CHANGELOG covers all changes
  • If not modified: AskUserQuestion (A) Bump PATCH B) Bump MINOR C) Skip)
  • Recommend C (documentation-only changes usually do not require a bump)

Step 9: Commit and Output

  • If there are no documentation modifications: output "All documentation is up to date." and end
  • If there are modifications:git add <files>、git commit -m "docs: sync documentation for release", output doc health summary

Doc health summary format：

Documentation health:
  README.md       [Updated|Current] (description)
  ARCHITECTURE.md [Updated|Current|—] (description)
  CONTRIBUTING.md [Updated|Current|—] (description)
  CHANGELOG.md    [Voice polished|Current|—] (description)
  TODOS.md        [Updated|Current|—] (description)
  VERSION         [Not bumped|Already bumped|Skipped] (description)

Input & Output

Input

  • Optional: base branch name; otherwise infer from project configuration or gh to infer
  • Feature branch containing unmerged documentation changes

Output

  • Updated documentation files (if any) and a single commit
  • Structured doc health summary

Restrictions

Hard boundaries

  • Do not rewrite, replace, or delete existing CHANGELOG entries
  • Do not bump VERSION without authorization; always confirm with the user
  • Do not use Write to overwrite CHANGELOG; use Edit for exact matching
  • Do not run on the base branch

Skill Boundaries

Do not do these (other skills can handle them)：

  • Establish conventions: Use discover-docs-norms
  • Assess document health: Use assess-docs
  • Guide document structure: Use bootstrap-docs

Self-Check

Success Criteria

  • Base branch correctly detected
  • Diff analyzed and classified
  • Per-file audit completed; Auto-update applied
  • CHANGELOG only polished, not rewritten
  • VERSION change confirmed by user
  • Cross-document consistency verified
  • If there are changes, committed and summary output

Acceptance Tests

Can a new contributor complete their first contribution using only README/CONTRIBUTING?

Examples

Example 1: Sync after a feature release

Scenario: New skill sync-release-docs has been merged, and the README capability table and CHANGELOG need to be updated.

Steps: Detect base branch → analyze diff → find that README is missing the new skill and CHANGELOG already has an entry → Auto-update README table → polish CHANGELOG wording → confirm not to bump VERSION → commit.

Example 2: No changes

Scenario: The documentation is already consistent with the diff.

Output：All documentation is up to date.

Appendix: Output Contract

This skill produces updated documentation and a single commit:

Element Format Required Fields Path Pattern
Documentation changes File diff Involves README / ARCHITECTURE / CONTRIBUTING / CLAUDE.md / CHANGELOG / TODOs; each item includes reason Project root and corresponding files under docs/
Commit git commit Single commit; message follows Conventional Commits; body lists the synced file list git history
Health summary Structured chat output Fields: files_updated[], files_skipped[] (with reasons), todos_resolved[], commit_hash Standard output