Release Instructions

1. List what's in the release

LAST=$(git tag --sort=-v:refname | head -1)
git log "$LAST"..HEAD --oneline

Group the commits mentally by feat / fix / docs / chore. Decide the next tag (vX.Y.Z).

2. For each user-facing item, dig up evidence

Don't trust commit subjects alone — find the actual artifact so the changelog entry is accurate and the reader can verify:

• User docs: docs/en/user/*.md and docs/ru/user/*.md — link the page.
• Dev docs: docs/dev/*.md — link if the feature has an internal spec or pattern doc.
• Tests / e2e: internal/**/<feature>_test.go, e2e/<feature>/* — gives you a real example payload or invocation.
• Specs / plans: docs/superpowers/specs/, docs/superpowers/plans/ — useful as authoritative description.
• CLI / scripts: cmd/<x>/main.go, scripts/<x>.py — gives you the exact invocation.

Use grep -l <symbol> docs/ -r and find -name '<feature>*' to locate them.

3. Write the changelog entry (EN + RU)

Add a new section at the top of both docs/en/changelog.md and docs/ru/changelog.md. The Russian version is a straight translation of the English one — same structure, same links (adjusted to relative paths), same set of features. Per the project rule on bilingual docs, neither file is allowed to drift.

## vX.Y.Z — YYYY-MM-DD

### <Feature name> — <one-line value prop>

- **What.** <One sentence describing the change.>
- **Why.** <Concrete reason the user should care.>
- **How.** <Doc links, mutation/CLI example, frontmatter key, admin path — enough to start using it.>

Rules of thumb:

• Order: features first (most impactful on top), then Fixes, then Docs & chore.
• Skip pure internal noise (CI tweaks, single-typo fixes) unless they affect a user.
• A backward-compatible automatic improvement (no flag, no config) still gets a section — explicitly state "automatic, no flags".
• Keep the prose user-facing. No commit hashes in the changelog; that's what git is for.
• One feature = one block. Don't bundle unrelated changes.

4. Commit the changelog

git add docs/en/changelog.md docs/ru/changelog.md
git commit -m "docs(changelog): vX.Y.Z"

Use specific paths in git add — never git add -A on a release commit (you'll sweep up unrelated untracked files).

5. Create an annotated tag

Annotated tags carry the release notes inside the tag object so git show vX.Y.Z produces a self-contained summary.

git tag -a vX.Y.Z -m "$(cat <<'EOF'
vX.Y.Z

<paste a compact version of the changelog section here —
 What/Why/How bullets collapsed to one line each is fine>
EOF
)"

Verify:

git show vX.Y.Z --stat | head -40

6. Push (manual)

Push is a deliberate, human-controlled step — never automated.

git push origin main
git push origin vX.Y.Z

Undo a local tag before pushing if you change your mind:

git tag -d vX.Y.Z