ship

Files (2)

• SKILL.md
• launch-runbook.md · references/

SKILL.md (first lines)

# Ship

Part of the **Ship** phase — see the `workflow` skill for tiers and sequencing.

Shipping is the phase where mistakes become public and expensive. The rule that
governs everything below: **every ship step ends with evidence a non-coding PM
can judge** — a PR URL, green CI, a deploy URL, smoke-check output, a
screenshot. Never "deployed, should be fine." Show the thing.

## Tier scaling

| Tier | Ship process | Evidence at the end |
|---|---|---|
| **T1** | branch → commit → PR → merge. Deploy only if the change is user-visible or the user asks. | PR URL + green CI |
| **T2** | T1 + deploy + single-pass smoke check on the live URL. | Deploy URL + smoke output |
| **T3** (money/auth/data/migrations) | Full runbook: **rollback criteria written BEFORE deploying**, staged rollout, post-deploy monitoring, T+24h check. See [references/launch-runbook.md](references/launch-runbook.md). | Runbook with each gate checked + live evidence |

Never enter Ship without a passing Verify phase (`verify-done`). Shipping does
not re-litigate verification — but it does re-run it when code changes (below).

## Git hygiene

- **Never `git add -A` or `git add .`.** Stage only the files you changed for
  this task, by explicit path. Unrelated dirt in the working tree stays out of
  your commit — it belongs to another change or to nobody.
- **Bisectable commits.** Group the diff into logical units, one coherent change
  per commit (not one file per commit). Order so dependencies land first:
  1. Infrastructure: config, migrations, route/schema additions
  2. Data layer and services (with their tests)
  3. UI: components, pages, styles (with their tests)
  4. Docs/changelog last
  A module and its test file travel in the same commit. Each commit must be
  independently valid — no broken imports, no references to code that doesn't
  exist yet. Small diffs (<50 lines across <4 files) can be a single commit.
- **Every commit revertible.** `git revert <sha>` on any single commit should
  cleanly undo one logical change. If a schema change and dependent code can't
  be reverted independently, note that in the commit body — it changes the
  rollback plan.
- **Never force push.** Never rewrite pushed history. Plain `git push` only.
  Sole exception: scrubbing a leaked secret from history (see `security`), with
  the user's explicit approval — rotate the secret first.

## PR / merge discipline

**Merge the base branch BEFORE the final test run.** Tests must run against the
merged state, not your stale branch:

```sh
git fetch origin <base> && git merge origin/<base> --no-edit
```

Auto-resolve only trivial conflicts (lockfiles, changelog ordering). Anything
ambiguous: stop and use the `resolving-merge-conflicts` skill (installed
separately) — never guess a conflict resolution.

**Verification gate — no completion claims without fresh verification evidence.**
If ANY code changed after the last test run (review fixes, conflict resolution),
re-run the tests and paste fresh output. "Should work now" → run it. "I'm
confident" → confidence is not evidence. "I tested earlier" → code changed since
then. Stale output is not acceptable; trivial changes break production too.

**Readiness gate (before merge):**
- Failing tests or failing CI → **blocker**. Never merge red.
- Merge conflicts (`gh pr view --json mergeable`) → blocker until resolved.
- Stale durable state → **warning, not blocker**: if the diff adds features but
  `.handoff/STATUS.md` / `CHANGELOG.md` weren't touched, flag it and offer to
  update before merging.
- PR body accuracy: compare the body against `git log <base>..HEAD --oneline`.
  A PR body describing last week's version of the change is a warning — fix it,
  the PM reads the PR body, not the diff.

**Post-fail invariant — after ANY non-zero exit from `gh pr merge`, query PR
state before doing anything else. Never blind-retry the merge:**

```sh
gh pr view --json state,mergeCommit,autoMergeRequest,mergedAt
```

- `state == MERGED` → the server-side merge actually succeeded (or a concurrent
  merge landed). Say "PR is merged on GitHub", capture the merge SHA, move on.
- `state == OPEN` and `autoMergeRequest` non-null → merge queue / auto-merge is
  processing. Expected — poll `gh pr view --json state` (30s interval), don't
  re-merge.
- `state == OPEN` and `autoMergeRequest` null → genuine failure. Surface the
  merge stderr AND the current PR state, then stop for the user.
- `state == CLOSED` → closed without merging. Stop.

Hard rule: never call `gh pr merge` a second time after a failure. Server state
is authoritative; a blind retry can double-merge or mask what happened.

## Deploy-target detection

Detect the target from config files in the repo root. **Order matters: data
layer deploys before the frontend that depends on it.**

```sh
ls convex 2>/dev/null && echo "TARGET:convex"
ls supabase/migrations 2>/dev/null && echo "TARGET:supabase-migrations"
ls wrangler.jsonc wrangler.toml 2>/dev/null && echo "TARGET:cloudflare"
(ls vercel.json 2>/dev/null || ls -d .vercel 2>/dev/null) && echo "TARGET:vercel"
```

**Convex (`convex/` dir)** — deploy BEFORE the frontend deploy:
`npx convex deploy`. Schema and function changes must be live before the
frontend that calls them. A Convex schema change is a migration → **this is T3**
(reverting frontend code does not revert the schema; plan the down path first).

**Supabase (`supabase/migrations/`)** — review every pending migration file
before pushing, then `supabase db push` (or apply via the Supabase MCP tools).
Database migrations are **always T3**: irreversible-by-default, so the rollback
plan (down migration or backup/restore) is written before pushing.

**Cloudflare Workers/Pages (`wrangler.jsonc` / `wrangler.toml`)** —
`wrangler deploy` (Workers) or `wrangler pages deploy` (Pages). For a T3 gradual
rollout on Workers: `wrangler versions upload` then
`wrangler versions deploy` to split traffic by percentage between old and new.
Rollback: `wrangler rollback` (Workers) or re-deploy the previous version.

**Vercel (`vercel.json` / `.vercel/`)** — two modes; check which this repo uses:

From AbdurRafay2004/handoff, MIT.

More from AbdurRafay2004/handoff