Use this checklist before pushing code and before deploying to production. The goal is to catch the most common causes of post-deploy issues in under five minutes.

​
Pre-push checklist

Run through these before every push, regardless of task size:
1

Check the diff

Review what changed. Look for:
  • Unintended file changes
  • Hardcoded values that should be environment variables
  • Console logs or debug statements left in
  • TODOs that should block shipping
git diff
2

Run the validation suite

Whatever the project uses — tests, lint, type check:
npm run lint
npm run typecheck
npm run test
Do not push with failing checks unless the failure is pre-existing and documented.
3

Verify the done criteria

Return to the scoping document and confirm each done criterion is met. If the criterion is a visible state, confirm it in a local preview.
4

Write the commit message

One line describing what changed and why. Format: type: short description
fix: correct sidebar path bug in quickstart
feat: add project scoping workflow page
refactor: move ai-productivity pages to workflows/

​
Pre-deploy checklist

Run before deploying to a production URL (Vercel, etc.):
1

Build locally

Confirm the production build succeeds with no errors:
npm run build
Build errors that only appear in production (not dev) are usually imports, missing environment variables, or server/client boundary issues.
2

Check environment variables

Confirm all required environment variables are set in the deployment target. Missing env vars surface as runtime errors, not build errors.
3

Verify redirects and URL changes

If any pages were moved or renamed, confirm vercel.json (or equivalent) has redirects in place for the old URLs. Dead links affect SEO and user trust.
4

Preview the deployment

For Vercel: check the preview deployment URL before promoting to production. Walk the key paths — not just the changed pages.

​
Post-deploy verification

After a production deploy:
  • Open the live URL and confirm the changed pages load correctly
  • Check at least one page that was not changed (regression check)
  • Confirm no 404s on paths that existed before the deploy
  • Check the build/deploy logs for warnings that weren’t present before

​
Common causes of post-deploy failures

FailureRoot causePrevention
Page 404Path moved without redirectAdd redirect to vercel.json before deploy
Missing env varAdded in dev, not set in productionDocument env vars in README, check before deploy
Build fails in CI but passes locallyDifferent Node version or package resolutionPin Node version in .nvmrc or engines field
Visual regressionCSS class conflict or missing importPreview deploy before promoting to production
Type error in production buildLoose any types masked in devRun tsc --noEmit locally as part of pre-push

Project Scoping

Define scope and done criteria before starting implementation.