shipping-and-launch

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:

1. Pre-ship gate results (PASS/FAIL per gate; FAIL = halt).
2. Feature-flag posture (flag name, default, kill-switch, owner).
3. Migration safety (Flyway/Liquibase script list, expand-vs-contract classification, rollback procedure).
4. Observability sign-off (new metrics, structured-log keys, alert rules, dashboard link).
5. Rollback plan (revert commit; DB rollback or contract-step procedure; on-call escalation).
6. Staged rollout plan (canary → percentage steps → 100%).
7. 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:

1. How do we know it's broken? (Alert name + threshold; user-report channel; metric anomaly.)
2. How do we stop the bleeding in under 5 minutes? (Flag flip; revert; scale-down; circuit breaker.)
3. 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

1. Verify gates. Walk the table above. Halt at the first FAIL with a specific recovery command.
2. Inspect the diff. git diff origin/main...HEAD — classify migrations, identify new endpoints, locate metric registrations.
3. 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.
4. 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.
5. 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.