# Release Review — never auto-publish

Companion to [github-ops](../skills/github-ops/SKILL.md), the
release flows in `cli-tools.md`, and [public-posts](public-posts.md)
(the broader sibling — preview text before sending it to any third-party
surface, not just the release page).

## The rule

**Never run `gh release create` without explicit user approval.** Push the
commit + tag if the user has authorised the publish flow, but stop at the
release step and surface the diff for review.

This applies to:

- `gh release create`
- `gh release edit --draft=false` (publishing a previously drafted release)
- Any other action that creates a public, externally-visible release page
- Force-pushing tags that already have a release

## Why

A GitHub release is a one-way visibility commitment. Once published:

- The release page shows up in the user's profile feed
- Any `uv tool install <pkg>@<tag>` / `pip install <pkg>==<version>` resolves
  to the published artefacts
- People watching the repo get a "new release" notification
- Search engines index the release notes
- "Yanking" a release leaves a 410 / "this release was deleted" trace

Pushing a commit + tag is *also* visible, but it's a much smaller signal
than a release page. The user can review the pushed state on GitHub
before creating the release.

The user has explicitly corrected this drift (rookery v0.3.0, 2026-04-28):

> "no human review before github release"

— meaning a human review step is required *before* the release is published.

## How to apply — the right release flow

When invoking the github-ops `update` mode (or any equivalent flow):

1. Bump the version, update CHANGELOG / README "Recent Updates"
2. `git commit` + `git tag` (these stay local until step 4)
3. Run push-gate preflight on the commit
4. `git push origin <branch>` + `git push origin <tag>` — OK to do
   without separate confirmation when the user has authorised the publish
5. **Stop here.** Surface the pushed state to the user:
   - Link to the tag's diff: `https://github.com/<org>/<repo>/compare/<prev>...<tag>`
   - Link to the tag's tree: `https://github.com/<org>/<repo>/tree/<tag>`
   - The CHANGELOG section that would become the release notes
6. Wait for explicit user approval before running `gh release create`
7. If the user wants edits to the release notes, apply them, then ask
   again

## What to surface for the review

When you stop at step 5, give the user:

- The exact `gh release create` command you'd run, with the `--notes` content
- The git diff URL for the tag
- A reminder that the tag + commit are already pushed, so review can
  happen on GitHub directly

Example:

```
v0.3.0 commit + tag pushed. Ready to create the GitHub release.

Diff: https://github.com/0xDarkMatter/rookery/compare/v0.2.0...v0.3.0
Tree: https://github.com/0xDarkMatter/rookery/tree/v0.3.0

Proposed release command:
  gh release create v0.3.0 \
    --repo 0xDarkMatter/rookery \
    --title "v0.3.0 — Parcel reporting refactor" \
    --notes-file /tmp/v030-notes.md

Want me to run it, or do you want to review on GitHub first?
```

## When to bend the rule

If the user has already explicitly said "create the release" / "publish
v0.X.Y" / "ship it" in the same turn that authorises the push, you can
skip the separate confirmation step. The rule is about *implicit*
authorisation — the user saying "use github-ops update mode" is not
the same as saying "publish the release page".

If unsure, ask. The cost of asking is low; the cost of an unwanted
release is real.

## Cross-reference

- `~/.claude/skills/github-ops/SKILL.md` — release flow modes
- `~/.claude/skills/push-gate/scripts/preflight.sh` — pre-push secret scan
- `~/.claude/rules/cli-tools.md` — `gh` CLI usage patterns