Pre-Ship

Production readiness check before releasing a feature or deploying. Different from gap-check (code quality) — this is whether the system is safe to release.

When to Use

• User is about to deploy, merge to main, cut a release, or promote to production
• User says "final check", "good to go?", "anything pending?", "last check", "pre-ship"
• End of a feature spanning multiple sessions — final gate before shipping
• Before pushing to a shared environment (staging → prod)

Do not use this for:

• Code quality review — use gap-check
• Plan review — use plan-review
• PR comment triage — use pr-triage

Preflight — confirm the deployment context

Before walking the 7 categories, establish:

1. Target environment — production, staging, canary, preview? The bar differs.
2. Change type — code change, config change, DB-only migration, infra-only change, dependency bump, pure docs? Some categories N/A for some change types.
3. Is this a first-time deploy or an update? First deploys need different verification (initial provisioning, DNS, env setup).
4. Rollback mechanism available? Blue/green, canary, feature flag, full rollback via re-deploy? Affects risk tolerance.
5. Who is the deployer? Single maintainer vs team vs CI/CD automation? Affects what "ship-with-caveats" means.

State these in the first block of the output. Categories that are N/A for this change type should be marked explicitly, not silently skipped.

Steps

Phase 1 — Identify the change surface

1. Branch diff vs main: git diff main...HEAD --stat + file list
2. Uncommitted changes: git status + git diff --stat
3. User-specified feature

Pre-ship considers not just the diff, but the system impact of the diff — env, DB, consumers, monitoring.

Phase 2 — Walk the 7 categories

Work through each. Flag each item ✅ Clear, ⚠️ Needs attention, or ❌ Blocker.

1. Environment & Config

• New env vars documented (.env.example, env.ts schema)?
• New env vars set in production (Vercel, Fly, AWS)?
• New secrets provisioned and rotated into secret manager?
• Config that differs across dev/staging/prod set correctly in each?
• Feature flags gated appropriately, default state safe?

2. Database & Migrations

• New collections / tables / fields / indexes actually created?
• Migration script exists and tested against a copy of real production data?
• Migration is reversible or has a documented rollback?
• Existing records won't break under the new schema?
• Data backfill plan exists, timed, with maintenance window if needed?
• Concurrent-write safety during deploy — old code and new code both work against the new schema during rolling deploy?
• Indexes added before queries that need them?

3. Backwards Compatibility

• Breaks for existing users? (settings reset, saved state, bookmarked URLs)
• API contract changes affecting client, worker, webhooks, Zapier, widgets, public API?
• Shared package version bumped? All consumers updated?
• Old routes redirect or deprecate gracefully, not 404 on day one?
• Browser support unchanged or support matrix updated deliberately?

4. Error & Edge Case Coverage

• What happens when this fails mid-way? Rollback, retry, at-least-once guarantee?
• Errors surfaced to the user with actionable messages, not silently swallowed?
• New failure modes monitored? Does someone get paged at 2am?
• Fallbacks for third-party outages (LLM, email, payments, analytics)?
• Graceful degradation for flaky networks / old browsers / ad blockers?

5. Security

• New endpoints: authenticated? authorized? rate-limited?
• User input reaching DB/filesystem/shell/LLM: validated and sanitized at the boundary?
• New data exposed in API responses that shouldn't be (PII, internal IDs, tokens)?
• CORS headers correct on new public endpoints?
• File uploads: size limits, type checks, storage location?
• New third-party scripts: reviewed for CSP impact?
• Secrets not logged, not in error messages, not in client bundle?

6. Monitoring & Observability

• New critical paths logged with enough context to debug at 2am?
• Key business events emitted as structured logs or metrics?
• Anything that should have a dashboard chart or alert that doesn't?
• Can you answer "is it working?" in production within 60 seconds?
• Error tracking (Sentry) capturing errors from new code paths?
• RUM / performance monitoring in place for user-facing changes?

7. Cleanup

• Feature flags, debug code, console.log, // TODO: remove before ship — all removed?
• Commented-out old code deleted (git has it if needed)?
• Test data / seed data removed from production-facing paths?
• Old files, routes, endpoints, components that are now dead — cleaned or tracked?
• Old analytics events deprecated explicitly?

Phase 3 — Produce the report

# Pre-Ship Check — {{feature name}}

**Scope:** {{N files, + lines, - lines}}
**Target environment:** {{production / staging / canary}}

## Category scores

| # | Category | Status |
|---|---|---|
| 1 | Environment & Config | ✅ / ⚠️ / ❌ |
| 2 | Database & Migrations | |
| 3 | Backwards Compatibility | |
| 4 | Error & Edge Case Coverage | |
| 5 | Security | |
| 6 | Monitoring & Observability | |
| 7 | Cleanup | |

## Findings

### ❌ Blockers (must fix before shipping)
1. [category] [issue] — [path:line] — [concrete fix]

### ⚠️ Warnings (ship-with-caveat OK, fix soon)
...

### ✅ Strengths (optional)
...

## Verdict

**🚀 Safe to ship** / **⚠️ Ship with caveats** / **🛑 Not ready**

**Post-ship follow-ups:**
- [items to track after ship]

Phase 4 — Review-only

Pre-ship does not fix. Exception: user says "fix it and re-check" on a trivial blocker.

Output Format

See Phase 3. Rules:

• Every category gets a row, even ✅ ones. Users need to see you didn't skip any.
• Blockers numbered, cite category, give fix path.
• Verdict is the last line, impossible to miss.
• Post-ship follow-ups required on "Ship with caveats" verdicts.

Rules

1. Walk all 7 categories. If one is N/A for this change type, say so explicitly — do not silently skip.
2. If you don't have context to evaluate a category, ask (interactive mode) or flag as "needs user confirmation" (headless/subagent mode). Do not mark ✅ on assumption.
3. Ship-with-caveats must itemize what's acceptable post-ship vs what's forbidden.
4. Verdict discipline. One of: 🚀 / ⚠️ / 🛑. Not "it depends".
5. Blockers need concrete fixes. "Missing env var" is a finding; "set STRIPE_WEBHOOK_SECRET in Vercel prod via vercel env add" is a fix.
6. Scope to what's shipping. Not the whole codebase.
7. Cleanup section is mandatory. The single most common real issue at deploy time is a leftover debug log or feature flag.
8. Call out deploy timing. If deploying to a live system, flag whether to gate on a low-traffic window.
9. In subagent / headless mode, emit the report and stop. Never "fix while reviewing" in any mode. The calling agent decides next steps.

Worked Example — Output

# Pre-Ship Check — Team invites feature

**Scope:** 14 files, +842 / -63 lines
**Target environment:** production

## Category scores

| # | Category | Status |
|---|---|---|
| 1 | Environment & Config | ⚠️ |
| 2 | Database & Migrations | ❌ |
| 3 | Backwards Compatibility | ✅ |
| 4 | Error & Edge Case Coverage | ✅ |
| 5 | Security | ⚠️ |
| 6 | Monitoring & Observability | ⚠️ |
| 7 | Cleanup | ❌ |

## Findings

### ❌ Blockers (must fix before shipping)

1. **[DB & Migrations]** `migrations/20260412_invites.sql` exists locally but
   not applied to production. Running the new code against the old schema
   will 500 on every invite creation.
   - **Fix:** apply via `pnpm migrate:prod` *before* deploying the code.
     Order: migration first, deploy second.

2. **[Cleanup]** `src/api/invites/create.ts:48` has
   `console.log('INVITE DEBUG', user, inviteData)` — leaks user email
   and invite token to logs.
   - **Fix:** remove the line.

3. **[Cleanup]** `src/components/InviteButton.tsx:12` has feature flag
   `NEXT_PUBLIC_ENABLE_INVITES` but the var is not set in Vercel prod.
   Button will be invisible on first deploy.
   - **Fix:** set env var to `'true'` in Vercel prod, or remove flag wrapper.

### ⚠️ Warnings (ship-with-caveat OK, fix soon)

4. **[Env & Config]** `RESEND_API_KEY` uses staging tier (100/day limit).
   - **Post-ship:** rotate to production Resend key within 24h.

5. **[Security]** Rate limit is 50/hr/user but no per-org limit. Coordinated
   multi-user abuse isn't blocked.
   - **Post-ship:** add per-org daily limit within 1 week.

6. **[Monitoring]** New `invite_sent` event emits but no dashboard chart.
   - **Post-ship:** add chart to growth dashboard within 24h.

### ✅ Strengths

- Migration is reversible (separate `down` SQL).
- All new endpoints authenticated via existing middleware.
- Error handling wraps insert + email in a transaction.

## Verdict

**🛑 Not ready.** Three blockers must be fixed: apply the migration, remove
the debug console.log (PII leak), and handle the feature flag. Estimated fix
time: 15 minutes. After blockers are cleared and warnings 4–6 are tracked as
post-ship follow-ups, this becomes **🚀 Safe to ship** with caveats.

**Post-ship follow-ups to track:**
- Rotate Resend key to production tier (24h)
- Add per-org rate limit (1 week)
- Add growth dashboard chart for invite events (24h)

Pipeline Position

write-plan → plan-review → (implement) → gap-check → simplify → [pre-ship] → (deploy) → pr-triage

Pre-ship is the final gate before deploying. Run after gap-check + simplify have cleaned the code. If pre-ship returns 🛑 Not ready, stop and fix — do not override the gate.