hol-run-lab

name	hol-run-lab
description	Validate a HOL lab by simulating a participant. Walks through all 5 Acts (Explore, Fix, Spec, Build, Show & Tell) and produces a validation report with pass/fail, timing, and facilitator recommendations.

HOL Lab Validator

You are simulating a workshop participant to validate that a HOL lab works end-to-end. Walk through all 5 Acts as if you were seeing the codebase for the first time. Be honest about what's confusing, what's too easy, and what doesn't work.

Important Rules

1. Do NOT read .hol/bugs/answers.md until AFTER you've attempted Act 2. The whole point is to validate that the bugs are discoverable without the answer key.
2. Time your work mentally — note when each act starts and roughly how long it takes you. Human participants will take 2-3x longer.
3. Be critical — if something is confusing, broken, or too easy, say so. A failed validation now saves 20 frustrated participants later.

Act 1 — Explore (Target: 10 min for humans)

Simulate a cold start. You've never seen this repo before.

1. Read CLAUDE.md — is it clear enough to get started?
2. Install and run:

   uv sync
   uv run python seed.py
   uv run pytest
   uv run uvicorn main:app --reload
   

3. Open the web UI at http://localhost:8000 — switch the "Browsing as" persona dropdown, click an itinerary card, change cabin types in the detail view, click "My Account". Confirm the three views (Browse / Detail / Profile) all render.
4. Explore the codebase — map the architecture (note the static frontend under web/), understand the domain.
5. Trace one main data flow (e.g., "how does a booking get created?")
6. Hit a few API endpoints (/docs, /itineraries/, /guests/) to confirm the data behind the UI.

Evaluate:

• Can a participant understand the app's purpose in under 5 min?
• Does the app start without errors?
• Does the web UI at / load and render seeded itineraries?
• Does the persona switcher populate from /guests/ and update the view on change?
• Are all three views (Browse / Detail / Profile) reachable from the nav?
• Is the seed data visible via API?
• Are the file names and structure intuitive?
• Is the CLAUDE.md helpful without being a spoiler?

Act 2 — Fix (Target: 20 min for humans)

Find and fix the planted bugs WITHOUT reading the answer keys.

1. Run pytest and examine the failures
2. Cross-check in the UI: with uvicorn running, switch the persona dropdown to a Gold-tier guest (e.g. "Sarah Chen — Gold"), open any itinerary. The price card shows the bug as "Gold loyalty discount: −5%" (should be −10%). Confirm Platinum still shows −15%. This visual surfacing is the lab's strongest "aha" moment — note whether it lands.
3. For each failing test:
   • Read the test to understand what it expects
   • Trace the failure through the codebase (router → service → model → schema)
   • Identify the root cause
   • Apply the fix
   • Write a regression test
4. Run pytest — all tests should pass after fixes
5. Reload the detail view in the browser and confirm the Gold price card now shows −10%

Evaluate:

• Are test failure messages clear enough to start debugging?
• Is the bug also visible in the UI (not just pytest output)?
• Is the diagnosis path logical (symptoms lead toward the cause)?
• Is the "aha" moment satisfying?
• Is the bug subtle enough to require real debugging (not obvious from reading one file)?
• Is it fair (no domain expertise required, just code tracing)?
• Can a meaningful regression test be written?
• Does fixing the bug update the UI's discount line correctly on reload?

After fixing: Now read .hol/bugs/answers.md and compare:

• Did you find the same root cause?
• Was your fix the same or equivalent?
• How long did it take vs the 20-min target?

Act 3 — Spec (Target: 20 min for humans)

1. Read .hol/features/proposals.md
2. Pick the recommended feature (or any feature)
3. Read the feature brief (the 1-2 sentence description)
4. Fill out .hol/templates/feature-spec.md for the chosen feature
5. Save the spec to .hol/validation/feature-spec-filled.md

Evaluate:

• Is the feature brief clear enough to spec from?
• Does the spec template guide without over-constraining?
• Can you identify the affected files and design decisions?
• Are there real edge cases to consider?

Act 4 — Build (Target: 30 min for humans)

Implement the feature from your spec.

UI integration note — only if you chose Personalized Recommendations:

The frontend already has a "Personalized for you" panel on the itinerary detail view that calls GET /itineraries/{id}/recommendations?guest_id={id} and currently shows "Coming soon" because the endpoint 404s. When your endpoint exists and returns 200, the panel auto-populates. The panel reads these exact keys per recommendation:

• itinerary_id — the trip to link to (clicks call openItinerary(itinerary_id))
• name
• ship_name
• base_price
• reason — short string explaining why this was recommended

.hol/features/proposals.md Proposal 1 also documents this contract. If your endpoint returns the raw ItineraryResponse + relevance_score shape, the cards will render blank (field names won't match). Either shape your response to the panel's contract or update the panel — but pick one explicitly.

1. Create the implementation: new/modified service functions, router endpoints, models if needed
2. Write tests for the new feature
3. Run the full test suite — everything should pass
4. Verify the feature works via API and (if Personalized Recommendations) confirm the UI panel populates with non-empty cards on the detail view

Evaluate:

• Is the feature buildable in ~30 min (estimated for a human with Claude Code)?
• Does it touch multiple layers as promised?
• Is the result demo-able (clear before/after)?
• If Personalized Recommendations: do the panel cards render with name / ship / price / reason populated, and do clicks navigate correctly?
• Did any unexpected complications arise?

Act 5 — Report

Generate a validation report at .hol/validation/report.md:

# Lab Validation Report — {App Name}

Date: {today}

## Summary

- Overall: PASS / FAIL / PASS WITH NOTES
- Lab is ready for: {audience} participants

## Act-by-Act Results

### Act 1 — Explore

- Status: PASS / FAIL
- Notes: {observations}
- Estimated human time: {X} min (target: 10 min)

### Act 2 — Fix

- Status: PASS / FAIL
- Bugs found: {N} / {N total}
- Diagnosis quality: {GOOD / FAIR / POOR — explain}
- Notes: {observations}
- Estimated human time: {X} min (target: 20 min)

### Act 3 — Spec

- Status: PASS / FAIL
- Notes: {observations}
- Estimated human time: {X} min (target: 20 min)

### Act 4 — Build

- Status: PASS / FAIL
- Feature built: {name}
- Complications: {any}
- Estimated human time: {X} min (target: 30 min)

## Issues Found

1. {issue — severity — recommendation}
2. ...

## Facilitator Recommendations

- {recommendation 1}
- {recommendation 2}
- ...

## Verdict

{Final assessment: is this lab ready for a live workshop?}

Undo all your changes after generating the report (the lab should be left in its "bugged" state for participants):

git checkout -- .

Keep only the validation report:

git checkout HEAD -- .hol/validation/