Guides manual staging validation before production deployment through smoke tests, critical user flow testing, data migration verification, and rollback capability checks. Use when validating staging deployments, running pre-production tests, or preparing for production promotion in staging-prod deployment model. (project)
Guides manual staging validation before production deployment through smoke tests, critical user flow testing, data migration verification, and rollback capability checks. Use when validating staging deployments, running pre-production tests, or preparing for production promotion in staging-prod deployment model. (project)
Validate staging deployment before promoting to production through systematic manual testing, automated smoke tests, data migration verification, and rollback capability testing. Ensures production deployments are safe, functional, and meet quality standards.
This skill orchestrates the staging validation phase, which occurs after /ship-staging and before /ship-prod in the staging-prod deployment workflow.
Core responsibilities:
Run automated smoke tests on staging environment
Test critical user flows manually (authentication, core features, payments)
Verify data migrations executed successfully
Test rollback capability (actual rollback + roll-forward)
Document sign-off decision (approve/reject with justification)
<quick_start>
Execute staging validation in 5 steps:
Run smoke tests - Execute automated smoke test suite on staging URL
npm run test:smoke -- --url=$STAGING_URL
Verify: homepage loads (200), API health endpoint (200), database connection
Test critical user flows - Manual testing of core functionality
Authentication (login, logout, password reset)
Primary user workflow (feature-specific)
Before running staging validation:
- [ ] Staging deployment completed successfully (from /ship-staging)
- [ ] Staging URL is live and accessible
- [ ] Deployment ID available (for rollback testing)
- [ ] Previous deployment ID available (for rollback test)
- [ ] Database migration logs available
- [ ] Test credentials available (for authentication flows)
- **Skip at your own risk**: Staging validation is the last quality gate before production. Skipping it risks deploying broken code to users.
- **Insufficient smoke tests**: Testing only homepage is inadequate. Must verify API, database, authentication, core features.
- **Assumed rollback works**: Must actually test rollback, not assume it works. Many rollback failures discovered during tests.
- **Vague sign-off**: "Looks good" is not a documented sign-off. Must update state.yaml with name, timestamp, decision.
**Run Automated Smoke Tests**
**Test Critical User Flows**
**Verify Data Migrations**
**Test Rollback Capability**
**Document Sign-Off Decision**
**Pre-validation checks**:
- [ ] Staging deployment completed (URL live)
- [ ] Deployment IDs available (current and previous)
- [ ] Test credentials available
- [ ] Database migration logs accessible
**Impact**: No accountability, unclear approval state
**Impact**: Rollback fails in production when needed
**Impact**: Deploys known bugs to production
**Impact**: Misses critical bugs, false confidence
**Issue**: Smoke tests failing on staging
**Solution**: Check deployment logs for errors, verify environment variables set, check database connection, re-deploy if necessary
Payment processing (if applicable)
Data CRUD operations
Verify data migrations - Check staging database for migration results
# Connect to staging database
psql $STAGING_DATABASE_URL -c "SELECT version FROM alembic_version;"# Verify tables, columns, constraints match expectations
Test rollback capability - Execute actual rollback test
# Rollback to previous deployment
vercel rollback $PREVIOUS_DEPLOYMENT_ID# Verify previous version is live# Roll forward to current deployment
vercel promote $CURRENT_DEPLOYMENT_ID
Document sign-off - Update state.yaml
manual_gates:staging_validation:status:approved# or rejectedapprover:"Your Name"timestamp:"2025-11-19T10:30:00Z"blockers: [] # or list of issues if rejected
Key principle: Test as if this is production. All failures must be fixed before production deployment.
</quick_start>
<knowledge_requirements>
Required understanding before validation:
Smoke tests: What automated tests exist, how to run them, what they verify
Critical user flows: Which workflows are essential for production (auth, core feature, payments)
Data migrations: What schema changes were made, how to verify them
Rollback procedure: How to rollback deployment, how to verify previous version, how to roll forward
Sign-off criteria: What constitutes approval vs rejection (all tests pass, no blocking bugs)
See deployment-strategy.md in project docs for platform-specific rollback procedures.
</knowledge_requirements>
Execute smoke test suite on staging environment.
Smoke Test Suite:
# Run smoke tests against staging URL
npm run test:smoke -- --url=$STAGING_URL# Typical smoke tests include:# - Homepage loads (HTTP 200, no errors in console)# - API health endpoint responds (GET /api/health → 200)# - Database connection established (health check includes DB ping)# - Static assets load (CSS, JS, images)# - Authentication page accessible (GET /login → 200)
Success Criteria:
All smoke tests pass (0 failures)
No 500 errors in server logs
No console errors in browser DevTools
Response times <2s for all endpoints
If smoke tests fail:
Document failures in validation report
Mark sign-off as "rejected" with blocker list
Return to /implement to fix issues
Re-deploy to staging
Re-run validation
Quality Check: Smoke tests provide quick confidence that deployment is functional, not a comprehensive test.
Manually test essential user journeys on staging.
Authentication Flow:
1. Navigate to staging URL
2. Click "Login" or navigate to /login
3. Enter test credentials (test@example.com / test-password)
4. Verify successful login (redirects to dashboard, user menu shows)
5. Click "Logout"
6. Verify successful logout (redirects to homepage, user menu gone)
7. Test password reset flow (request reset, receive email, change password)
Core Feature Flow (feature-specific):
Example for "Student Progress Dashboard" feature:
1. Login as teacher
2. Navigate to /dashboard
3. Verify student list loads (check for >0 students)
4. Click on student name
5. Verify progress details load (completion rate, lessons, grades)
6. Test filters (by class, by date range)
7. Verify data accuracy (spot-check 3 students against database)
Payment Processing Flow (if applicable):
1. Add item to cart
2. Proceed to checkout
3. Enter test payment credentials (Stripe test mode)
4. Submit payment
5. Verify success confirmation
6. Verify order appears in user account
7. Verify payment recorded in admin panel
Quality Check: Test flows that represent 80% of user activity. Don't test every edge case.
Check that database migrations executed successfully in staging.
Migration Verification:
# Connect to staging database
psql $STAGING_DATABASE_URL# Check migration version
SELECT version FROM alembic_version;
# Expected: Latest migration version (e.g., 4f3a2b1c5d6e)# Verify schema changes
\d+ users# Describe users table# Check for expected columns, constraints, indexes# Verify data migrations
SELECT COUNT(*) FROM users WHERE email_verified IS NOT NULL;
# Check backfill operations completed
Schema Validation:
New tables exist (if migrations added tables)
New columns exist with correct types (if migrations added columns)
Default values applied (if migrations set defaults)
Data integrity maintained (no orphaned records, referential integrity)
Success Criteria:
Migration version matches expected version
All schema changes present in staging database
Data migrations completed (if applicable)
No migration errors in deployment logs
If migrations failed:
Check deployment logs for migration errors
Document failure in validation report
Mark sign-off as "rejected"
Return to /implement to fix migration scripts
Re-deploy to staging (may require manual database cleanup)
Quality Check: Migrations are critical. A failed migration in production is catastrophic.
Execute actual rollback test to verify production safety net.
Rollback Test Procedure:
Step 4a: Identify Previous Deployment:
# For Vercel deployments
vercel list --limit=5
# Find previous production deployment ID# Store IDs
CURRENT_DEPLOYMENT_ID="<current-staging-deployment>"
PREVIOUS_DEPLOYMENT_ID="<previous-production-deployment>"
Step 4b: Execute Rollback:
# Rollback to previous deployment
vercel rollback $PREVIOUS_DEPLOYMENT_ID --yes# Or via CLI:
vercel aliasset$PREVIOUS_DEPLOYMENT_ID <staging-alias>
Step 4c: Verify Previous Version Live:
1. Navigate to staging URL
2. Verify previous version is live (check version number, feature presence)
3. Test critical flow to confirm functionality
4. Document: "Rollback successful, previous version ($PREVIOUS_DEPLOYMENT_ID) is live"
Step 4d: Roll Forward:
# Restore current deployment
vercel aliasset$CURRENT_DEPLOYMENT_ID <staging-alias>
Step 4e: Verify Current Version Restored:
1. Navigate to staging URL
2. Verify current version is live (feature present)
3. Test critical flow to confirm functionality
4. Document: "Roll-forward successful, current version ($CURRENT_DEPLOYMENT_ID) is live"
Mark sign-off as "rejected" with blocker: "Rollback capability not verified"
BLOCK production deployment - DO NOT proceed to /ship-prod
Fix rollback procedure (check deployment IDs, alias configuration, DNS)
Re-test rollback on staging
Quality Check: Rollback capability is the safety net for production. Must work reliably.
Update state.yaml with validation results and approval decision.
Approval Criteria:
Sign-off as "approved" ONLY if:
- All smoke tests pass (0 failures)
- All critical user flows complete without errors
- Data migrations verified successfully
- Rollback test succeeds (rollback + roll-forward verified)
- No blocking bugs found during manual testing
Rejection Criteria:
Sign-off as "rejected" if ANY of:
- Smoke tests fail
- Critical user flows broken (authentication fails, core feature broken)
- Data migrations failed or incomplete
- Rollback test fails
- Blocking bugs found (security issue, data corruption, critical UX bug)
state.yaml Update:
Approval Example:
manual_gates:staging_validation:status:approvedapprover:"Jane Smith"timestamp:"2025-11-19T14:30:00Z"validation_summary:smoke_tests:"All passed (8/8)"critical_flows:"All verified (authentication, dashboard, payments)"migrations:"Version 4f3a2b verified, schema changes confirmed"rollback_test:"Successful (rollback to dpl_abc123, roll-forward to dpl_xyz789)"blockers: []
Rejection Example:
manual_gates:staging_validation:status:rejectedapprover:"Jane Smith"timestamp:"2025-11-19T14:30:00Z"validation_summary:smoke_tests:"1 failure (API health endpoint returned 503)"critical_flows:"Authentication broken (login redirects to 404)"migrations:"Verified"rollback_test:"Not attempted (smoke tests failed)"blockers:-"API health endpoint failing (503 error)"-"Login flow broken (404 on redirect)"
Next Steps After Sign-Off:
If approved → Run /ship-prod to deploy to production
If rejected → Return to /implement, fix blockers, re-deploy to staging, re-run validation
Quality Check: Sign-off must be explicit, documented, and traceable. No verbal approvals.
Tester: "Rollback should work, Vercel has rollback feature"
Reality: Rollback deployed but DNS not updated, or deployment ID incorrect, or database migration not reversible
Result: Production incident, attempted rollback fails, extended downtime
Prevention:
Always test rollback on staging before production deployment
Execute actual rollback (change alias/DNS)
Verify previous version is live
Test roll-forward to confirm current version restored
Document rollback + roll-forward success
Good Practice:
# Actual rollback test
vercel rollback $PREVIOUS_ID# Verify previous version live (manual test)
vercel aliasset$CURRENT_ID staging
# Verify current version restored (manual test)
Scenario:
Tester: "Login is broken but we'll fix it in a hotfix"
Result: Production users cannot login, support tickets spike, revenue impacted
Prevention:
Mark validation as "rejected" for any blocking bug
<critical_flow_checklist>
When to use: Every staging validation
Approach:
Identify 3-5 critical user flows (authentication, core feature, payments)
Create checklist for each flow
Test each flow manually on staging
Document results in validation summary
Benefits:
Ensures essential functionality works before production
Catches UX bugs that automated tests miss
Provides structured testing approach (no guessing)
Example Checklist:
Authentication Flow:
- [ ] Login with valid credentials succeeds
- [ ] Login with invalid credentials fails (shows error)
- [ ] Logout succeeds (session cleared)
- [ ] Password reset email sent
- [ ] Password reset link works
- [ ] New password accepted
</critical_flow_checklist>
<rollback_test_discipline>
When to use: Every staging validation (non-negotiable)
Approach:
Identify previous production deployment ID
Execute rollback to previous deployment
Verify previous version is live (manual test)
Execute roll-forward to current deployment
Verify current version restored (manual test)
Document rollback + roll-forward success
Benefits:
Verifies safety net works before production deployment
Builds muscle memory for production rollback procedure
Identifies rollback issues in safe environment (staging)
Example:
# Rollback test
PREVIOUS_ID=$(vercel list --limit=5 | grep production | head -1 | awk '{print $1}')
vercel rollback $PREVIOUS_ID# Manual verification: Navigate to staging, confirm previous version live
vercel aliasset$CURRENT_ID staging
# Manual verification: Navigate to staging, confirm current version live
All critical user flows verified (authentication, core feature, payments)
Data migrations verified (schema + data correct)
Rollback test succeeds (rollback + roll-forward verified)
Sign-off documented in state.yaml (approver, timestamp, validation summary)
Decision is "approved" (ready for production) OR "rejected" (blockers documented, return to implement)
Ready to proceed when:
If approved → Run /ship-prod to deploy to production
If rejected → Return to /implement, fix blockers, re-deploy to staging, re-run validation
</success_criteria>
Issue: Critical user flow broken (authentication, core feature)
Solution: Mark validation as "rejected", document blocker, return to /implement to fix, re-deploy to staging, re-validate
Issue: Data migrations not showing in staging database
Solution: Check deployment logs for migration errors, verify migration scripts syntax, manually run migrations on staging if needed
Issue: Rollback test fails (previous version not live)
Solution: Verify deployment IDs correct, check alias/DNS configuration, test rollback procedure manually, update deployment scripts if needed
Issue: Unclear what to test (no critical flows documented)
Solution: Review spec.md for feature requirements, identify essential user workflows (authentication always critical), create flow checklist, document for future validations
Issue: Validation taking >90 minutes (too long)
Solution: Focus on critical flows only (don't test every edge case), automate smoke tests (don't test manually), parallelize testing where possible, skip exhaustive testing (save for QA phase)
