workshop-builder

---
name: workshop-builder
description: Plan and set up a paper-free, live-data workshop end to end — first a discovery session that pins the objective and recommends a workshop type (UX research workshops first, business workshops second), then a grill for the mandatory details (duration, attendees, venue, backend, consent), a plan the user confirms, and only then the build — digital data collection (Google Forms through the facilitator's own Google auth, or kit-rendered static forms with Supabase), a QR landing page, a projector page with live tallies, a print fallback — followed by the run-day protocol and the synthesis into findings and a report. Use when someone says "plan a workshop", "set up a workshop", "digitize my workshop", "paper-free workshop", "workshop forms", "live workshop display", "run the workshop", "synthesize the workshop", "requirements workshop", "feedback retro", "co-design session", "usability session", or asks how to collect answers from a room of participants and show them live.
argument-hint: [define | build <slug> | run <slug> | synthesize <slug>]
---

# Workshop builder

Turns "we should run a workshop" into a workshop that runs itself on the data side: every answer is
captured under an anonymous code the moment it is given, the projector shows the room its own
results when the facilitator chooses, and the synthesis starts from clean tallies instead of
photographed sticky notes. The method comes from running requirements workshops with lecturers;
the kit generalizes it to any room.

Six stages, each with a gate. Never skip a gate: a workshop built on an unconfirmed plan wastes
the one hour the participants gave you.

| # | Stage | Gate to pass |
|---|---|---|
| 1 | **Discover** — objective, audience, decision it feeds; recommend a workshop type | User picks a type |
| 2 | **Grill** — every mandatory detail, checkpointed as you go | Checklist complete (answered or explicitly defaulted) |
| 3 | **Confirm** — plan.md + workshop.json, validated, summarized | User says "confirmed" |
| 4 | **Build** — backend setup, site, forms, QRs, print pack, rehearsal | Rehearsal passed, cutoff set |
| 5 | **Run** — day-of protocol with live display | Forms closed |
| 6 | **Synthesize** — tallies → findings → report → decisions fed | Deliverables handed over |

`$ARGUMENTS` may name a stage and a workshop slug (`build my-workshop-2026-01-31`). Without
arguments, start at Stage 0.

## Context — where things live

- **Kit root** = the folder containing `tools/`, `workflows/`, `skills/`. Resolve it as
  `${CLAUDE_PLUGIN_ROOT}` when set (plugin install), else the git root of this skill file, else
  `$WORKSHOP_KIT_HOME`. Call it `$KIT` below. Run tools with the kit's Python
  (`$KIT/.venv/bin/python` if present, else `python3`).
- **Workspace** = where `workshops/` lives: `$WORKSHOP_KIT_WORKSPACE` or `$KIT`. One folder per
  workshop: `workshops/<slug>/` with `workshop.json` (the only source of truth; see
  `$KIT/docs/contracts.md`), `plan.md`, `brainstorm.md`, `registry.json`, `images/`, `site/`,
  `print/`, `report/`, `.tmp/` (private).
- **SOPs** in `$KIT/workflows/*.md` — one per stage from Stage 3 on. Read the SOP before running
  its stage; it lists the exact tool order, checks and fallbacks.
- **References** in this folder's `references/` — load the one the stage needs, not all:
  `workshop-types.md` (Stage 1), `grill-checklist.md` (Stage 2), `plan-template.md` (Stage 3),
  `instrument-patterns.md` and `live-display-patterns.md` (Stages 2–3 when designing forms and
  screens), `backends.md` (Stage 2 question on data collection, Stage 4), `run-day-protocol.md`
  (Stage 5), `synthesis-method.md` (Stage 6), `lessons-learned.md` (read once at Stage 1 of your
  first workshop; it is why the defaults are what they are).
- **Tools** in `$KIT/tools/*.py` — registry in `$KIT/tools/README.md`. Each takes the workshop
  folder as first argument. You orchestrate; the tools execute. Do not hand-build what a tool builds.

## The method in nine rules

1. **Evidence before opinions, opinions before product.** Ask what people did and where it
   broke before asking what they think; show designs or proposals last, as props.
2. **Codes, not names.** Every participant gets an anonymous code at the door; it is the first
   field of every form. Names, if needed at all, stay in `.tmp/`.
3. **Taps before typing.** Phone forms are taps first; one free-text line per card at most.
4. **One spec.** Agenda, instruments, screens, print pages and synthesis groups all come from
   `workshop.json`. Change the spec, rebuild; never patch a generated file.
5. **Reveal after close.** Live tallies stay hidden until the block closes, so the room cannot
   anchor on early answers. Then tally first, minority voice first.
6. **Rehearse with the test code, then cut off.** Test rows cannot be deleted from Google
   Forms; the cutoff time hides them from every tally and pull.
7. **Paper never disappears.** Print code slips and the fallback forms for the two blocks that
   matter most. Wi-Fi fails in the room where it matters most.
8. **The facilitator's own accounts.** Forms live in the facilitator's Google account or their
   Supabase project; the kit never routes data through anyone else's.
9. **Synthesis starts the same day.** Pull, tally, charts within the hour; findings while the
   room is still fresh; decisions fed back by the date promised in the room.

## Stage 0 — Locate or resume

1. List `workshops/` in the workspace. If a slug was given or exactly one workshop exists, open
   it; otherwise ask which workshop or whether to start a new one.
2. Read `plan.md` and `registry.json` (if present) to infer the stage: no `plan.md` → Stage 1–2;
   plan but no `registry.json` → Stage 3–4; registry with `cutoff` set → Stage 5; `.tmp/responses.json`
   present after the workshop date → Stage 6.
3. Say in one line what stage you are at and what the gate is.

## Stage 1 — Discover the objective and recommend a type

1. Ask, in one round (AskUserQuestion when available, up to four questions; otherwise plain
   questions): **what decision or deliverable** the workshop must produce and by when; **who** is in
   the room (roles, how many, their relationship to the product or process); **what exists already**
   (research, open questions, designs, a rule register, a backlog); **constraints** (date, duration,
   venue, language, budget, who facilitates).
2. Do the small research the answers call for, and stop when it changes the recommendation no
   further: read the documents the user points at (project notes, PRD sections, open questions,
   prior findings); if the domain or the method is unfamiliar, run two or three web searches
   ("<domain> workshop method", "<method> facilitation guide", "<method> remote vs onsite") and
   keep only what affects the type choice or the time budget. Say what you read.
3. Open `references/workshop-types.md`. Match the goal verb to the catalog (decide → requirements
   workshop; learn pain → feedback retro or journey mapping; test → usability session; generate →
   co-design; organize → card sort or affinity; prioritize → prioritization workshop; align → kickoff).
   UX research workshops are the first choice; business-side formats (SWOT, OKR drafting,
   pre-mortem, retrospective, process mapping) are offered when the goal is organizational, not
   product learning.
4. Recommend one type (at most two with a clear trade-off) in a short table: type, what it produces,
   duration, group size, blocks, what it will not answer. Ask the user to pick. Gate: a type is chosen.

## Stage 2 — Grill for the mandatory details

1. As soon as the slug is known, scaffold the folder so nothing is lost:
   `python $KIT/tools/init-workshop.py <slug> --title "…" --date YYYY-MM-DD --lang xx [--lang2 yy]`.
   Slug convention: `<topic>-<YYYY-MM-DD>`.
2. Open `references/grill-checklist.md`. Ask in rounds of at most four questions, grouped by topic
   (objective and decisions · participants and codes · schedule and venue · instruments and time
   budget · data collection backend and hosting · privacy and consent · recruitment and invite ·
   synthesis deadline and deliverables · risks and fallbacks). Propose a default with every question
   so a tired user can answer "defaults".
3. After every round, append to `workshops/<slug>/brainstorm.md`: date, the questions, the answers
   verbatim, the decision taken, open items. This file is the audit trail; never rewrite past entries.
4. When designing instruments, use `references/instrument-patterns.md` for the question shapes and
   time budget (about one minute per three tap questions, two minutes per grid, three per free text)
   and `references/live-display-patterns.md` for what the projector shows per block.
5. The backend question is mandatory and has two honest answers (`references/backends.md`):
   **google** — the facilitator has or will set up their own Google Cloud OAuth client
   (`$KIT/docs/setup-google-auth.md`, 20 minutes, needs a Google account); **static** — the kit
   renders the form pages and stores answers in the facilitator's own Supabase project
   (`$KIT/docs/setup-supabase.md`, 10 minutes, no Google needed). Never offer to use someone
   else's credentials. Gate: every checklist item answered or explicitly defaulted.

## Stage 3 — Confirm the plan

1. Write `workshops/<slug>/plan.md` from `references/plan-template.md`: objective, research
   questions, decisions fed, participants and codes, agenda table (start, minutes, block, instrument,
   screen), instruments (one line each with question count and minutes), live display plan, props,
   roles and run-of-show, privacy and consent, backend and hosting, rehearsal date, synthesis plan and
   deliverables, risks and fallbacks.
2. Write `workshops/<slug>/workshop.json` to match the plan, replacing every `<<placeholder>>` from
   the template. Keep instrument ids short (`opener`, `context`, `cards`, `gallery`, `wants`) and
   question ids as codes (`Q1`, `C1`, `C1x` for the one-line "why" after card 1).
3. Run `python $KIT/tools/validate-spec.py workshops/<slug>` and fix every error; read the warnings
   and notes aloud (buffer minutes, missing images, instruments no block opens).
4. Present the plan as a compact summary in chat — agenda table, instruments with minutes, backend,
   hosting, what prints, what the room will see live, the three biggest risks — and ask for an explicit
   confirmation. Changes go into the plan and spec, then validate again. Gate: the user says the plan
   is confirmed. Nothing is created remotely before this.

## Stage 4 — Build

Follow `$KIT/workflows/build-workshop.md` exactly; it is the order that avoids the chicken-and-egg
between the site URL, the QR codes and Google Forms images. In short:

1. `check-setup.py --workshop workshops/<slug>` → fix gaps, following `$KIT/workflows/setup-backend.md`
   when credentials or a Supabase project are missing (the user does those steps; you verify).
2. `build-site.py` → `deploy.py --create-site` (or `--zip`/`--local`) → `build-site.py` again so the
   QRs carry the final URL → `build-forms.py` (google: creates the forms and the item maps; static:
   nothing remote) → `build-site.py` once more so the landing page links the forms → `deploy.py`.
3. `build-print-pack.py` → PDF of the run sheet and fallback forms; `site/a4.html` printed from the
   local file for the code slips.
4. Rehearse per `$KIT/workflows/rehearse-workshop.md`: submit every form with the test code from a
   phone, watch `serve-live.py` show it, press `C` to set the cutoff, confirm the test rows vanish.
   Gate: rehearsal passed and `registry.cutoff` is set.

## Stage 5 — Run

Follow `$KIT/workflows/run-workshop.md` and `references/run-day-protocol.md`. Your part before the
day: the morning checklist (printed), the start command, the block-by-block script on `run.html`,
the incident card (Wi-Fi down → paper forms; token dead → `serve-live.py` shows the error, pull
later; a form rebuilt → old test rows reappear → set the cutoff again). On the day you may be absent;
the tooling must not depend on you. After the room empties: close the forms (`build-forms.py --close-all`
for google), pull once, back up `.tmp/`.

## Stage 6 — Synthesize

Follow `$KIT/workflows/synthesize-workshop.md` with `references/synthesis-method.md`:
`pull-responses.py --tally` → `build-charts.py` → read every question with `tally.py --print <ref>`
→ write `findings.md` per synthesis group (what we found, evidence with codes and counts, minority
positions, open questions) and per decision (the answer the evidence supports, confidence, what it
does not settle) → `build-report.py` (and `--gdoc` when the facilitator uses Google) → hand over the
report, the charts and the raw tallies; feed each decision to its owner by the promised date; write
`workshops/<slug>/lessons.md` (what to keep, what to change next time).

## Output per stage

- Stage 1: a recommendation table in chat; nothing on disk yet.
- Stage 2: `workshops/<slug>/brainstorm.md` growing after every round; `workshop.json` from the template.
- Stage 3: `plan.md` + `workshop.json` validated; the summary in chat; the user's confirmation quoted in `brainstorm.md`.
- Stage 4: `registry.json` with URLs, QR files, `site/` deployed, `print/pack.pdf`, cutoff set.
- Stage 5: a printed morning checklist; closed forms; `.tmp/responses.json` pulled.
- Stage 6: `findings.md`, `report/report.html` (+ `.md`, charts, optional Google Doc), `lessons.md`.

## Guardrails

- Do not create anything remote (forms, sites, sheets, Supabase rows) before Stage 3's confirmation,
  and never with `--dry-run` omitted during planning.
- Never put a name, email or employee id into the spec, a form or the projector. Codes only.
- Do not ship placeholders: `validate-spec.py` refuses `<<…>>`; so do you.
- Keep forms short: a participant form over 12 minutes loses the back of the room. Split it.
- One instrument per block on the projector; the landing page lists all of them so a lost phone recovers.
- Respect the facilitator's time budget for setup: Google route ≈ 20 min of console clicking once;
  static route ≈ 10 min for a Supabase project. Say which before they start.
- Images in Google Forms must be public URLs → deploy the site first (the SOP orders this for you).
- A Google OAuth consent screen left in Testing expires tokens after 7 days: re-consent the day before.
- The kit never decides for the room. Tallies and quotes go to the facilitator; the facilitator and the
  room decide.
- If the user asks for a format the catalog lacks, build it as `type: custom` from the same blocks and
  instruments; do not refuse, do not invent a new tool.

• SKILL.md 15 KB
• references/backends.md 3 KB
• references/grill-checklist.md 6 KB
• references/instrument-patterns.md 6 KB
• references/lessons-learned.md 4 KB
• references/live-display-patterns.md 4 KB
• references/plan-template.md 3 KB
• references/run-day-protocol.md 4 KB
• references/synthesis-method.md 3 KB
• references/workshop-types.md 9 KB