---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-preference-capture-practice"
title: "Turn preference into reusable decisions — prompts and exercises"
---

# Turn preference into reusable decisions — prompts and exercises

Complete reusable prompts, setup recipes, success checks, and caveats for turn preference into reusable decisions.

## Quick start

The kit with three demo options, running in under a minute (needs `python3` + `curl`):

``` text
mkdir -p this-or-that && cd this-or-that
for f in compare.html server.py options.json options/sample-a.html options/sample-b.html options/sample-c.html; do
  curl -s --create-dirs -o "$f" "https://gentle-lasso-9d5n.here.now/kit/$f"
done
python3 server.py
# then open http://127.0.0.1:8477/compare.html and vote with your arrow keys
```

## Prompt library

Three prompts run the whole loop: kick off a lab for any decision, have the agent read your votes, ship the winner. Replace the `<ANGLE-BRACKET>` slots before pasting.

### Kick off a lab for any decision

- Agent: any coding agent
- Working directory: your project root
- Expected result: a this-or-that/ dir, N distinct option files, a 127.0.0.1 URL to vote at

``` text
Build me a local "this or that" voting lab for this decision: <DECISION — e.g. "the hero section of our landing page" / "our CLI error-message style" / "the README structure">.

Rules:
- Generate 8 genuinely DISTINCT options. Different structure, not one knob turned — if two options could be confused at arm's length, replace one. Keep the SUBJECT constant across all options; only the approach varies.
- Each option is one self-contained file an iframe can render (HTML page, image, or plain code/text file).
- Set up the this-or-that kit (compare.html + server.py + options.json — from https://gentle-lasso-9d5n.here.now/agent.md?raw) with my options listed in options.json, start the server, and give me the URL.
- I'll vote with arrow keys; every vote and note is saved to votes.jsonl. Don't interpret my taste yet — wait until I say done.
```

### Read my votes (the RLHF step)

- Agent: same session or a fresh one
- Working directory: project root, after you pressed f
- Expected result: a ranking, explicit taste rules with quoted evidence, a round-2 plan

``` text
I finished voting. Read this-or-that/votes.jsonl and:
1. Give me the final ranking with win-loss records (and per-mode splits if present).
2. Tell me what my taste IS — concrete rules inferred from the winners, the losers, the both-bad votes, and my notes. Quote the evidence for each rule.
3. Propose round 2: keep the top 2-3, cut the bottom, and generate NEW options that push harder on what won. If my votes contradict each other, say so and ask me one sharp question instead of guessing.
```

### Ship the winner and bank the taste

- Agent: same project
- Working directory: project root
- Expected result: the real artifact updated, plus a DECISIONS.md entry future sessions can read

``` text
<WINNER> won. Apply it for real:
1. Translate the winning option into the actual artifact (template / copy / config / code) in this project.
2. Verify it end-to-end, then show me before/after.
3. Record the decision: append the final standings, what won and why, and the taste rules you learned to DECISIONS.md — so future sessions start from my recorded preferences instead of re-asking.
```

## The loop, productized

This loop has now run on the workshop twice. The first round (130 votes) chose the page template you're reading. The second pointed the kit at its own question — *how should these guides be authored?* — 13 structurally distinct formats over one constant subject, 27 votes, and a decisive note later, every section ships a **Session Replay + Socratic Dialogue page pair**. Watch that round happen: [Session Replay](https://gentle-lasso-9d5n.here.now/replay.html) · [Socratic Dialogue](https://gentle-lasso-9d5n.here.now/dialogue.html).

Because it worked twice, the loop is captured twice. In the workshop repo it's an mdflow flow — one command that scaffolds a lab from this kit, fans out option authors, and injects the banked taste records fresh on every run:

``` text
md flows/this-or-that.md --_question "<WHAT TO DECIDE>" --_subject "<CONTENT HELD CONSTANT ACROSS EVERY OPTION>"
```

The flow file, verbatim:

``` text
---
description: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules
_inputs: [_question, _subject]
_interactive: true
---

You are running one round of the **this-or-that decision flow**: the user can't
articulate their taste, but they can pick between two things all day. Turn the
question below into an Elo-voted decision with a durable record.

**Question to decide:** {{ _question }}

**Subject / content source (hold constant across every option):** {{ _subject }}

## The process (exactly as proven in `authoring-lab/` and `07-variations/template-lab/`)

1. **Frame the axis.** Name the ONE thing options vary on (theme, format, copy,
   API shape). Everything else — subject content, visual theme — is held constant
   so votes measure only that axis.
2. **Scaffold the lab.** Create `<slug>-lab/` at the repo root. Copy `compare.html`
   and `server.py` **verbatim** from `10-this-or-that/kit/`. Write `options.json`
   (`{title, modes: true, options: [{id, name, src}]}`). Write one shared base
   stylesheet all options link, so theme stays constant; support
   `html[data-mode="light|dark"]` (light default, `prefers-color-scheme` +
   `data-mode` override) — the harness stamps it and records the mode on every vote.
3. **Generate 9–13 structurally distinct options.** Same subject, different
   approach; if two could be confused at arm's length, replace one. Include the
   incumbent as a control when one exists. Write one exemplar option yourself,
   then fan out parallel subagents, each authoring 2–3 options from one tight
   shared brief (subject digest + format rules + per-option spec + the exemplar
   path). Real content only — never lorem ipsum, never invented names.
4. **QA before handing over.** Every file HTTP 200 through `server.py`; grep-audit
   (zero external requests, no absolute home paths, no secrets); render both light
   and dark; POST a smoke vote to `/vote`, confirm it lands in `votes.jsonl`,
   remove it.
5. **Hand over and get out of the way.** Start `python3 server.py <port>` in the
   background and give the user the `compare.html` URL. Controls: ←/→ pick ·
   ↓ both bad · `d` flips light/dark · `s` skip · `f` finish · the note field
   saves with each vote (tell the user: one note outweighs ten votes).
6. **When the user says "done":** read `votes.jsonl` — ranking, per-mode W-L
   splits, `both_bad` lines, and especially notes. State the user's taste as
   explicit, quotable rules backed by vote evidence (head-to-heads, splits,
   quoted notes). A user note that makes a decision IS the decision.
7. **Bank it.** Archive as `votes-round<N>.jsonl`, write `RESULTS.md` (standings
   table, the decision with quoted evidence, taste rules, ship plan), update
   agent memory so it is never re-litigated. Then propose round 2 from the
   winners — or ship.

## Accumulated taste record (injected fresh each run — read before generating options)

@../authoring-lab/RESULTS.md

@../07-variations/template-lab/RESULTS.md
```

The flow file is published as a downloadable attachment on this site (the `?raw` suffix skips the HTML viewer — required for machine fetches). Pull it into your own repo's `flows/` and run it; note it injects two taste-record files by relative path (the `@`-lines at the bottom), so outside the workshop repo point those at your own `RESULTS.md` files:

``` text
mkdir -p flows
curl -fsSL "https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw" -o flows/this-or-that.md
md flows/this-or-that.md --_question "<WHAT TO DECIDE>" --_subject "<CONTENT HELD CONSTANT ACROSS EVERY OPTION>"
```

`md install "https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw"` also works — it registers the flow verbatim in the mdflow registry (reversible with `md remove this-or-that.md`) — but the registry copy can't resolve the flow's relative `@`-imports, so the `flows/`-local copy above is the layout that runs as-is.

Outside the repo, the same loop is a generalized agent skill — `this-or-that`, at `~/.agents/skills/this-or-that/SKILL.md` — which pulls `compare.html` and `server.py` straight from this site's `/kit/` files and works in any project. The SKILL.md is also a downloadable attachment; install it into a project with the `skills` CLI (stage it anywhere *except* a dir named `skills/` — the CLI claims that name as its own symlink target and you'd install an empty skill):

``` text
mkdir -p skill-src/this-or-that
curl -fsSL "https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw" -o skill-src/this-or-that/SKILL.md
npx skills add ./skill-src --skill this-or-that -y
```

## Set it up (agent guide)

Everything below is also published as [agent.md](https://gentle-lasso-9d5n.here.now/agent.md) for agents to execute cold. Three files make the kit; three sample options make it demo instantly.

1.  Create `this-or-that/compare.html` — the duel harness (Elo pairing, ←/→ voting, ↓ both-bad, `s` skip, `f` finish, per-vote notes, optional light/dark axis, synced scrolling):

    ``` text
    <!doctype html>
    <html lang="en">
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>this or that</title>
    <style>
    :root{color-scheme:dark}
    *{box-sizing:border-box}
    body{margin:0;font:14px/1.45 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;background:#101114;color:#e8e8ea;height:100vh;display:flex;flex-direction:column;overflow:hidden}
    header{display:flex;align-items:center;gap:.9rem;padding:.5rem .9rem;background:#17181c;border-bottom:1px solid #26272c;flex:0 0 auto;flex-wrap:wrap}
    #status{font-weight:700;white-space:nowrap}
    #mode{font-weight:700;font-size:12px;padding:.2rem .6rem;border-radius:99px;border:1px solid #34353c;cursor:pointer;white-space:nowrap;display:none}
    #mode.on{display:inline-block}
    #mode.light{background:#f5f2ea;color:#3a3830}
    #mode.dark{background:#0d0b08;color:#d8d2c4}
    #board{color:#9fa3ad;font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
    #board b{color:#ffd479}
    #hint{color:#8b8d94;font-size:12px}
    .hbtn{background:#26272c;color:#c9cbd2;border:1px solid #34353c;border-radius:6px;padding:.3rem .7rem;font:inherit;font-size:12px;cursor:pointer;white-space:nowrap}
    .hbtn:hover{border-color:#4a4c55;color:#fff}
    .hbtn.warn{color:#ff9d9d}
    #note{margin-left:auto;background:#0d0e11;border:1px solid #2a2b31;color:#e8e8ea;border-radius:6px;padding:.35rem .6rem;width:240px;font:inherit}
    #note::placeholder{color:#5b5d66}
    .stage{flex:1;display:flex;min-height:0}
    .pane{flex:1;display:flex;flex-direction:column;min-width:0;border-right:1px solid #26272c}
    .pane:last-child{border-right:0}
    .pane-bar{display:flex;align-items:center;gap:.6rem;padding:.38rem .8rem;background:#131418;border-bottom:1px solid #26272c}
    .pane-bar b{font-size:13px}
    .pane-bar .side{color:#8b8d94;font-size:12px}
    .pane-bar button{margin-left:auto;background:#2b6cf6;color:#fff;border:0;border-radius:6px;padding:.3rem .85rem;font-weight:600;cursor:pointer;font:inherit}
    .pane-bar button:hover{background:#3d7bff}
    iframe{flex:1;border:0;width:100%;background:#fff}
    kbd{background:#26272c;border:1px solid #34353c;border-bottom-width:2px;border-radius:4px;padding:0 .4rem;font-family:ui-monospace,Menlo,monospace;font-size:12px}
    #overlay{position:fixed;inset:0;background:rgba(8,8,10,.93);display:none;place-items:center;z-index:9}
    #overlay.show{display:grid}
    .card{background:#17181c;border:1px solid #2a2b31;border-radius:14px;padding:1.5rem 1.9rem;max-width:680px;max-height:85vh;overflow:auto}
    .card h2{margin:0 0 .7rem}
    .card table{border-collapse:collapse;width:100%;margin:.5rem 0 1rem}
    .card td,.card th{padding:.28rem .6rem;border-bottom:1px solid #26272c;text-align:left;font-size:13px}
    .card th{color:#8b8d94;font-weight:600}
    .card p{color:#b9bbc3}
    .card button{background:#2b6cf6;color:#fff;border:0;border-radius:8px;padding:.5rem 1.1rem;font-weight:600;cursor:pointer;font:inherit}
    </style>
    </head>
    <body>
    <header>
      <span id="status"></span>
      <button id="mode" onclick="toggleMode(true)"></button>
      <span id="board"></span>
      <button class="hbtn warn" onclick="bothBad()">Both bad <kbd>↓</kbd></button>
      <button class="hbtn" onclick="skip()">Skip <kbd>s</kbd></button>
      <button class="hbtn" onclick="finish()">Finish <kbd>f</kbd></button>
      <span id="hint"></span>
      <input id="note" placeholder="optional note — saved with vote">
    </header>
    <div class="stage" id="stage"></div>
    <div id="overlay"><div class="card" id="ocard"></div></div>
    <script>
    'use strict';
    let V = [], MODES = false, TITLE = 'this or that';
    const K = 32;
    let elo = [], games = [], rec = [];
    let mode = 'duel', A = -1, B = -1, voteN = 0, duelN = 0, browseI = 0, lastKey = '';
    let uiMode = 'light', toggled = false;

    const stage = document.getElementById('stage');
    const statusEl = document.getElementById('status');
    const modeEl = document.getElementById('mode');
    const board = document.getElementById('board');
    const hint = document.getElementById('hint');
    const note = document.getElementById('note');
    const overlay = document.getElementById('overlay');

    const N = () => V.length;
    const src = i => V[i].src;
    const name = i => V[i].name;

    function post(d){ d.lab = TITLE; fetch('/vote',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(d)}).catch(()=>{}); }
    function expected(ra, rb){ return 1/(1+Math.pow(10,(rb-ra)/400)); }
    function applyResult(w, l){
      const ew = expected(elo[w], elo[l]);
      elo[w] = Math.round(elo[w] + K*(1-ew));
      elo[l] = Math.round(elo[l] - K*(1-ew));
      games[w]++; games[l]++;
      if (MODES) rec[w][uiMode].w++, rec[l][uiMode].l++;
    }
    function ranked(){ return V.map((v,i)=>i).sort((a,b)=>elo[b]-elo[a]); }
    function renderBoard(){
      board.innerHTML = 'top: ' + ranked().slice(0,3).map(i=>`<b>${name(i)}</b> ${elo[i]}`).join(' · ');
    }
    function renderMode(){
      if (!MODES) return;
      modeEl.className = 'on ' + uiMode;
      modeEl.textContent = (uiMode === 'light' ? ' light' : ' dark') + ' — d flips';
    }
    function applyMode(){
      renderMode();
      if (!MODES) return;
      document.querySelectorAll('iframe').forEach(f => {
        try { f.contentWindow.document.documentElement.dataset.mode = uiMode; } catch(e){}
      });
    }
    window.toggleMode = (manual) => {
      if (!MODES) return;
      uiMode = uiMode === 'light' ? 'dark' : 'light';
      if (manual) toggled = true;
      applyMode();
    };
    function pickPair(){
      let best = null, bestScore = Infinity;
      for (let i=0;i<N();i++) for (let j=i+1;j<N();j++){
        const key = i+'-'+j;
        if (key === lastKey) continue;
        const score = (games[i]+games[j])*60 + Math.abs(elo[i]-elo[j]) + Math.random()*40;
        if (score < bestScore){ bestScore = score; best = [i,j]; }
      }
      lastKey = best[0]+'-'+best[1];
      return Math.random() < .5 ? best : [best[1], best[0]];
    }
    function hookIframes(){
      const frames = [...document.querySelectorAll('iframe')];
      frames.forEach(f => f.addEventListener('load', () => {
        try {
          if (MODES) f.contentWindow.document.documentElement.dataset.mode = uiMode;
          f.contentWindow.addEventListener('keydown', onKey);
          const other = frames.find(x => x !== f);
          if (!other) return;
          let lock = false;
          f.contentWindow.addEventListener('scroll', () => {
            if (lock) { lock = false; return; }
            try {
              const a = f.contentWindow, b = other.contentWindow;
              const ah = a.document.documentElement.scrollHeight - a.innerHeight;
              const bh = b.document.documentElement.scrollHeight - b.innerHeight;
              if (ah > 0 && bh > 0){ lock = true; b.scrollTo(0, a.scrollY/ah*bh); }
            } catch(e){}
          }, {passive:true});
        } catch(e){}
      }));
    }
    function paneHTML(i, side, key){
      return `<div class="pane"><div class="pane-bar"><b>${name(i)}</b><span class="side">${side} · elo ${elo[i]} · ${games[i]} games</span>`+
            `<button onclick="pick('${side}')">This one <kbd>${key}</kbd></button></div>`+
            `<iframe src="${src(i)}"></iframe></div>`;
    }
    function renderDuel(){
      [A, B] = pickPair();
      duelN++;
      if (MODES){ uiMode = duelN % 2 ? 'light' : 'dark'; toggled = false; }
      stage.innerHTML = paneHTML(A,'left','←') + paneHTML(B,'right','→');
      statusEl.textContent = `Vote ${voteN+1}`;
      hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> pick · winner-agnostic pairing · vote until it stops being informative';
      renderBoard(); renderMode();
      hookIframes();
    }
    window.pick = side => {
      if (mode !== 'duel') return;
      const w = side === 'left' ? A : B, l = side === 'left' ? B : A;
      applyResult(w, l);
      voteN++;
      const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), winner:name(w), loser:name(l),
                 elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};
      if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }
      post(d);
      note.value = '';
      renderDuel();
    };
    window.bothBad = () => {
      if (mode !== 'duel') return;
      elo[A] = Math.round(elo[A] - 12); elo[B] = Math.round(elo[B] - 12);
      games[A]++; games[B]++;
      voteN++;
      const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), result:'both_bad',
                 elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};
      if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }
      post(d);
      note.value = '';
      renderDuel();
    };
    window.skip = () => { if (mode === 'duel') renderDuel(); };
    window.finish = () => {
      if (mode !== 'duel') return;
      mode = 'browse'; browseI = ranked()[0];
      const table = ranked().map(i => {
        const r = {id:V[i].id, name:name(i), elo:elo[i], games:games[i]};
        if (MODES){ r.light = `${rec[i].light.w}-${rec[i].light.l}`; r.dark = `${rec[i].dark.w}-${rec[i].dark.l}`; }
        return r;
      });
      post({mode:'final', votes:voteN, table});
      document.getElementById('ocard').innerHTML =
        `<h2>Standings — ${voteN} votes</h2>`+
        `<table><tr><th>#</th><th>Option</th><th>Elo</th><th>Games</th>${MODES?'<th>Light W-L</th><th>Dark W-L</th>':''}</tr>`+
        table.map((r,i)=>`<tr><td>${i+1}</td><td>${r.name}</td><td>${r.elo}</td><td>${r.games}</td>${MODES?`<td>${r.light}</td><td>${r.dark}</td>`:''}</tr>`).join('')+
        `</table><p>Saved to <code>votes.jsonl</code> — tell your agent to read it. <kbd>←</kbd>/<kbd>→</kbd> browse · <kbd>r</kbd> keep voting</p>`+
        `<button onclick="closeOverlay()">Browse →</button>`;
      overlay.classList.add('show');
    };
    window.closeOverlay = () => { overlay.classList.remove('show'); renderBrowse(); };
    function renderBrowse(){
      stage.innerHTML = `<div class="pane"><div class="pane-bar"><b>${name(browseI)}</b>`+
        `<span class="side">elo ${elo[browseI]} · ${ranked().indexOf(browseI)+1} of ${N()}</span></div><iframe src="${src(browseI)}"></iframe></div>`;
      statusEl.textContent = 'Browse';
      hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> cycle by rank · <kbd>r</kbd> keep voting';
      hookIframes();
    }
    function onKey(e){
      if (e.target === note) return;
      if (e.key === 'd'){ toggleMode(true); return; }
      if (mode === 'duel'){
        if (e.key === 'ArrowLeft'){ e.preventDefault(); pick('left'); }
        else if (e.key === 'ArrowRight'){ e.preventDefault(); pick('right'); }
        else if (e.key === 'ArrowDown'){ e.preventDefault(); bothBad(); }
        else if (e.key === 's'){ skip(); }
        else if (e.key === 'f' || e.key === 'Enter'){ finish(); }
      } else {
        const order = ranked();
        const pos = order.indexOf(browseI);
        if (e.key === 'ArrowLeft'){ browseI = order[(pos+N()-1)%N()]; renderBrowse(); }
        else if (e.key === 'ArrowRight'){ browseI = order[(pos+1)%N()]; renderBrowse(); }
        else if (e.key === 'r'){ mode = 'duel'; renderDuel(); }
      }
    }
    document.addEventListener('keydown', onKey);

    fetch('options.json').then(r => r.json()).then(cfg => {
      TITLE = cfg.title || TITLE;
      MODES = !!cfg.modes;
      V = cfg.options;
      document.title = TITLE + ' — this or that';
      elo = V.map(() => 1000);
      games = V.map(() => 0);
      rec = V.map(() => ({light:{w:0,l:0}, dark:{w:0,l:0}}));
      renderDuel();
    }).catch(() => {
      stage.innerHTML = '<div style="padding:2rem;color:#ff9d9d">Could not load options.json — serve this directory with server.py, not file://</div>';
    });
    </script>
    </body>
    </html>
    ```

2.  Create `this-or-that/server.py` — serves the dir and appends every POSTed vote to `votes.jsonl`:

    ``` text
    #!/usr/bin/env python3
    """this-or-that server: serves the kit dir + appends POST /vote JSON bodies to votes.jsonl."""
    import json, os, sys, time
    from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler

    ROOT = os.path.dirname(os.path.abspath(__file__))
    PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8477

    class Handler(SimpleHTTPRequestHandler):
        def __init__(self, *a, **kw):
            super().__init__(*a, directory=ROOT, **kw)

        def do_POST(self):
            if self.path != "/vote":
                self.send_response(404); self.end_headers(); return
            n = int(self.headers.get("Content-Length", 0))
            try:
                data = json.loads(self.rfile.read(n) or b"{}")
            except Exception:
                data = {"error": "unparseable"}
            data["ts"] = time.strftime("%Y-%m-%dT%H:%M:%S")
            with open(os.path.join(ROOT, "votes.jsonl"), "a", encoding="utf-8") as f:
                f.write(json.dumps(data) + "\n")
            self.send_response(204); self.end_headers()

        def log_message(self, *a):
            pass

    if __name__ == "__main__":
        print(f"this-or-that → http://127.0.0.1:{PORT}/compare.html")
        ThreadingHTTPServer(("127.0.0.1", PORT), Handler).serve_forever()
    ```

3.  Create `this-or-that/options.json` — the manifest. `src` is anything an iframe can render; set `"modes": true` to add a light/dark axis (duels alternate modes, `d` flips, per-mode records are tracked — options must respond to `<html data-mode="light|dark">`):

    ``` text
    {
      "title": "Pick a direction",
      "modes": false,
      "options": [
        { "id": "a", "name": "Option A", "src": "options/sample-a.html" },
        { "id": "b", "name": "Option B", "src": "options/sample-b.html" },
        { "id": "c", "name": "Option C", "src": "options/sample-c.html" }
      ]
    }
    ```

4.  Create the three demo options (same subject, three styles — replace with real options for a real decision):

    ``` text
    <!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>A</title>
    <style>body{margin:0;font-family:system-ui;background:oklch(98% .008 80);color:oklch(16% .008 80);display:grid;place-items:center;min-height:100vh}
    .hero{max-width:26rem;padding:2rem}.hero h1{font-size:2.6rem;font-weight:820;letter-spacing:-.03em;line-height:1;margin:0 0 .6rem}
    .hero p{color:oklch(55% .016 80)}.hero button{background:oklch(60% .19 40);color:#fff;border:0;padding:.7rem 1.4rem;font:inherit;font-weight:700;text-transform:uppercase;font-size:.7rem;letter-spacing:.06em}</style></head>
    <body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option A: big type, one accent, flat.</p><button>Get started</button></div></body></html>
    ```

    ``` text
    <!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>B</title>
    <style>body{margin:0;font-family:ui-serif,Georgia,serif;background:oklch(97% .02 85);color:oklch(22% .015 80);display:grid;place-items:center;min-height:100vh}
    .hero{max-width:24rem;padding:2rem;text-align:center}.hero h1{font-size:2.1rem;font-weight:650;margin:0 0 .6rem}
    .hero p{font-style:italic;color:oklch(50% .03 80)}.hero button{background:none;color:oklch(45% .13 25);border:2px solid currentColor;border-radius:99px;padding:.6rem 1.5rem;font:inherit;font-weight:600}</style></head>
    <body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option B: centered serif, soft, outlined.</p><button>Get started</button></div></body></html>
    ```

    ``` text
    <!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>C</title>
    <style>body{margin:0;font-family:ui-monospace,Menlo,monospace;background:oklch(15% .01 250);color:oklch(90% .01 250);display:grid;place-items:center;min-height:100vh}
    .hero{max-width:26rem;padding:2rem;border:1px solid oklch(35% .02 250)}.hero h1{font-size:1.6rem;font-weight:700;margin:0 0 .6rem}.hero h1::before{content:"$ ";color:oklch(75% .15 150)}
    .hero p{color:oklch(65% .02 250)}.hero button{background:oklch(75% .15 150);color:oklch(15% .05 150);border:0;padding:.6rem 1.2rem;font:inherit;font-weight:700}</style></head>
    <body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option C: terminal dark, mono, green go.</p><button>Get started</button></div></body></html>
    ```

5.  Run it:

    ``` text
    cd this-or-that && python3 server.py
    # open http://127.0.0.1:8477/compare.html
    ```

**Success check:** with the server running, this must append one line to `votes.jsonl`:

``` text
curl -s -X POST http://127.0.0.1:8477/vote -H 'Content-Type: application/json' -d '{"probe":true}'
tail -1 this-or-that/votes.jsonl
```

Expected: a JSON line containing `"probe": true` plus a `"ts"` timestamp — and `http://127.0.0.1:8477/compare.html` shows two options side by side. Report both results to your user, then delete the probe line.

Every real vote looks like this — `winner`, `loser`, a full Elo snapshot, and the optional note; a `final` line with the standings table lands when the voter presses `f`:

``` text
{"mode": "elo", "vote": 12, "left": "Option C", "right": "Option B", "winner": "Option C", "loser": "Option B", "elo": {"a": 1000, "b": 984, "c": 1016}, "note": "C's header wins but B's spacing is calmer", "lab": "Pick a direction", "ts": "the example workflow-16T22:35:47"}
```

## Complete reusable setup contract

## This or That: RLHF for Your Agent — agent setup guide

Following this file sets up: a local "this or that" voting lab in the user's current project — a duel harness page, a tiny vote-recording server, a manifest of options, and three demo options. The user votes with arrow keys; every vote is appended to `votes.jsonl` for you (the agent) to read and act on.

Human companion pages on this site: the [section guide](https://gentle-lasso-9d5n.here.now/) (kit, prompts, the full write-up), the [Session Replay](https://gentle-lasso-9d5n.here.now/replay.html) (turn-by-turn replay of the round where this loop chose the workshop's own page format — 13 formats, 27 votes), and the [Socratic Dialogue](https://gentle-lasso-9d5n.here.now/dialogue.html) (attendee Q&A).

Placeholders used below: `<project-root>` = the project you are working in. All paths are relative to `<project-root>`.

## Prerequisites

Check each before starting:

- `python3 --version` — any Python 3.8+.
- A browser on the same machine (the lab runs at `http://127.0.0.1:8477`).
- Port 8477 free (or pick another: `python3 server.py 8481`).

## Steps

1. Create `this-or-that/compare.html` with exactly this content — the duel harness (Elo pairing, ←/→ voting, ↓ both-bad, `s` skip, `f` finish, per-vote notes, optional light/dark axis, synced scrolling):

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>this or that</title>
<style>
:root{color-scheme:dark}
*{box-sizing:border-box}
body{margin:0;font:14px/1.45 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;background:#101114;color:#e8e8ea;height:100vh;display:flex;flex-direction:column;overflow:hidden}
header{display:flex;align-items:center;gap:.9rem;padding:.5rem .9rem;background:#17181c;border-bottom:1px solid #26272c;flex:0 0 auto;flex-wrap:wrap}
#status{font-weight:700;white-space:nowrap}
#mode{font-weight:700;font-size:12px;padding:.2rem .6rem;border-radius:99px;border:1px solid #34353c;cursor:pointer;white-space:nowrap;display:none}
#mode.on{display:inline-block}
#mode.light{background:#f5f2ea;color:#3a3830}
#mode.dark{background:#0d0b08;color:#d8d2c4}
#board{color:#9fa3ad;font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
#board b{color:#ffd479}
#hint{color:#8b8d94;font-size:12px}
.hbtn{background:#26272c;color:#c9cbd2;border:1px solid #34353c;border-radius:6px;padding:.3rem .7rem;font:inherit;font-size:12px;cursor:pointer;white-space:nowrap}
.hbtn:hover{border-color:#4a4c55;color:#fff}
.hbtn.warn{color:#ff9d9d}
#note{margin-left:auto;background:#0d0e11;border:1px solid #2a2b31;color:#e8e8ea;border-radius:6px;padding:.35rem .6rem;width:240px;font:inherit}
#note::placeholder{color:#5b5d66}
.stage{flex:1;display:flex;min-height:0}
.pane{flex:1;display:flex;flex-direction:column;min-width:0;border-right:1px solid #26272c}
.pane:last-child{border-right:0}
.pane-bar{display:flex;align-items:center;gap:.6rem;padding:.38rem .8rem;background:#131418;border-bottom:1px solid #26272c}
.pane-bar b{font-size:13px}
.pane-bar .side{color:#8b8d94;font-size:12px}
.pane-bar button{margin-left:auto;background:#2b6cf6;color:#fff;border:0;border-radius:6px;padding:.3rem .85rem;font-weight:600;cursor:pointer;font:inherit}
.pane-bar button:hover{background:#3d7bff}
iframe{flex:1;border:0;width:100%;background:#fff}
kbd{background:#26272c;border:1px solid #34353c;border-bottom-width:2px;border-radius:4px;padding:0 .4rem;font-family:ui-monospace,Menlo,monospace;font-size:12px}
#overlay{position:fixed;inset:0;background:rgba(8,8,10,.93);display:none;place-items:center;z-index:9}
#overlay.show{display:grid}
.card{background:#17181c;border:1px solid #2a2b31;border-radius:14px;padding:1.5rem 1.9rem;max-width:680px;max-height:85vh;overflow:auto}
.card h2{margin:0 0 .7rem}
.card table{border-collapse:collapse;width:100%;margin:.5rem 0 1rem}
.card td,.card th{padding:.28rem .6rem;border-bottom:1px solid #26272c;text-align:left;font-size:13px}
.card th{color:#8b8d94;font-weight:600}
.card p{color:#b9bbc3}
.card button{background:#2b6cf6;color:#fff;border:0;border-radius:8px;padding:.5rem 1.1rem;font-weight:600;cursor:pointer;font:inherit}
</style>
</head>
<body>
<header>
  <span id="status"></span>
  <button id="mode" onclick="toggleMode(true)"></button>
  <span id="board"></span>
  <button class="hbtn warn" onclick="bothBad()">Both bad <kbd>↓</kbd></button>
  <button class="hbtn" onclick="skip()">Skip <kbd>s</kbd></button>
  <button class="hbtn" onclick="finish()">Finish <kbd>f</kbd></button>
  <span id="hint"></span>
  <input id="note" placeholder="optional note — saved with vote">
</header>
<div class="stage" id="stage"></div>
<div id="overlay"><div class="card" id="ocard"></div></div>
<script>
'use strict';
let V = [], MODES = false, TITLE = 'this or that';
const K = 32;
let elo = [], games = [], rec = [];
let mode = 'duel', A = -1, B = -1, voteN = 0, duelN = 0, browseI = 0, lastKey = '';
let uiMode = 'light', toggled = false;

const stage = document.getElementById('stage');
const statusEl = document.getElementById('status');
const modeEl = document.getElementById('mode');
const board = document.getElementById('board');
const hint = document.getElementById('hint');
const note = document.getElementById('note');
const overlay = document.getElementById('overlay');

const N = () => V.length;
const src = i => V[i].src;
const name = i => V[i].name;

function post(d){ d.lab = TITLE; fetch('/vote',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(d)}).catch(()=>{}); }
function expected(ra, rb){ return 1/(1+Math.pow(10,(rb-ra)/400)); }
function applyResult(w, l){
  const ew = expected(elo[w], elo[l]);
  elo[w] = Math.round(elo[w] + K*(1-ew));
  elo[l] = Math.round(elo[l] - K*(1-ew));
  games[w]++; games[l]++;
  if (MODES) rec[w][uiMode].w++, rec[l][uiMode].l++;
}
function ranked(){ return V.map((v,i)=>i).sort((a,b)=>elo[b]-elo[a]); }
function renderBoard(){
  board.innerHTML = 'top: ' + ranked().slice(0,3).map(i=>`<b>${name(i)}</b> ${elo[i]}`).join(' · ');
}
function renderMode(){
  if (!MODES) return;
  modeEl.className = 'on ' + uiMode;
  modeEl.textContent = (uiMode === 'light' ? ' light' : ' dark') + ' — d flips';
}
function applyMode(){
  renderMode();
  if (!MODES) return;
  document.querySelectorAll('iframe').forEach(f => {
    try { f.contentWindow.document.documentElement.dataset.mode = uiMode; } catch(e){}
  });
}
window.toggleMode = (manual) => {
  if (!MODES) return;
  uiMode = uiMode === 'light' ? 'dark' : 'light';
  if (manual) toggled = true;
  applyMode();
};
function pickPair(){
  let best = null, bestScore = Infinity;
  for (let i=0;i<N();i++) for (let j=i+1;j<N();j++){
    const key = i+'-'+j;
    if (key === lastKey) continue;
    const score = (games[i]+games[j])*60 + Math.abs(elo[i]-elo[j]) + Math.random()*40;
    if (score < bestScore){ bestScore = score; best = [i,j]; }
  }
  lastKey = best[0]+'-'+best[1];
  return Math.random() < .5 ? best : [best[1], best[0]];
}
function hookIframes(){
  const frames = [...document.querySelectorAll('iframe')];
  frames.forEach(f => f.addEventListener('load', () => {
    try {
      if (MODES) f.contentWindow.document.documentElement.dataset.mode = uiMode;
      f.contentWindow.addEventListener('keydown', onKey);
      const other = frames.find(x => x !== f);
      if (!other) return;
      let lock = false;
      f.contentWindow.addEventListener('scroll', () => {
        if (lock) { lock = false; return; }
        try {
          const a = f.contentWindow, b = other.contentWindow;
          const ah = a.document.documentElement.scrollHeight - a.innerHeight;
          const bh = b.document.documentElement.scrollHeight - b.innerHeight;
          if (ah > 0 && bh > 0){ lock = true; b.scrollTo(0, a.scrollY/ah*bh); }
        } catch(e){}
      }, {passive:true});
    } catch(e){}
  }));
}
function paneHTML(i, side, key){
  return `<div class="pane"><div class="pane-bar"><b>${name(i)}</b><span class="side">${side} · elo ${elo[i]} · ${games[i]} games</span>`+
        `<button onclick="pick('${side}')">This one <kbd>${key}</kbd></button></div>`+
        `<iframe src="${src(i)}"></iframe></div>`;
}
function renderDuel(){
  [A, B] = pickPair();
  duelN++;
  if (MODES){ uiMode = duelN % 2 ? 'light' : 'dark'; toggled = false; }
  stage.innerHTML = paneHTML(A,'left','←') + paneHTML(B,'right','→');
  statusEl.textContent = `Vote ${voteN+1}`;
  hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> pick · winner-agnostic pairing · vote until it stops being informative';
  renderBoard(); renderMode();
  hookIframes();
}
window.pick = side => {
  if (mode !== 'duel') return;
  const w = side === 'left' ? A : B, l = side === 'left' ? B : A;
  applyResult(w, l);
  voteN++;
  const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), winner:name(w), loser:name(l),
             elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};
  if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }
  post(d);
  note.value = '';
  renderDuel();
};
window.bothBad = () => {
  if (mode !== 'duel') return;
  elo[A] = Math.round(elo[A] - 12); elo[B] = Math.round(elo[B] - 12);
  games[A]++; games[B]++;
  voteN++;
  const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), result:'both_bad',
             elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};
  if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }
  post(d);
  note.value = '';
  renderDuel();
};
window.skip = () => { if (mode === 'duel') renderDuel(); };
window.finish = () => {
  if (mode !== 'duel') return;
  mode = 'browse'; browseI = ranked()[0];
  const table = ranked().map(i => {
    const r = {id:V[i].id, name:name(i), elo:elo[i], games:games[i]};
    if (MODES){ r.light = `${rec[i].light.w}-${rec[i].light.l}`; r.dark = `${rec[i].dark.w}-${rec[i].dark.l}`; }
    return r;
  });
  post({mode:'final', votes:voteN, table});
  document.getElementById('ocard').innerHTML =
    `<h2>Standings — ${voteN} votes</h2>`+
    `<table><tr><th>#</th><th>Option</th><th>Elo</th><th>Games</th>${MODES?'<th>Light W-L</th><th>Dark W-L</th>':''}</tr>`+
    table.map((r,i)=>`<tr><td>${i+1}</td><td>${r.name}</td><td>${r.elo}</td><td>${r.games}</td>${MODES?`<td>${r.light}</td><td>${r.dark}</td>`:''}</tr>`).join('')+
    `</table><p>Saved to <code>votes.jsonl</code> — tell your agent to read it. <kbd>←</kbd>/<kbd>→</kbd> browse · <kbd>r</kbd> keep voting</p>`+
    `<button onclick="closeOverlay()">Browse →</button>`;
  overlay.classList.add('show');
};
window.closeOverlay = () => { overlay.classList.remove('show'); renderBrowse(); };
function renderBrowse(){
  stage.innerHTML = `<div class="pane"><div class="pane-bar"><b>${name(browseI)}</b>`+
    `<span class="side">elo ${elo[browseI]} · ${ranked().indexOf(browseI)+1} of ${N()}</span></div><iframe src="${src(browseI)}"></iframe></div>`;
  statusEl.textContent = 'Browse';
  hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> cycle by rank · <kbd>r</kbd> keep voting';
  hookIframes();
}
function onKey(e){
  if (e.target === note) return;
  if (e.key === 'd'){ toggleMode(true); return; }
  if (mode === 'duel'){
    if (e.key === 'ArrowLeft'){ e.preventDefault(); pick('left'); }
    else if (e.key === 'ArrowRight'){ e.preventDefault(); pick('right'); }
    else if (e.key === 'ArrowDown'){ e.preventDefault(); bothBad(); }
    else if (e.key === 's'){ skip(); }
    else if (e.key === 'f' || e.key === 'Enter'){ finish(); }
  } else {
    const order = ranked();
    const pos = order.indexOf(browseI);
    if (e.key === 'ArrowLeft'){ browseI = order[(pos+N()-1)%N()]; renderBrowse(); }
    else if (e.key === 'ArrowRight'){ browseI = order[(pos+1)%N()]; renderBrowse(); }
    else if (e.key === 'r'){ mode = 'duel'; renderDuel(); }
  }
}
document.addEventListener('keydown', onKey);

fetch('options.json').then(r => r.json()).then(cfg => {
  TITLE = cfg.title || TITLE;
  MODES = !!cfg.modes;
  V = cfg.options;
  document.title = TITLE + ' — this or that';
  elo = V.map(() => 1000);
  games = V.map(() => 0);
  rec = V.map(() => ({light:{w:0,l:0}, dark:{w:0,l:0}}));
  renderDuel();
}).catch(() => {
  stage.innerHTML = '<div style="padding:2rem;color:#ff9d9d">Could not load options.json — serve this directory with server.py, not file://</div>';
});
</script>
</body>
</html>
```

2. Create `this-or-that/server.py` — serves the directory and appends every POSTed vote to `votes.jsonl`:

```python
#!/usr/bin/env python3
"""this-or-that server: serves the kit dir + appends POST /vote JSON bodies to votes.jsonl."""
import json, os, sys, time
from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler

ROOT = os.path.dirname(os.path.abspath(__file__))
PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8477

class Handler(SimpleHTTPRequestHandler):
    def __init__(self, *a, **kw):
        super().__init__(*a, directory=ROOT, **kw)

    def do_POST(self):
        if self.path != "/vote":
            self.send_response(404); self.end_headers(); return
        n = int(self.headers.get("Content-Length", 0))
        try:
            data = json.loads(self.rfile.read(n) or b"{}")
        except Exception:
            data = {"error": "unparseable"}
        data["ts"] = time.strftime("%Y-%m-%dT%H:%M:%S")
        with open(os.path.join(ROOT, "votes.jsonl"), "a", encoding="utf-8") as f:
            f.write(json.dumps(data) + "\n")
        self.send_response(204); self.end_headers()

    def log_message(self, *a):
        pass

if __name__ == "__main__":
    print(f"this-or-that → http://127.0.0.1:{PORT}/compare.html")
    ThreadingHTTPServer(("127.0.0.1", PORT), Handler).serve_forever()
```

3. Create `this-or-that/options.json` — the manifest. `src` is anything an iframe can render (HTML page, image, code/text file). Set `"modes": true` only if every option responds to `<html data-mode="light|dark">`; duels then alternate modes, `d` flips both panes, and per-mode win-loss records are tracked:

```json
{
  "title": "Pick a direction",
  "modes": false,
  "options": [
    { "id": "a", "name": "Option A", "src": "options/sample-a.html" },
    { "id": "b", "name": "Option B", "src": "options/sample-b.html" },
    { "id": "c", "name": "Option C", "src": "options/sample-c.html" }
  ]
}
```

4. Create the three demo options (same subject, three deliberately different styles). For a real decision, replace these with the user's options and update `options.json`:

`this-or-that/options/sample-a.html`:

```html
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>A</title>
<style>body{margin:0;font-family:system-ui;background:oklch(98% .008 80);color:oklch(16% .008 80);display:grid;place-items:center;min-height:100vh}
.hero{max-width:26rem;padding:2rem}.hero h1{font-size:2.6rem;font-weight:820;letter-spacing:-.03em;line-height:1;margin:0 0 .6rem}
.hero p{color:oklch(55% .016 80)}.hero button{background:oklch(60% .19 40);color:#fff;border:0;padding:.7rem 1.4rem;font:inherit;font-weight:700;text-transform:uppercase;font-size:.7rem;letter-spacing:.06em}</style></head>
<body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option A: big type, one accent, flat.</p><button>Get started</button></div></body></html>
```

`this-or-that/options/sample-b.html`:

```html
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>B</title>
<style>body{margin:0;font-family:ui-serif,Georgia,serif;background:oklch(97% .02 85);color:oklch(22% .015 80);display:grid;place-items:center;min-height:100vh}
.hero{max-width:24rem;padding:2rem;text-align:center}.hero h1{font-size:2.1rem;font-weight:650;margin:0 0 .6rem}
.hero p{font-style:italic;color:oklch(50% .03 80)}.hero button{background:none;color:oklch(45% .13 25);border:2px solid currentColor;border-radius:99px;padding:.6rem 1.5rem;font:inherit;font-weight:600}</style></head>
<body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option B: centered serif, soft, outlined.</p><button>Get started</button></div></body></html>
```

`this-or-that/options/sample-c.html`:

```html
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>C</title>
<style>body{margin:0;font-family:ui-monospace,Menlo,monospace;background:oklch(15% .01 250);color:oklch(90% .01 250);display:grid;place-items:center;min-height:100vh}
.hero{max-width:26rem;padding:2rem;border:1px solid oklch(35% .02 250)}.hero h1{font-size:1.6rem;font-weight:700;margin:0 0 .6rem}.hero h1::before{content:"$ ";color:oklch(75% .15 150)}
.hero p{color:oklch(65% .02 250)}.hero button{background:oklch(75% .15 150);color:oklch(15% .05 150);border:0;padding:.6rem 1.2rem;font:inherit;font-weight:700}</style></head>
<body><div class="hero"><h1>Ship the winner</h1><p>Same subject, different style. This is Option C: terminal dark, mono, green go.</p><button>Get started</button></div></body></html>
```

5. Start the server and tell the user where to vote:

```bash
cd this-or-that && python3 server.py
# → this-or-that → http://127.0.0.1:8477/compare.html
```

## Success check

With the server running:

```bash
curl -s -X POST http://127.0.0.1:8477/vote -H 'Content-Type: application/json' -d '{"probe":true}'
tail -1 this-or-that/votes.jsonl
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8477/compare.html
```

Expected: the `tail` prints a JSON line containing `"probe": true` plus a `"ts"` timestamp, and the last command prints `200`. Also confirm in a browser that `compare.html` shows two options side by side with "This one" buttons. Report all results to your user, then remove the probe line from `votes.jsonl`.

## Notes for agents

- **Serve, don't open as a file.** `compare.html` fetches `options.json` and POSTs votes — `file://` breaks both. Always go through `server.py`.
- **Options must be same-origin** (files inside `this-or-that/`). Cross-origin option URLs render, but scroll-sync and the light/dark stamp fail silently.
- **Generating options for a real decision:** make them genuinely DISTINCT — different structure, not one knob turned. If two options could be confused at arm's length, replace one. Keep the subject constant across all options; only the approach varies. 6–12 options is the useful range.
- **When the user says they're done voting:** read `this-or-that/votes.jsonl`. Vote lines carry `winner`, `loser`, a full `elo` snapshot, and an optional `note`; a `"mode": "final"` line carries the standings table. Report the ranking, infer explicit taste rules (quote the evidence — especially notes and `both_bad` results), and propose the next round: keep the top 2–3, cut the rest, generate new options that push on what won.
- **Bank the outcome.** After a winner ships, append the standings and the inferred taste rules to the project's `DECISIONS.md` so future sessions inherit the preference record instead of re-asking.
- **Productized forms of this loop.** In John's workshop repo, `flows/this-or-that.md` runs an entire round as one mdflow command — `md flows/this-or-that.md --_question "..." --_subject "..."` — and injects the banked taste records fresh on every run (the flow file is printed verbatim on the section guide). For any other repo, the generalized `this-or-that` agent skill (`~/.agents/skills/this-or-that/SKILL.md`) runs the same loop and pulls this exact kit from `https://gentle-lasso-9d5n.here.now/kit/`. Both artifacts are published on this site as machine-fetchable attachments (the `?raw` suffix is required — the bare `.md` URL serves an HTML viewer): the flow at `https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw` (fetch it into `flows/this-or-that.md`; it @-imports two taste-record files by relative path — point those at your own `RESULTS.md` files outside the workshop repo), and the skill at `https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw`. Skill install: `mkdir -p skill-src/this-or-that && curl -fsSL "https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw" -o skill-src/this-or-that/SKILL.md && npx skills add ./skill-src --skill this-or-that -y` — do NOT stage in a dir named `skills/`; the skills CLI claims that name as its own symlink target and installs an empty skill. Proof it works: a second real round (13 authoring formats, 27 votes) chose the Session Replay + Socratic Dialogue page pair now used across the workshop sites — replayed at `https://gentle-lasso-9d5n.here.now/replay.html`.
- **Known failure modes:** port already in use → pass another port (`python3 server.py 8481`) and use that URL everywhere; `votes.jsonl` missing → no votes have been cast yet (the file is created on first POST); a duel pane is blank → that option's `src` path in `options.json` is wrong (paths are relative to `this-or-that/`).

## Original references

- [Turn preference into reusable decisions](https://gentle-lasso-9d5n.here.now/)
- [Public setup contract](https://gentle-lasso-9d5n.here.now/agent.md)
