Upgrade Checklists
Required work for transitioning between stages and stacks.
Overview
These checklists define the minimum work required to safely transition between project stages or technical stacks. Skipping items creates technical debt and risks.
How to Use
Before starting an upgrade, review the entry criteria. Complete all work items. Watch for anti-patterns that indicate you're cutting corners.
Stage Transitions
POC → MVP
Entry Criteria
- ☐ POC validated with stakeholders
- ☐ Core assumptions proven
- ☐ Intent Gate passed
- ☐ Scope defined for MVP
Anti-Patterns
- ⚠ Keeping mock data 'temporarily'
- ⚠ Skipping auth because 'it's internal'
- ⚠ No error handling on critical paths
- ⚠ Hardcoded configuration values
Required Work Items
- ☐ Replace mock data with real database
- ☐ Implement user authentication
- ☐ Add proper error handling
- ☐ Implement core happy-path tests
- ☐ Set up proper environment configuration
- ☐ Add basic logging
- ☐ Review and fix security basics
- ☐ Update State of Play document
MVP → MMP
Entry Criteria
- ☐ MVP features complete and tested
- ☐ Early user feedback incorporated
- ☐ Build Gate passed
- ☐ Performance baseline established
Anti-Patterns
- ⚠ Launching without load testing
- ⚠ Ignoring accessibility
- ⚠ No user documentation
- ⚠ Missing support processes
Required Work Items
- ☐ UI/UX polish and consistency pass
- ☐ Comprehensive error handling
- ☐ Edge case handling
- ☐ Performance optimisation
- ☐ Security review and fixes
- ☐ Accessibility audit
- ☐ Documentation for users
- ☐ Support escalation path defined
MMP → PROD
Entry Criteria
- ☐ MMP features stable
- ☐ Performance testing complete
- ☐ Security review passed
- ☐ Release Gate criteria reviewed
Anti-Patterns
- ⚠ No monitoring in production
- ⚠ Untested backup/recovery
- ⚠ No incident response plan
- ⚠ Missing operational runbook
Required Work Items
- ☐ Monitoring and alerting configured
- ☐ Backup and recovery tested
- ☐ Incident response process documented
- ☐ Runbook created for operations
- ☐ SLA defined and achievable
- ☐ On-call/support rotation established
- ☐ Disaster recovery plan documented
- ☐ Final security sign-off
Stack Transitions
Stack A → B (Add Supabase)
Entry Criteria
- ☐ POC validated
- ☐ Need for auth or data persistence confirmed
- ☐ Supabase is appropriate (not needing Stack C)
Anti-Patterns
- ⚠ No row-level security on tables
- ⚠ Exposing service role key to client
- ⚠ Skipping database design
- ⚠ No testing of auth flow
Required Work Items
- ☐ Create Supabase project
- ☐ Add environment variables to .env.local
- ☐ Install @supabase/supabase-js and @supabase/ssr
- ☐ Create lib/supabase/ with client utilities
- ☐ Design database schema
- ☐ Implement row-level security policies
- ☐ Migrate mock data to database
- ☐ Implement authentication flow
- ☐ Update API calls to use Supabase
- ☐ Test auth flow end-to-end
Stack A → C (Add Laravel)
Entry Criteria
- ☐ POC validated
- ☐ Complex backend requirements confirmed
- ☐ Laravel expertise available
- ☐ Supabase would not be sufficient
Anti-Patterns
- ⚠ No API contract documentation
- ⚠ CORS misconfiguration
- ⚠ No API versioning
- ⚠ Mixing auth strategies
Required Work Items
- ☐ Set up Laravel project (separate repo or monorepo)
- ☐ Define API contract (OpenAPI recommended)
- ☐ Add NEXT_PUBLIC_API_URL environment variable
- ☐ Create lib/api/ with API client utilities
- ☐ Implement Laravel Sanctum for auth
- ☐ Set up CORS configuration
- ☐ Implement API versioning strategy
- ☐ Create database migrations
- ☐ Implement API endpoints
- ☐ Connect Next.js to Laravel API
- ☐ Test auth flow end-to-end
Quick Reference
Common upgrade paths and approximate effort:
POC → MVP2-3 days
MVP → MMP1-2 weeks
MMP → PROD1 week
A → B1-2 days
A → C3-5 days
Estimates assume experienced team. Actual effort varies by project complexity.
Next Steps
See Workflow for the day-to-day delivery process, and Helpers & Templates for prompts and templates to support transitions.