Why Full Stack Developers Explain Automation Script Aloud

WITHOUT EXPLAINING ALOUD:

You skim the deploy script:

  #!/bin/bash
  set -e
  npm ci
  npm run build
  npx prisma migrate deploy
  pm2 restart api
  echo "deployed"

Your brain fills in the gaps:
"Looks fine. It installs, builds, migrates,
restarts, and confirms."

You run it on a Friday.

Two hours later:
- The migration dropped a column that the
  old API still reads, so every request
  returns 500
- pm2 restart failed silently because the
  process name was wrong, so the old code
  is still running
- There's no health check, so the script
  reported "deployed" while the app was
  down
- There's no rollback, so the team has to
  manually revert the migration

Why it failed:
❌ Skimming hides the destructive migration
❌ Skimming hides the wrong pm2 name
❌ Skimming hides the missing health check
❌ Skimming hides the missing rollback

WITH EXPLAINING ALOUD:

You read the same script out loud:

"It installs dependencies with npm ci, builds
with npm run build, runs prisma migrate
deploy, restarts api with pm2, and echoes
'deployed'.

Wait — prisma migrate deploy. What does the
migration do? If it drops a column that the
old API reads, the app breaks during the
window between migrate and restart. I need a
backward-compatible migration, or a
maintenance window.

And pm2 restart api — is the process name
actually 'api'? If it's 'api-server' or
'myapp', pm2 fails silently. I need to
verify the process name, and I need
set -e to actually stop on the failure.

And there's no health check after the
restart. The script echoes 'deployed' even if
the app is returning 500s. I need a curl
/healthz check with a retry loop.

And there's no rollback. If the health check
fails, the script just stops. I need to
restore the previous build and re-run the
migration down (or a snapshot restore).

And the build: is NODE_ENV=production set?
If not, the build is a dev build with source
maps. I need the env var before npm run build.

The script should be: install, set NODE_ENV,
build, backward-compatible migration,
restart with verified process name, health
check with retries, and a rollback on
failure."

CI SCRIPT — READ ALOUD:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

WHAT YOU SAY ALOUD:
"On every push and PR, it spins up Postgres
15, checks out the repo, runs npm ci, lint,
test, and build.

What breaks?
- The Postgres service is up, but is the
  DATABASE_URL set for the test step? If
  not, the tests fail with a connection
  error. I need the env var.
- npm test — does it wait for Postgres to
  be ready? Services take a few seconds to
  accept connections. I need a healthcheck
  or a wait-for-postgres step.
- The test step has no coverage gate. A PR
  that drops coverage from 80% to 40%
  still passes. I need a threshold.
- The build step runs, but is it cached?
  Without a cache, every build re-downloads
  node_modules. I need actions/cache.
- There's no artifact upload. If a later
  job needs the build, it has to rebuild.
  I need upload-artifact.
- And there's no timeout. If the tests
  hang, the job runs for 6 hours. I need
  timeout-minutes.

The pipeline should be: Postgres with
healthcheck, DATABASE_URL, wait-for-postgres,
npm ci with cache, lint, test with coverage
gate, build, upload artifact, and a timeout."

WHAT IT CATCHES:
✅ Missing DATABASE_URL
✅ Missing wait-for-postgres
✅ Missing coverage gate
✅ Missing cache
✅ Missing artifact
✅ Missing timeout

DB MIGRATION — READ ALOUD:

-- migrations/20260828_add_status.sql
ALTER TABLE orders ADD COLUMN status TEXT;
UPDATE orders SET status = 'completed';
ALTER TABLE orders ALTER COLUMN status SET NOT NULL;

WHAT YOU SAY ALOUD:
"The migration adds a status column, sets
every existing row to 'completed', and then
makes the column NOT NULL.

What breaks?
- The UPDATE sets every row to 'completed',
  including cancelled and refunded orders.
  That's data corruption. I need a backfill
  that reads the existing state, or a
  default + a separate backfill job.
- The NOT NULL constraint locks the table
  while it validates every row. On a 10M-
  row table, that's minutes of downtime.
  I need to add the constraint NOT VALID,
  backfill, then VALIDATE CONSTRAINT.
- The migration isn't backward-compatible
  with the old app. If the old app writes
  a row without status, the NOT NULL
  fails. I need a two-phase deploy:
  add nullable, deploy new code, backfill,
  add NOT NULL.
- And there's no rollback. If the migration
  fails halfway, the column exists but is
  partially backfilled. I need an idempotent
  migration and a down migration.

The migration should be: add nullable with
a default, backfill in batches, add NOT NULL
NOT VALID, validate, deploy new code, then
drop the default in a later migration."

WHAT IT CATCHES:
✅ Data corruption (cancelled → completed)
✅ Table lock from NOT NULL
✅ Backward incompatibility
✅ Missing rollback
✅ Non-idempotent migration

DEPLOY SCRIPT — READ ALOUD:

#!/bin/bash
set -e
git pull origin main
npm ci
npm run build
npx prisma migrate deploy
pm2 restart api
curl -f http://localhost:3000/healthz
echo "deployed"

WHAT YOU SAY ALOUD:
"It pulls main, installs, builds, migrates,
restarts pm2, and curls the health endpoint.

What breaks?
- git pull on the server. If someone
  pushed a bad commit, the server pulls
  it. There's no review, no CI, no tag.
  I need to deploy a tagged, CI-verified
  build, not raw main.
- The build runs on the server. That's
  slower than building in CI and
  downloading the artifact. I should build
  in CI and scp the artifact.
- prisma migrate deploy — if the migration
  is destructive, the app breaks. I need
  a migration review, a backup, and a
  rollback plan.
- pm2 restart api — if the process name is
  wrong, pm2 fails, but the script already
  ran migrate. Now the DB is migrated and
  the app is old. That's a broken window.
  I need to verify the process name.
- curl -f /healthz — if it fails, the script
  exits, but there's no rollback. The DB is
  migrated and the app is down. I need a
  rollback: restore the previous build and
  re-run the down migration.
- And the health check: does it check the
  DB connection? If /healthz only checks
  that the server is up, a broken DB
  connection still passes. I need a
  /readyz that checks DB and cache.

The script should be: deploy a CI-verified
tag, run a backward-compatible migration,
verify the pm2 name, check /readyz (DB +
cache), and roll back on failure."

WHAT IT CATCHES:
✅ Pulling raw main
✅ Building on the server
✅ Destructive migration
✅ Silent pm2 failure
✅ Missing rollback
✅ Weak health check

SEED SCRIPT — READ ALOUD:

#!/bin/bash
npx prisma db push --force-reset
npx prisma db seed
npm run test:e2e

WHAT YOU SAY ALOUD:
"It force-resets the DB, seeds it, and
runs e2e tests.

What breaks?
- --force-reset drops the entire database.
  If DATABASE_URL points to staging or
  production, the script wipes it. I need
  an env guard: refuse to run unless
  NODE_ENV=test.
- db push is a schema sync, not a
  migration. It skips migration history,
  so a later migrate deploy will fail.
  I should use migrate reset, which
  replays migrations and keeps history.
- The seed is not idempotent. If it runs
  twice, it creates duplicate rows. I
  need upserts, not inserts.
- The e2e tests run against the seeded DB.
  If a test mutates the data, later tests
  fail. I need a per-test transaction or
  a reset between tests.
- And there's no cleanup. After the run,
  the DB is left in a seeded state. That's
  fine for local, but bad for CI caching.
  I need a cleanup step.

The script should be: refuse to run unless
NODE_ENV=test, use migrate reset, idempotent
upserts, per-test transactions, and a
cleanup step."

WHAT IT CATCHES:
✅ Missing env guard
✅ db push vs migrate
✅ Non-idempotent seed
✅ Shared DB state across tests
✅ Missing cleanup

Explain-Aloud Automation Checklist:

BEFORE RUNNING:
☐ Say each step aloud
☐ Say the blast radius aloud
☐ Say the rollback plan aloud
☐ Say the env guard aloud
☐ Say what's NOT in the script (backups, canary)

DURING REVIEW:
☐ Explain the script to a teammate aloud
☐ Say what breaks at each step
☐ Say the destructive commands aloud
☐ Say the process names and ports aloud
☐ Say the permissions and secrets aloud

AFTER RUNNING:
☐ Say what changed in production
☐ Say the health check and smoke test aloud
☐ Say the alerts you'll watch
☐ Write a one-paragraph "what I explained" note
☐ Share the note in the PR

Why this works:
- Speaking slows you down
- Saying "migrate" catches the destructive step
- Saying "restart" catches the wrong process name
- Saying "healthz" catches the weak check
- Saying "rollback" catches the missing plan

30-DAY HABIT PLAN:

Week 1 — CI scripts only
☐ Read every CI workflow aloud
☐ Say each step (install, lint, test, build)
☐ Say the DB readiness and env vars aloud
☐ Say the coverage gate and artifact aloud

Week 2 — Add deploy scripts
☐ Read every deploy script aloud
☐ Say the migration and rollback aloud
☐ Say the process name and port aloud
☐ Say the health check and ready check aloud

Week 3 — Add data scripts
☐ Read every seed and migration script aloud
☐ Say the env guard and idempotency aloud
☐ Say the destructive commands aloud
☐ Say the blast radius aloud

Week 4 — Make it routine
☐ Add "explained aloud" to your PR template
☐ Pair with a teammate weekly
☐ Practice explaining a deploy in a mock interview
☐ Write a short note after each deploy

Signs it's working:
✅ You catch a destructive migration before deploy
✅ You catch a wrong process name
✅ You catch a weak health check
✅ You catch a missing env guard
✅ Deploys are calmer
✅ Interviews feel easier