AkiGarage/readme-release-sync

README Release Sync

Use this skill whenever a task touches README copy, release notes, changelogs, product screenshots/GIFs, or bilingual product documentation.

The goal is to reduce maintainer review burden: docs should match the real product state before reviewers have to catch stale names, screenshots, feature descriptions, or English/Japanese mismatches.

Core Rule

Do not edit product-facing docs from the existing docs alone. First identify the current source of truth: app code, UI strings, screenshots/GIFs, release branch, version files, package metadata, or a user-provided latest screenshot/video.

Workflow

1. Anchor the target state

   • Confirm the product/app name, branch, version, binary name, and platform scope from repo files or explicit user instructions.
   • Inspect the relevant implementation or UI strings for features being described.
   • Treat user-provided latest screenshots/videos as authoritative visual evidence unless code or branch context clearly contradicts them.

2. Update docs and media together

   • Replace stale screenshots/GIFs when the UI changed.
   • Verify every image reference exists and points to the intended file.
   • Check screenshots do not visibly contradict the current product name, menu labels, version, or UI state.
   • Remove old media references when they describe removed behavior.
   • For a public release fed by a private repository, update public README files in the public repository on release/vX.Y.Z after the scrubbed snapshot has been copied there. Do not rely on the private README as the final public source of truth.
   • Treat public CHANGELOG, release draft notes, install docs, and public development logs as part of the same release-facing doc set. They should use the same product names, version, asset names, privacy claims, and user-facing wording as the README.

3. Keep bilingual docs equivalent

   • Compare English and Japanese sections claim by claim.
   • Preserve the same product facts, feature order, caveats, and setup requirements in both languages.
   • Do not leave important behavior explained in only one language.

4. Write readable public README copy

   • Make first-read sections scannable: short paragraphs, one idea per paragraph, and blank lines where they improve readability.
   • Lead with what the product does and what the user can see or do. Put implementation mechanics later only when they matter to setup, safety, or troubleshooting.
   • Prefer clear behavior lines over packed feature sentences. A good shape is a one-sentence overview followed by 2-4 concise capability lines.
   • For UI behavior, describe the visible result: drag to move, resize from an edge or corner, double-click to reset. Avoid internal framework details such as hit bands, cursor rects, scaling internals, or exact default percentages unless the user needs them.
   • Keep detailed information where it is genuinely useful, but do not make the public README carry maintainer-only implementation explanation.
   • Apply the same readability rule to release notes and changelog entries: avoid internal precision such as exact default percentages, hit-band wording, cursor-rect mechanics, or build-system trivia unless it affects a user-visible fix, install step, or troubleshooting path.

5. Make Japanese reader-friendly

   • Prefer ordinary Japanese UI terms when natural: タブ, 詳細パネル, マウスオーバー, 最小表示, フローティングタブ.
   • Keep technical literals such as commands, paths, package names, app names, URLs, and code identifiers in English.
   • Remove redundant feature lists and repeated paragraphs; make the main feature set quickly scannable for a general Japanese reader.

6. Scan for stale product drift

   • Old product names, old app names, old binary names, and old repository names.
   • Old version numbers outside historical changelog entries.
   • Obsolete UI labels, removed platform notes, and screenshots from older behavior.
   • Claims that imply a dependency must be running when only an installed CLI or package is required.

7. Validate before closing

   • Run relevant doc lint/check commands when available.
   • Run a bounded rg scan for stale names/versions/labels.
   • Run the stale/private/too-internal wording scan across README files, changelogs, release notes, and any public docs shipped in the release, not only the top-level README.
   • Check README image links exist.
   • For release PRs, provide maintainers the GitHub-rendered README URLs for the branch/PR and wait for explicit visual approval. This must match the GitHub display users will actually see; local previews, raw Markdown, static screenshots, or automated checks are only supporting evidence.
   • Inspect the public repository git diff so README claims, version metadata, release asset names, and copied implementation changes agree.
   • For public releases, prefer release/vX.Y.Z branch -> PR -> CI -> merge before tag or GitHub Release creation. Direct main pushes should be used only when the maintainer explicitly asks to skip the PR gate.
   • If code changed, run the relevant tests or build.
   • Summarize the source-of-truth checks, not just edited files.

Output Checklist

Before finishing, report:

• product name/version/branch checked;
• media references checked;
• Japanese/English parity checked;
• GitHub-rendered README visual approval received, or explicitly still pending;
• stale wording scan result;
• tests/build/doc checks run, or why they were not run.