pedronauck/ship-pr

ship-pr — Finish-a-Feature Release & PR Workflow

This skill drives the end-of-feature ritual: detect what changed, document its impact, generate release notes, write a complete PR description, commit cleanly, open the PR via gh, and (optionally) start an automated review-watch loop.

Two layers exist:

• Core path (always runs): explore impact → build PR description → commit → gh pr create.
• Optional integrations (auto-detected): pr-release for release notes, skeeper for spec sync, qa-report/qa-execution artifacts under .compozy/tasks/<slug>/qa/, compozy reviews watch for CodeRabbit auto-fix.

Optional steps are skipped silently when the supporting tool or artifact is not present — the skill never blocks on missing tooling.

Required Reading Router

Match the phase to the row. Read the listed file in full before acting on that phase. Inline content in this SKILL.md is a tripwire, not the source of truth.

| Phase | MUST read | | ---------------------------------------------------- | -------------------------------------------------------- | | Explore PR impact (docs/site/README/changelog) | references/explore-impact.md | | Generate release notes | references/release-notes.md | | Build PR description | references/pr-description.md | | Build PR description with QA artifacts | references/pr-description.md + references/qa-artifacts.md | | Commit staged changes | references/commit-conventions.md | | Launch CodeRabbit review-watch loop | references/coderabbit-watch.md |

Reference Index

• references/explore-impact.md — how to fan out parallel Explore subagents to surface every doc/site/README/CHANGELOG that the change touches, and how to aggregate their output.
• references/release-notes.md — two flows: invoke pr-release add-note when the CLI is on PATH, otherwise build an inline conventional-commit changelog for the PR body using the same emoji legend pr-release uses.
• references/pr-description.md — PR body template (Summary / Changes / Release Notes / QA / Test plan) and the rules for filling each section honestly.
• references/qa-artifacts.md — how to detect .compozy/tasks/<slug>/qa/ artifacts, extract bug counts and screenshot paths, and inject them into the PR body.
• references/commit-conventions.md — commitlint-config detection priority, how to read type-enum/scope-enum, and the staging/HEREDOC commit rules.
• references/coderabbit-watch.md — exact compozy reviews watch command, task-slug resolution, and the skip-if-missing guard.

Pre-flight: detect tooling

Run the bundled detector (read-only — probes the filesystem and PATH only):

bash skills/mine/ship-pr/scripts/detect-tooling.sh

It prints a JSON object describing what is available:

{
  "gh": true,
  "pr_release": false,
  "compozy": true,
  "skeeper_installed": true,
  "skeeper_configured": false,
  "commitlint_config": "commitlint.config.cjs",
  "qa_output_paths": [".compozy/tasks/my-feature/qa"],
  "task_slug_candidates": ["my-feature"]
}

Branch decisions off this output. Notes:

• skeeper_installed reports whether the binary is on PATH; skeeper_configured is true only when both .skeeper/ and skeeper.lock exist (the gating signal for step 3).
• commitlint_config is an empty string when no config is found — that means "use @commitlint/config-conventional defaults" per references/commit-conventions.md §7.

Hard requirements: gh on PATH and a git working tree with changes ready to ship (staged or unstaged in tracked files). Abort with a clear message if either is missing — do not invent workarounds.

Operating Loop

Run the steps in order. Skip optional steps cleanly when the detector reports the supporting tool is absent.

1. Explore the change's impact

Fan out up to 3 parallel Explore subagents over the diff against the base branch. Each agent gets a distinct slice: docs site / README & top-level docs / .github/, CHANGELOG, examples & e2e. Aggregate results into a single bullet list grouped by impact area — this list feeds steps 2 and 4.

Gist tripwires:

• Any new public API, CLI flag, config key, or env var → must be reflected in docs or README before shipping.
• Any new user-visible UI element → must have an entry in release notes.
• Any change to .github/workflows/ → call it out separately; reviewers always want to see CI diffs.

STOP. Read references/explore-impact.md in full before launching the Explore agents. The inline tripwires above are not the contract — the reference defines the exact search prompts, the parallelism budget, and the aggregation format.

2. Generate release notes

Two flows, selected by the detector:

• Flow A — pr-release on PATH. For each user-visible bullet from step 1, run pr-release add-note --title "<title>" --type {feature|fix|breaking|highlight} --body "<markdown>". The notes land in .release-notes/ and are picked up automatically by the next release PR.
• Flow B — fallback. Build an inline changelog block to embed in the PR description: group git log <base>..HEAD by conventional-commit type using the same legend the project's cliff.toml uses (🎉 Features, 🐛 Bug Fixes, ⚡ Performance Improvements, 🔒 Security, 📚 Documentation, 📦 Build System, 🔧 CI/CD, ♻️ Refactoring, 🧪 Testing, 💅 Style, 🔧 Miscellaneous Tasks, ⏪ Reverts, Other Changes).

STOP. Read references/release-notes.md in full before running either flow. It contains the exact CLI invocations, the conventional-commit grouping rules, and the worked examples for both flows.

3. (Optional) Skeeper sync

Only if the detector reports skeeper_configured: true (i.e., .skeeper/ directory and skeeper.lock both exist):

skeeper sync --dry-run         # preview
skeeper sync --commit -m "..."  # apply + stage skeeper.lock

Review the dry-run plan before applying. Skip this step entirely otherwise — do not install or initialise skeeper as a side effect.

4. Build the PR description

Assemble these sections in order: Summary (≤ 3 bullets, focus on user-visible outcome), Changes (grouped by impact area from step 1), Release Notes (excerpt from step 2; for Flow B paste the full inline changelog here), QA (only when the detector reports qa_output_paths), Test plan (checklist of checks actually performed — never invent results).

Gist tripwires:

• Title ≤ 70 characters; everything else goes in the body.
• "Test plan" must reflect what actually ran. Unrun checks belong in a follow-up issue, not in the checklist as if they passed.
• If the repo ships a .github/PULL_REQUEST_TEMPLATE.md, align the section headings to it before merging in the content above.

STOP. Read references/pr-description.md in full before writing the body. When the detector reports QA artifacts, also STOP and read references/qa-artifacts.md before drafting the QA section — that reference defines the path conventions, severity extraction, and screenshot linking rules.

5. Commit staged changes

Detect the repo's commit convention via the detector's commitlint_config value (fallback to @commitlint/config-conventional defaults). Stage files by name (never git add -A), write the commit message via HEREDOC, and never use --no-verify or --no-gpg-sign.

Gist tripwires:

• Do not stage files outside the scope of this feature, even if git status lists them as modified.
• If a pre-commit hook fails, fix the underlying issue and create a new commit. Do not --amend after a failed hook — the prior commit may belong to unrelated work.

STOP. Read references/commit-conventions.md in full before staging or committing. It contains the config-detection priority, the rules for reading type-enum/scope-enum, and the exact HEREDOC commit pattern.

6. Open the PR via gh

Refuse to push from the repo's main branch — opening a PR requires a feature branch with a distinct head:

BRANCH="$(git rev-parse --abbrev-ref HEAD)"
case "$BRANCH" in
  main|master|develop|trunk) echo "Refusing to ship from $BRANCH. Create a feature branch first." >&2; exit 1 ;;
esac

git push -u origin "$BRANCH"
gh pr create --title "<title>" --body-file "$BODY_FILE"

$BODY_FILE is the temp file written in step 4 (per references/pr-description.md §5). Capture the returned PR URL and number from gh's stdout — the PR number is the input for step 7.

7. (Optional) CodeRabbit review-watch loop

Only if the detector reports compozy: true. Resolve the task slug:

1. If the detector reports any task_slug_candidates, pick the one whose name best matches the current git branch (or ask the user when ambiguous).
2. Otherwise, derive a kebab-case slug from the branch name and create .compozy/tasks/<slug>/ (just mkdir -p — the compozy reviews watch daemon populates the rest).

Then run, substituting <slug> and <number>:

compozy reviews watch \
  --auto-commit --auto-push \
  --batch-size 20 \
  --ide codex --model gpt-5.4 --reasoning-effort high \
  --max-rounds 3 \
  --name <slug> \
  --pr <number> \
  --provider coderabbit

STOP. Read references/coderabbit-watch.md in full before invoking the command. It documents every flag, the alternative --until-clean mode, the attach-mode options, and the failure paths (missing compozy, missing .compozy/tasks/<slug>/, provider auth missing).

When NOT to use

• Draft PRs of unfinished work — finish the implementation first; this skill assumes the change is shippable.
• Amending an already-merged PR — the gh pr create step would fail, and re-running compozy reviews watch against a merged PR has no effect.
• Repo-level release publishing (cutting a tagged release, opening a release PR off RELEASE_BODY.md) — that is the pr-release CLI's own pr-release subcommand. This skill only adds release-note entries; it does not orchestrate the release branch.
• In-progress development checkpoints / WIP commits — use a plain git commit instead. This skill is the end-of-feature ritual.