Fast product prototype previews

# Fast product prototype previews

Kevin needs a product-spec-to-clickable-preview workflow that lets him iterate with Brian quickly without creating production-grade AWS environments for every small prototype change.

## Problem

The current PR preview path is too slow for product iteration. It creates an App Runner preview backed by a shared RDS schema, restores a production dump, runs migrations, builds/pushes Docker, applies Terraform, waits for App Runner, then runs smoke checks. That is useful for production-like QA, but not for Kevin's "see it, feel it, tweak the spec, rebuild" loop.

Kevin's target loop is closer to 30 seconds. The current loop is commonly 5-10+ minutes per meaningful update.

## Current engineering status

- `yawp-2.0` PR #136 (`codex/kevin-preview-workflow`) exists and is draft.
- PR #136 adds:
  - `/preview` and `/preview destroy` PR comment triggers.
  - Manual workflow dispatch by PR number.
  - Stable Product Lab environment IDs keyed by a product lab slug.
  - Runbook docs for spec-to-preview workflow.
- PR #136 currently has CI green except the preview deploy check. The failed step is `Create PR schema, restore dump, and migrate`.
- `yawp-2.0` PR #139 (`codex/product-lab-build-out`) is the more advanced Product Lab direction. It is green and blocked on Bryant approval before the first non-production Product Lab run.
- `yawp-2.0` PR #140 (`codex/preview-forge`) merged on 2026-05-25. It proved a live HTTPS preview at `https://pr-140.preview.yawp.school` during the PR run, green CI, and a latest reported preview-deploy healthcheck of 36247ms, with the full preview-deploy job completing in 50s.

May 26 call update:

- The round-two preview setup is fast enough to be useful for Kevin's prototype loop.
- The active blocker is seed parity: the new fast preview data does not yet match the old preview seed closely enough, causing login and review issues.
- Codespaces was discussed and is not the preferred near-term path. The preferred loop is cloud-agent work plus sub-60-second PR previews.
- Preview status should feed the central PM/status system so Kevin can see what is ready to review without opening engineering tools.

## Requirements

- Kevin can start from a product spec and get a clickable preview without becoming a full-time engineer.
- Preview updates should be fast enough for live iteration with Brian when changes are UI/prototype-heavy.
- Full-stack behavior must still be available when the prototype touches DB, background jobs, auth, submissions, grading, or AI calls.
- Production data must not be mutated.
- Preview data should be isolated per PR/prototype/initiative.
- The workflow should leave durable artifacts: preview URL, branch/source, database/checkpoint identity, and QA/proof notes.
- It should not create long-lived AWS clutter by default.
- Seeded preview users, classes, feature flags, and demo schools must match the expected review accounts.

## Options to evaluate

### Option A: Stabilize Product Lab / App Runner previews

Use the current AWS App Runner + RDS schema approach, but make it easier to trigger, preserve, and resume.

Pros:
- Closest to production.
- Already mostly built.
- Handles full stack, database, auth, background jobs, AI, and production-shaped data.

Cons:
- Too slow for 30-second product iteration.
- Terraform/App Runner/Docker push dominate the loop.
- Better as an acceptance/demo environment than a sketchpad.

Best use: Brian demo, pre-engineering validation, and high-confidence QA.

### Option B: Fast UI lab on Vercel/Netlify

Deploy a preview shell for UI/product prototypes, backed by fixtures or mocked APIs.

Pros:
- Likely fastest path to 30-second preview updates.
- Great for layout, flow, copy, and interaction questions.
- Lower infrastructure overhead.

Cons:
- Not full-stack unless we invest in mocked services or remote API adapters.
- Can lie about database/background-job behavior.
- Needs clear labeling so nobody treats it as production-grade QA.

Best use: Kevin/Brian iteration on screens and workflows before engineering hardening.

### Option C: Full-stack container lab per prototype

Package the app, Postgres, worker/background services, and seed/checkpoint data into Docker Compose or a lightweight remote container host.

Pros:
- Full-stack isolation with real Postgres.
- Can be much faster than App Runner after the first build if image layers/cache are warm.
- Gives Kevin a stable URL per prototype without production AWS deploy semantics.

Cons:
- Requires building/operating the container runner.
- Needs a decision on hosting: EC2, ECS, Fly.io, Railway, Render, or similar.
- Database snapshots/checkpoints need careful lifecycle rules.

Best use: realistic product prototypes that need DB/auth/jobs but not production-like App Runner.

### Option D: Codespaces as Kevin's lab

Let Kevin run the app in a managed dev environment with Claude Code and port forwarding.

Pros:
- Fastest path to self-serve engineering-like iteration.
- Minimal platform buildout.
- Good if Kevin is willing to operate closer to the code.

Cons:
- Pushes Kevin toward being a developer.
- Port forwarding/auth/dev data can become confusing.
- Harder for Brian to review if previews are not stable public URLs.

Best use: Kevin-in-the-loop prototyping, not Brian-facing review by default.

## Recommendation to test first

Use a two-lane system:

1. **Fast Lab** for product iteration.
   Vercel/Netlify or a lightweight container host, with fixture-backed or checkpoint-backed data. Goal: sub-60-second rebuilds for UI-heavy changes.

2. **Product Lab** for full-stack validation.
   Keep the App Runner/Product Lab direction for the moment a prototype needs Brian signoff, real data shape, migrations, jobs, or pilot readiness.

This avoids forcing one environment to be both instant and production-like. It also matches the product workflow: sketch fast, validate seriously.

## Open questions

- [ ] Bryant: Is the first Fast Lab allowed to use mocked/fixture data, or must it use a real Postgres snapshot from day one?
- [ ] Bryant: Should Fast Lab live in `yawp-2.0` or in a separate prototype shell repo?
- [ ] Bryant: Is merged Preview Forge acceptable as the first Fast Lab lane at sub-60 seconds, or should the next slice add cached dev-runtime work toward the 30-second target?
- [ ] Bryant: Should PR #136 be closed/superseded by PR #139, or repaired as a simpler bridge?
- [ ] Bryant: Which exact seed fixture should fast previews use so Kevin can log in and review with production-like classes?
- [ ] Kevin: How much code/dev-environment exposure is acceptable if the payoff is faster iteration?

## Test plan

- Measure current App Runner PR preview timing by step.
- Add preview seed smoke: seeded teacher can log in, has classes, and can create/open assignments.
- Prototype one UI-only Fast Lab deployment and record edit-to-preview timing.
- Prototype one full-stack container lab with Postgres and seed/checkpoint data; record cold-start and warm-update timing.
- Compare Kevin's workflow: spec update, preview update, Brian review link, proof capture.

## Rollout

Start with one Daily Pages or assignment-level-insights prototype. Do not use production resources for the first Fast Lab. Keep App Runner/Product Lab as the acceptance gate until Fast Lab proves reliable.

## Engineering handoff checklist

- [x] Domain context covered
- [x] File paths in `yawp-2.0` listed at a workflow level
- [x] Data model implications called out
- [x] UX sketch in prose
- [x] Edge cases enumerated
- [x] Test plan written
- [x] Rollout plan decided