What happened
The Choco web application (cho.co / choco.dev) — the public-facing factory tour, documentation site, and Golden Ticket display — was scaffolded as a full Next.js application. 64 files, 21 pages, all building and ready for Vercel deployment. After shipping the scaffold, we realigned 10 GitHub issues across two repositories to reflect what’s been built and what remains. One issue was closed as complete. Seven were significantly expanded with concrete specifications.Business impact
Before this session: The cho-co repo had only Go backend code. Visiting the web URL would show nothing (Vercel 404). The backlog had vague issues like “Implement Golden Ticket counter” with 3 bullet-point acceptance criteria. After this session: The web app exists with 21 working pages covering the factory tour, documentation, Golden Ticket display, search, dashboard, and authentication. The backlog has detailed specifications — cho-co#5 (onboarding events) went from a one-paragraph description to a complete mapping of 17 events with their trigger points, data payloads, and downstream reactions. This means the next developer (or AI agent) picking up any of these issues has a precise specification to work against, not a vague prompt requiring interpretation.Operational takeaways
Scaffold-first, then specify
The most productive pattern was: build the scaffold first, then return to expand the issue specifications. Before the scaffold existed, issue #5 could only say “17 events across 4 domains.” After the scaffold, we could write “thetour.started event fires from tour-wizard.tsx when the component mounts, with payload { step: 1, entry_point: string }.” Concrete component paths make acceptance criteria testable.
Conditional auth is essential for early-stage projects
The web app uses Clerk for authentication, but Clerk requires API keys to build. The scaffold uses a conditional pattern: if the key is present, auth works; if not, the app builds and runs without it. This means we can deploy to Vercel immediately without configuring Clerk, and activate auth later by adding one environment variable. No code changes needed.Issue expansion multiplied scope visibility
| Issue | Before | After |
|---|---|---|
| Golden Ticket counter (#3) | 3 acceptance criteria | 11 acceptance criteria |
| Hall of Fame (#4) | 3 acceptance criteria | 12 acceptance criteria |
| Onboarding events (#5) | 1 paragraph | 17 event mappings + 6 consumption reactions |
| Oompa annotations (#16) | 4 acceptance criteria | 11 acceptance criteria |
Current state
- cho-co repo: 1 issue closed (scaffold), 3 open with expanded specs (ticket counter, hall of fame, onboarding events), 1 epic updated
- choco-hq repo: 5 issues updated with scaffold progress and expanded remaining work (annotations, songs, SVG expressions, onboarding, master epic)
- Deployment: Scaffold committed and pushed. Vercel deployment ready once domain is configured.
Action items
- Configure Vercel deployment for cho-co repo (point at
web/root directory) - Set
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYin Vercel when Clerk app is provisioned - Begin cho-co#3 (Golden Ticket counter API integration) — first issue with scaffold + expanded spec ready
- Consider extracting Oompa SVG components to
choco-ui-kitpackage for cross-repo reuse (tracked in choco-hq#18)