subwave: Skill for Claude Code

SUB/WAVE release PR

Open a pull request from develop → main. Everything after that — version bump, CHANGELOG, tag, GitHub release, image publishing — is handled by the release-please and publish-images workflows once the PR merges. This skill's job is just to surface a clean PR with a useful summary.

Why this skill exists

A release PR for SUB/WAVE is mechanical but easy to get wrong by hand: forgetting to fetch first, listing merge commits in the body, picking up commits that are actually already on main via a back-merge. The skill encodes the right git plumbing and the body format that matches the project's recent PR history.

It also keeps develop from drifting behind main. After every release, release-please pushes a chore(main): release X.Y.Z version bump (and CHANGELOG entry) directly to main, and that commit — plus the merge-commit bubble from the release PR — never flows back to develop on its own. Left alone, develop steadily falls "N commits behind main" even though it carries every line of real source. This skill detects that gap up front and closes it with a back-merge after the release lands (Step 8).

Workflow

Step 0 — Sanity checks

Run these from the repo root (/home/klair/Projects/subwave). They're cheap, surface state, and let you decide whether to proceed:

git rev-parse --show-toplevel              # confirm we're in subwave (or any git repo)
git status --short                         # any uncommitted work?
git rev-parse --abbrev-ref HEAD            # current branch (informational — we work via remote refs)
git fetch origin main develop              # MUST run before computing the diff, otherwise stale
git rev-list --left-right --count origin/develop...origin/main   # "<ahead>	<behind>" — develop relative to main

What to do with the output:

• If git status --short shows uncommitted changes, surface them to the user and ask whether to proceed (the PR is built from origin/develop, so local edits won't be in it — but the user might want to commit them first).
• If git fetch fails (no network, no remote), stop and tell the user. Don't fall back to local refs — the PR base is origin/main and the head is origin/develop, so the comparison must be against fresh remotes.
• If the second number ("behind") is > 0, develop is behind main. Inspect those commits with git log --oneline origin/develop..origin/main before reacting. Almost always they're pure release bookkeeping — chore(main): release … version bumps + merge-commit bubbles from prior release PRs — in which case develop is not missing any real source and the release PR is unaffected (a merge commit does a 3-way merge, so main's version bump and CHANGELOG survive). Note the gap to the user, proceed with the PR, and plan to close it with the Step 8 back-merge once this release lands. Only stop and flag it as a real problem if those "behind" commits include feat: / fix: / refactor: work that isn't already on develop — that means a hotfix landed straight on main and should be back-merged into develop before you cut the release, so the release PR doesn't reintroduce or conflict with it.