| name | shipping-and-launch |
| description | Pre-deploy hygiene for a Spring Boot 4 feature — verify gates, capture rollback plan, sign off observability, generate release notes, and stage the rollout. Used by `/ship` after `/review` approves the diff. The agent never deploys; it produces the plan a human executes. |
| when_to_use | ["Phase 8 (Ship) — `/ship` command, after `/review` verdict is approve.","Pre-deploy review on a brownfield repo where the toolkit is being adopted and the team wants a structured launch plan."] |
| authoritative_references | [".claude/commands/ship.md",".claude/templates/ship-plan.template.md",".claude/skills/spring-security-baseline/SKILL.md",".claude/skills/flyway-or-liquibase-detection/SKILL.md"] |
Shipping and launch
Faster is safer. Small, reversible, observable changes ship more often and break less.
What this skill produces
The artifact .specs/<feature-id>/09-ship-plan.md, populated from .claude/templates/ship-plan.template.md, with these sections filled in:
- Pre-ship gate results (PASS/FAIL per gate; FAIL = halt).
- Feature-flag posture (flag name, default, kill-switch, owner).
- Migration safety (Flyway/Liquibase script list, expand-vs-contract classification, rollback procedure).
- Observability sign-off (new metrics, structured-log keys, alert rules, dashboard link).
- Rollback plan (revert commit; DB rollback or contract-step procedure; on-call escalation).
- Staged rollout plan (canary → percentage steps → 100%).
- Release notes (user-facing changelog excerpt + internal notes).
Pre-ship gates (must all be green)
| Gate | Source of truth | Halt if |
|---|
| Validation | 07-validation-report.md verdict | not PASS |
| Code review | 08-code-review.md verdict | not Approve (or Approve with waivers linking ADRs) |
| Open questions | 01-spec.md, 03-design.md ## Open Questions | any unresolved Q-NNN |
| Baseline regression | .specs/_baseline.json vs latest harness | any new failure not in baseline |
| Diff scope | git diff origin/main...HEAD | files outside any task's files_in_scope |
If any gate halts, stop and tell the user which command to run (/build, /test, /validate, or /review). Do not write a partial ship plan.
Feature flags
For any change that adds or alters a runtime path, decide:
- Flag required? Yes if the change is risky, irreversible, or touches a hot path. No if it's a pure bug fix or strictly additive.
- Default? Off in production until the canary clears. On in non-prod.
- Kill-switch? A documented config knob (env var or remote config key) that disables the new path without a redeploy.
- Owner? A named human (not "the team").
Record this in the ship plan even if the answer is "no flag" — with the reasoning.
Migration safety
Detect the migration tool with .claude/skills/flyway-or-liquibase-detection/SKILL.md. For each migration script in the diff:
| Classification | Definition | Required action |
|---|
| Forward-only safe | Adds nullable column, new table, new index, new view | Proceed |
| Expand step | First half of an expand-then-contract: write to old + new, read old | Proceed; record contract-step ticket |
| Contract step | Second half: read new, drop old | Verify expand step is in production for at least one full release cycle (or the period the team agreed to) |
| Breaking | Drops/renames a column, narrows a type, removes a table | Halt unless an ADR documents the migration plan, the feature flag gating it, and the rollback |
No edits to a previously-released migration script. New script, always.
Record the rollback procedure: revert commit alone is not enough when a migration ran. Spell out the SQL or contract step that reverses the schema change.
Observability sign-off
For each new endpoint, message handler, or background task, verify:
- A
MeterRegistry counter or timer with a stable, low-cardinality name (e.g. gift_card.redeemed, gift_card.rejected).
- A structured log line at the boundary with the feature-id and the AC-NNN it covers.
- An alert rule (or explicit "no alert needed" with reasoning).
- A dashboard link or panel reference.
- For HTTP endpoints: response-time histogram (p50/p95/p99) bucketed via Micrometer.
If any item is missing, halt and recommend /build or /test to add it before shipping.
Rollback plan
Every ship plan must answer three questions in writing:
- How do we know it's broken? (Alert name + threshold; user-report channel; metric anomaly.)
- How do we stop the bleeding in under 5 minutes? (Flag flip; revert; scale-down; circuit breaker.)
- How do we recover state? (Revert commit; replay events from offset N; reconcile job; manual SQL.)
If any answer is "we'd figure it out", halt — that's not a rollback plan.
Staged rollout
Default rollout shape (override only with an ADR):
canary (1 instance, ~1%) → 10% → 50% → 100%
↳ 30 min observation ↳ 1 hr ↳ 4 hr ↳ steady state
For each step the plan records:
- Entry criteria (previous step green for the observation window, no SEV-2+ alerts, error rate within budget).
- Abort criteria (specific metric thresholds; named on-call decides).
- Who watches what.
For changes behind a flag with no schema impact, the rollout is "flip flag for cohort N → observe → expand cohort". Same shape, different lever.
Release notes
Two audiences, two sections in the ship plan:
- External / user-facing. Plain English, one to three bullets. Links to docs if the API changed. No internal jargon.
- Internal / engineering. Diff summary, AC-NNN list, ADR links, migration class, flag name, dashboard.
Both are generated from git log origin/main..HEAD plus 01-spec.md ## Goal and 04-tasks.md task titles. The agent drafts both; the user edits the external one before publishing.
Anti-rationalizations
| Excuse | Counter |
|---|
| "Small change, skip the flag." | Small changes still cause incidents. The flag costs minutes; an incident costs hours. Add the flag, default off, flip after the canary. |
| "Forward-only migration, no rollback needed." | Forward-only refers to the script direction, not the feature. The feature still needs a rollback path (flag flip, contract step, or replay). Document it. |
| "We'll add metrics if it breaks." | If it breaks without metrics you won't know. Add the counter and the alert before shipping, not after. |
| "100% rollout is fine, this is a tiny endpoint." | "Tiny" endpoints fan out to dependencies you don't see. Canary first; 5 minutes of caution prevents 5 hours of recovery. |
| "Release notes are a Product thing." | Engineering writes the technical truth; Product edits the tone. Skipping the engineering draft means the notes are wrong. |
| "Validation is green so we're good to ship." | Green tests prove the code does what the tests say. Shipping also requires flag posture, rollback, observability, and a rollout plan. |
Red flags (block the ship plan)
- A migration script is renamed or edited from a previous release.
- The diff edits a previously-deployed feature flag's default without an ADR.
- A new endpoint has no metric and no alert.
- The rollback "plan" is "revert the commit" with no migration recovery.
- The release notes are auto-generated commit subjects with no human pass.
- Any
Q-NNN is still open in the spec or design.
Process inside /ship
- Verify gates. Walk the table above. Halt at the first FAIL with a specific recovery command.
- Inspect the diff.
git diff origin/main...HEAD — classify migrations, identify new endpoints, locate metric registrations.
- Fill the template. Use
.claude/templates/ship-plan.template.md. Every section must have content; "n/a" is allowed only with a one-line reason.
- Surface required human inputs. Flag owner, alert thresholds, and rollout cohorts often need a human decision; mark these
Q-NNN-style and halt until answered. Never invent.
- Emit the deploy command for the user. Print the suggested command (e.g.
kubectl rollout ..., mvn deploy, the team's release pipeline trigger). The agent never executes it.
Verification
A ship plan is complete when:
- All seven sections are filled (no placeholder text).
- Every gate row in the pre-ship table is
PASS.
- Migration scripts are classified, with named rollback steps.
- Each new endpoint has at least one named metric and one alert (or a documented "no alert" reason).
- The release notes have both an external and an internal section.
- The user has confirmed the flag owner, the alert thresholds, and the rollout cohorts.
