studies / process manual

Studies

parallel design exploration, judged and refined

Generate many genuinely different UI concepts, score them, pick with your own eyes, refine, and walk away with one honest artifact. A repeatable pipeline you drive from Claude Code, instead of Claude Design.

012345 loop x2 SetupGenerateAuditGateRefineFinalise Diverges to many concepts, then converges to one. Amber steps are yours.

Three ways to run it

Enablement, then reliability, then automation

Same six steps every time. What changes is how much you drive by hand and how much is fixed for you. Start at Learn. Move up when the friction of the tier below starts to cost you more than the setup of the next one.

Learn

Hand-run, general workers

Paste each step's prompt. Nothing to install. You see the whole shape of the method. Best for learning Claude Code by doing.

Repeat

Hand-run, installed workers

Install six named subagents once. The same hand-run flow stops drifting and routes models correctly. Still you pacing it. Best for running it often.

Automate

One harness, walk away

A workflow calls those installed workers and runs the whole sequence, pausing only at your gate. Fire it and leave. Best for high-stakes or batch runs.

Pick a tier. The step prompts below change to match it.

Only the machine steps change with the tier: Generate, Audit and Refine. Setup, Gate and Finalise are the same in every tier, because authoring the specs, choosing, and finalising do not change. Repeat and Automate also need the six workers installed once.

Before you start

What you need, and how to read this

Claude Code with foundational familiarity, a folder for the run, and twenty minutes for Step 0. The graph on the left is the run, top to bottom; scroll the steps and it tracks where you are. Amber steps are yours.

You decide (taste) Claude Code runs it Haiku Sonnet Opus
Every step starts the same way: you paste its prompt into Claude Code. The colour tells you what happens after. On a Claude Code step, CC does the work on its own and reports back. On a your-step (amber), you make the call. The paste is the trigger; the colour is who owns the thinking. In Automate, even the pasting goes away: one harness runs it all.
Models. The pills are the recommended routing. In Learn, set one session model with /model (Sonnet is the right default); a line in a prompt does not switch models. In Repeat and Automate the routing is real, because each installed worker carries its own model.
Step 0 · Setup

One-time setup · for Repeat and Automate

Install the workers

Learn needs nothing installed. Each step's prompt describes its worker inline, so skip straight to Setup. When you start running this often and the prompts drift (wrong file type, wrong model), that is the signal to move up to Repeat and install these.

Custom subagents are small files Claude Code loads as named workers. Save each block below into your project's .claude/agents/ folder (for example .claude/agents/studies-generator.md). Once installed, the Repeat and Automate prompts call them by name, so the model, tools and rules are fixed and stop drifting. Install once per project, not per run.

Field names follow Claude Code's agent format (name, description, model, tools). If your version differs, check the agents documentation and adjust the frontmatter; the system prompt body is what matters.
studies-generator.md
.claude/agents/studies-generator.md
---
name: studies-generator
description: Generates one UI concept from an assigned aesthetic and interaction model.
model: sonnet
tools: Read, Write
---
You are a senior product designer. Read brief.md and anti-patterns.md in the run folder. You will be given one AESTHETIC and one INTERACTION MODEL; both are non-negotiable, do not drift to safer choices. Use the frontend-design skill. Produce two files:
  designs/.html  a self-contained single-file page that opens in any browser with no build step. The primary interaction must actually work. Output HTML, never .tsx or .jsx.
  designs/.interaction.md  the navigation model, each state, keyboard/focus/ARIA behaviour, mobile changes, and which anti-patterns you avoided.
Satisfy the brief's key flows and handle its listed states, not just the happy path. Return only the two paths and one sentence on the central idea.
studies-judge.md
.claude/agents/studies-judge.md
---
name: studies-judge
description: Scores one candidate against the rubric. Read-only.
model: sonnet
tools: Read
---
You are a design and UX auditor. Read rubric.md and anti-patterns.md and the candidate you are given plus its .interaction.md. Score every rubric dimension 1 to 5 with one concrete justification tied to what is actually in the files. Score interaction and state from the .interaction.md. Apply the AI-tell penalty; a justified, well-executed use of an otherwise-clichéd pattern is not penalised. Judge the design, not its verbosity; boldness that breaks the brief scores low on fit. Return only valid JSON: id, scores, ai_tell_penalty, ai_tells_found, weighted_total, strengths, weaknesses. You never edit files.
studies-verifier.md
.claude/agents/studies-verifier.md
---
name: studies-verifier
description: Checks one candidate for a single anti-pattern. Read-only, skeptic.
model: haiku
tools: Read
---
You check whether one specific anti-pattern (given to you) is present in one candidate. Be a skeptic to limit false positives: only flag a clear, unjustified instance of the unthinking default. Return JSON: anti_pattern, present (true/false), one-line evidence. You never edit files.
studies-refiner.md
.claude/agents/studies-refiner.md
---
name: studies-refiner
description: Refines one shortlisted candidate against the human's feedback. Does not redesign.
model: sonnet
tools: Read, Write
---
You refine a strong candidate, not redesign it. Read the original, its .interaction.md, its audit JSON, and this candidate's block in shortlist.md. The human's Keep and Change are AUTHORITATIVE over the audit. PRESERVE everything under Keep plus the central idea and interaction model. FIX everything under Change, then any flagged AI-tell. Do not swap the navigation pattern, change fonts wholesale, or touch anything unflagged. Keep accessibility intact. Output a self-contained .html and update its .interaction.md. Return a 2-line changelog of what you kept and what you changed.
studies-reviewer.md
.claude/agents/studies-reviewer.md
---
name: studies-reviewer
description: Re-scores a refined candidate and confirms whether weaknesses are resolved. Read-only.
model: sonnet
tools: Read
---
You re-score a refined candidate against rubric.md and report whether each prior weakness from its audit is now resolved. Return JSON: id, scores, weighted_total, resolved (list), unresolved (list). If anything is unresolved, say so plainly so the loop can run again. You never edit files.
studies-previewer.md
.claude/agents/studies-previewer.md
---
name: studies-previewer
description: Verifies every design renders and assembles the index.html record.
model: haiku
tools: Read, Write, Bash
---
For each designs/*.html, headlessly load it in real Chrome, capture console errors, confirm the main content is populated. If one fails, fix the preview harness (CDN imports, Babel automatic JSX runtime), never the design. Build designs/index.html: embed studies_diverge_converge_node_graph.svg at the top with an amber ring on the current step node, then list every candidate with a single-click link and one-line description, ordered by audit score if audit/scores.json exists. After Step 2 include the plain-language rationale; after Step 4 include the changelogs and keep pre-refine versions with a compare link. Do not write "double-click". Do not init git or deploy.

Step 0 · you decide

Setup

You author three files: brief.md, rubric.md and anti-patterns.md. Then CC drafts matrix.md from your brief for you to approve. This is identical across all three tiers, because it is where your intent enters as rules the workers follow.

Tier note. Learn needs nothing installed. Repeat and Automate need the six workers installed once into .claude/agents/ before Step 1 (see Install the workers); after that, runs reuse them.
runs/your-slug/ brief.md you write rubric.md you tune from boilerplate anti-patterns.md you tune from boilerplate matrix.md CC drafts from your brief, you approve prompts/ the step prompts, copied in (self-contained) designs/ created when you run Step 1 audit/ created when you run Step 1
Ready when the three specs and an approved matrix are in the folder. To start: open Claude Code in runs/your-slug/ and run Step 1. In Repeat and Automate, install the six workers first (above), once per project.
brief prompt A: structured interrogation
Help me write brief.md for a Studies run. Interview me one question at a time, wait for each answer, do not pad. Ask, in order:
  1. What are you building? (the one surface, not the whole product)
  2. Who is it for, how technical are they, how often do they use it?
  3. What problem does it solve, and where does success or trust come from?
  4. What are the key user flows, start to finish?
  5. What states occur? (empty, loading, error, edge)
  6. Desktop-first, mobile-first, or parity?
  7. Does it render any system or process I should design around?
When I have answered, draft brief.md, show a one-screen summary, let me correct it.
Once the brief is approved, draft matrix.md from it using the matrix boilerplate: keep the eligible-patterns library, the aesthetic list, the coverage rule and the sanity check, and fill only the per-candidate aesthetic x interaction cells (default 8). Show me the matrix to approve. Do not generate any designs.
End your reply by telling me to author rubric.md and anti-patterns.md from boilerplate, then run Step 1.
brief prompt B: brain-dump then interrogate
Below is my unstructured thinking about a surface I want to design. Read it, then draft brief.md from it. For anything missing or ambiguous (audience, problem, key flows, states, device priority, any system the UI must render), ask me targeted questions one at a time, only for the gaps. Do not invent answers.
When the gaps are filled, show a one-screen summary and let me correct it. Once the brief is approved, draft matrix.md from it using the matrix boilerplate (fill only the per-candidate cells, default 8). Show me the matrix to approve. No designs yet.
End your reply by telling me to run Step 1 next.

MY THINKING:
[ dump everything: what it is, who it is for, why it matters, half-formed flows, references, constraints ]
rubric.md boilerplate
rubric.md
| Dimension | Weight | 1 | 5 |
|---|---|---|---|
| Hierarchy and legibility | 0.18 | nowhere for the eye to land | instant scan path |
| Brief fit | 0.20 | ignores the job | nails the job |
| Interaction fit | 0.22 | wrong pattern for the task | obvious-in-hindsight pattern |
| Flow and state coverage | 0.15 | happy path only | empty/loading/error/edge handled |
| Distinctiveness and craft | 0.15 | generic, sloppy | memorable, meticulous |
| Accessibility (incl. interaction) | 0.10 | fails AA, no keyboard/focus | clears AA, focus/escape/ARIA/kbd |
| AI-tell penalty | minus up to 1.0 | | subtract per anti-pattern present |

Optional surface-specific dimension: add one for what is uniquely hard about THIS surface, rebalance to 1.00.
anti-patterns.md boilerplate
anti-patterns.md
## Surface-specific tells (fill per run)
[ tells unique to this domain. Leave blank if none. ]

## Visual tells
- Left-border accent stripe on cards or messages
- Purple or violet gradients, especially on white
- Inter / Roboto / system-font defaults
- Sparkle iconography on generate or AI actions
- Uniform three-card grid with icon-title-blurb

## Interaction tells
- Floating circular chat bubble pinned bottom-right
- Centered single-column chat with suggestion chips
- Skeleton loaders on everything as the only loading state
- Modal-for-everything where a drawer or inline fits better

NOTE: avoidance is not contrarianism. If a pattern is the right tool, use it well.
matrix.md frame (CC fills it)
matrix.md frame
## Eligible interaction patterns (CC deletes the wrong ones)
master-detail / progressive reveal / activity stream / split view / command palette / spatial node graph / document-centric / spotlight focus / drill-down inspector / timeline / wizard / bottom sheet

## Aesthetic directions (distinct; no two candidates the same feel)
Swiss / Brutalist / Editorial / Glassmorphic / Industrial / Refined minimal / Data-dense / Calm focus / Terminal-mono / Maximalist

## Candidate assignments (CC fills from the brief; you approve)
01  [aesthetic]  x  [interaction model]
...  to N, crossing distinct cells on BOTH axes

## Coverage rule
No interaction pattern more than twice; no two candidates share both axes.

Step 1 · Claude Code runs it

Generate

CC spawns one worker per matrix row in parallel, each forced into its assigned look and interaction model, plus one baseline as the control. You paste the prompt; CC does the rest.

step 1 · Learn (general workers)
Orchestrate Step 1. Read brief.md, rubric.md, matrix.md and anti-patterns.md.
For each row in matrix.md, spawn one generator sub-agent in parallel. Give each its assigned AESTHETIC and INTERACTION MODEL (non-negotiable), and have it use the frontend-design skill. Each produces designs/.html (self-contained, opens with no build step, primary interaction works, HTML never .tsx) and designs/.interaction.md (navigation, states, keyboard/focus/ARIA, mobile, anti-patterns avoided). Each returns only the two paths and one sentence.
Also generate one baseline (no cell) as designs/00-baseline.html. Then run prompts/preview-build.md to verify renders and build designs/index.html. Give me a one-line index.
End your reply by telling me to run Step 2.
step 1 · Repeat (installed workers)
Orchestrate Step 1. Read brief.md, matrix.md, anti-patterns.md.
For each row in matrix.md, invoke the studies-generator subagent in parallel, passing that row's aesthetic and interaction model. Invoke studies-generator once more with no assigned cell for designs/00-baseline (the control).
Then invoke studies-previewer to verify renders and build designs/index.html. Give me a one-line index.
End your reply by telling me to run Step 2.
Automate runs this step inside the harness. You do not paste it. See Automate the whole run.

Step 2 · Claude Code runs it

Audit

You paste the prompt, then CC judges on its own. A fresh judge scores each candidate against your rubric and reads its interaction spec. No candidate judges its own work.

step 2 · Learn
Orchestrate Step 2. Read rubric.md and anti-patterns.md.
For each candidate in designs/ including 00-baseline, spawn an independent judge sub-agent (not the generators). Each reads the candidate and its .interaction.md, scores every rubric dimension 1 to 5 with one concrete justification, applies the AI-tell penalty, and returns JSON: id, scores, ai_tell_penalty, ai_tells_found, weighted_total, strengths, weaknesses.
Aggregate and rank into audit/scores.json and write the plain-language rationale for index.html. Show me the ranked board including the baseline. Then stop for the gate.
End your reply by telling me to open the previews, then run Step 3.
step 2 · Repeat
Orchestrate Step 2. For each candidate in designs/ including 00-baseline, invoke the studies-judge subagent (it scores against rubric.md and returns JSON). Optionally invoke studies-verifier per anti-pattern entry.
Aggregate and rank into audit/scores.json, then invoke studies-previewer to write the rationale into index.html. Show me the ranked board including the baseline. Then stop for the gate.
End your reply by telling me to open the previews, then run Step 3.
Automate runs this step inside the harness. See Automate the whole run.

Step 3 · you decide

Gate

The one decision point, and it is the same in every tier. CC presents the top five and stops. You open the previews, actually click them, then pick three with Keep and Change feedback. Your feedback overrides the judges where they disagree.

part A · paste into CC
Run Step 3. Read audit/scores.json. Confirm the previews in designs/ open; a single click on a link in designs/index.html opens each one.
Present the top 5 as a table: rank, id, aesthetic x interaction, score, AI-tells, the one watch-out, the path to open, and a one-line "what to try". Then STOP.
I will reply with my picks. Use AskUserQuestion to collect them, and when a piece of my feedback could apply to other picks, ask whether to apply it to them too. Write my selection verbatim to audit/shortlist.md, then confirm.
End your reply by telling me to run Step 4.
part B · you fill this and paste back
SHORTLIST (3 picks)

PICK 1 : candidate 
  Why it advances:  
  Keep (do not change):  
  Change or fix:  

PICK 2 : candidate 
  ...
PICK 3 : candidate 
  ...

Overall direction (optional):  
The only cheap place to redirect the run. If none is right, say so and re-run Step 1 with a sharper matrix. Do not push a weak pick into refinement and hope.

Step 4 · Claude Code runs it

Refine

CC refines all three picks against your feedback. A refiner applies your Keep and Change, a separate reviewer re-scores, looping until the rubric is met or two rounds pass. Originals are preserved.

step 4 · Learn
Orchestrate Step 4. Read audit/shortlist.md.
For each of the 3 picks, run a refiner then a separate reviewer, max 2 rounds, stopping when the reviewer confirms the rubric is met. Refiner: the human's Keep and Change are AUTHORITATIVE over the audit; preserve Keep plus the central idea and interaction model, fix Change then any flagged AI-tell, do not redesign. Output designs/refined/.html and update its .interaction.md. Keep originals.
Rebuild index.html via prompts/preview-build.md. Show me the 3 changelogs.
End your reply with: "Run the Step 5 prompt. Step 5 will ask which of the three to finalise, and you can add feedback when you reply."
step 4 · Repeat
Orchestrate Step 4. Read audit/shortlist.md.
For each of the 3 picks, invoke studies-refiner then studies-reviewer, looping max 2 rounds, stopping when the reviewer confirms the rubric is met. Keep originals; do not overwrite.
Invoke studies-previewer to rebuild index.html, keeping pre-refine versions with a compare link. Show me the 3 changelogs.
End your reply with: "Run the Step 5 prompt. Step 5 will ask which of the three to finalise, and you can add feedback when you reply."
Automate runs this loop inside the harness, pausing only at your gate. See Automate the whole run.

Step 5 · Claude Code runs it

Finalise

Where you choose the winner. CC asks which of the three refined picks to finalise and takes any last feedback, then writes a clean standalone HTML file plus a thorough interaction and README spec to final/, ready to hand to CC in another project.

step 5 · paste into CC
Run Step 5. First, use AskUserQuestion to ask which of the three refined picks (A, B, C) I want to finalise, and invite optional last feedback to apply before finalising. Wait for my answer.
Then, applying any feedback, produce in final/: a clean self-contained standalone .html (interactions working, real content where I provide it, any preview-only shortcut such as a Tailwind CDN resolved), and a thorough README + interaction spec (every state, every keyboard path, the interaction model, the anti-patterns honoured) as the contract a future project rebuilds against.
Write only to final/. Do not init git, do not deploy, do not touch another repo.
End your reply by telling me the run is complete and pointing me to final/.

Automate the whole run

One harness, calling your installed workers

When you want to fire the run and walk away, have CC write a workflow that drives all six steps and calls the workers you installed for Repeat. It pauses only at your gate. This needs the six subagents installed, and it is where per-agent model routing is genuinely enforced. Prove the method by hand first; the harness costs materially more tokens, so it is for high-stakes or batch runs, not every surface.

trigger in CC, in your run folder
ultracode - build a workflow for this Studies run. Read brief.md, rubric.md, matrix.md, anti-patterns.md first.
1. FAN-OUT generation: invoke studies-generator once per matrix row, each in its own worktree, plus one baseline. Avoid resource-heavy commands.
2. DEDUPE near-identical candidates.
3. AUDIT: invoke studies-judge per candidate and studies-verifier per anti-pattern. Synthesise into audit/scores.json.
4. GATE: use AskUserQuestion to show me the top 5; let me pick 3 with Keep/Change feedback.
5. REFINE: invoke studies-refiner then studies-reviewer per pick, looping until the rubric is met or 2 rounds. Invoke studies-previewer to rebuild index.html.
Use /goal to require all candidates generated and judged before the gate. Save it after; I will keep it for next time.

The record

index.html becomes the run's memory

Steps 1, 2 and 4 write into designs/index.html. It opens with the flow graph marking where you are up to, then lists the concepts, the audit rationale in plain language, and the refinement history. By the end it is a genuine reference: the concepts, why each scored as it did, and how the chosen three evolved.

When it misbehaves

Known wrinkles

Candidates come back as .tsx, not .html. A general worker defaulting to React. In Repeat this stops happening, because the rule lives in the installed studies-generator. In Learn, lead the prompt with the HTML requirement.

Concepts feel the same. The matrix is too weak. Sharpen the aesthetic and interaction separation, re-run Step 1.

Scores bunch at the top. The matrix working, not failing. The ranking cannot separate the finalists for you; open the top five and decide.

A file is not found. Each run folder is self-contained, so the prompts and specs must be inside it, spelled exactly. In Repeat, also check the six workers are installed in .claude/agents/.

Install workers
0 Setup
1 Generate
2 Audit
3 Gate
4 Refine
5 Finalise