# Dopamine UX — session prompts

Ten pasteable prompts derived from *"The Dopamine Architecture: How UX Designers
Hold User Attention in 2026"* (london-post.co.uk), applied to kuhy's repos.

Paste **one file's contents** into a fresh Claude session. Each is
self-contained: it restates the findings it depends on, so no session needs the
context of another.

## The two tests — every change must pass both

The article's four mechanics (variable rewards, micro-animations, sound design,
near-miss) are in scope, aimed at **kuhy's own stated goals**. They are gated by
two questions, not by an allow/deny list:

1. **Is the displayed state true?** A progress ring at 93% is legitimate *iff*
   you are actually at 93%. A streak is legitimate iff it counts real days.
   Dopamine may come from framing, timing and salience — **never from a
   fabricated number**.
2. **Is the variance real?** A random pick from a real pool (next workout, next
   task) is legitimate. Injected random bonus points to manufacture uncertainty
   are not.

### The load-bearing corollary

**Reward the recording, never the number recorded.** In diet-guard the
satisfying moment fires on *logging a meal*, not on hitting a calorie target —
otherwise the app rewards eating less rather than recording honestly, and
corrupts its own data. Same shape in workout_app (reward logging a workout, not
beating a PB) and todo (reward capture, not completion count).

## Running order

`01` gates everything. `07` gates `08`. Everything else is independent.

| # | File | Repo | Findings |
|---|---|---|---|
| 01 | `01-motion-tokens.md` | `~/src/utils` | 3 |
| 02 | `02-structural-check.md` | `~/src/utils` | 2 |
| 03 | todo note `85ca329b-9809-412c-a47f-eddf055322cf` | `~/src/diet-guard` | 4 |
| 04 | todo note `73a20837-6480-4b31-b966-1898a4e7272e` | `~/src/screen-locker` | 3 |
| 05 | todo note `e50d6a03-ae7d-4da5-bbd3-c33b17f6f074` | `~/src/screen-locker/stronglift_replacement/workout_app` | 4 |
| 06 | `06-todo.md` | `~/src/todo` | 3 |
| 07 | `07-dufs-theme.md` | `~/src/dufs-cloud` | 2 |
| 08 | todo note `e301e090-b2ee-4e26-8387-00f356b63521` | `~/src/dufs-cloud` | 4 |
| 09 | todo note `9e1e4922-9f29-4bad-bcf4-96826aa8ffa4` | `~/src/wake-alarm` | 2 |

**27 ranked findings total.**

### Dependency graph

```
01-motion-tokens ──┬─→ 03, 04, 05, 09   (transcribe tokens locally)
                   ├─→ 06               (bump design_system-v0.2.0)
                   └─→ 07 ─→ 08         (bump web_ui-v0.3.2)
02-structural-check  (independent; run after 01 so it has motion tokens to check)
```

## The top three findings fleet-wide

Ranked by value-over-effort from the survey data:

1. **screen-locker streak render** (prompt 04) — `snapshot.streak` is already
   populated and no renderer reads it. Zero new state, zero conftest change,
   zero new dependency.
2. **diet-guard `_onLogMeal` feedback** (prompt 03) — the flagship case.
   Dependency-free via `HapticFeedback` from `flutter/services.dart`.
3. **workout_app finish-workout cue** (prompt 05) — `audioplayers`, `vibration`,
   the `assets:` block and the VIBRATE permission are **already present**. Only
   the call is missing.

## Distributed copies, and the completion protocol

Each prompt is **also copied into the repo it acts on**, at
`<repo>/prompts/dopamine-ux-*.md`, so you can open a repo and say
"do dopamine-ux-<name>" without going hunting. **This directory stays the source
of truth** — if a prompt needs correcting, fix it here and re-distribute.

| Prompt | Distributed to |
|---|---|
| 01 | `~/src/utils/prompts/dopamine-ux-01-motion-tokens.md` — deleted (done) |
| 02 | `~/src/utils/prompts/dopamine-ux-02-structural-check.md` |
| 03 | `~/src/diet-guard/prompts/dopamine-ux-diet-guard.md` |
| 04 | `~/src/screen-locker/prompts/dopamine-ux-04-screen-locker.md` — deleted (done) |
| 05 | `~/src/screen-locker/prompts/dopamine-ux-05-workout-app.md` — deleted (done) |
| 06 | `~/src/todo/prompts/dopamine-ux-todo.md` |
| 07 | `~/src/dufs-cloud/prompts/dopamine-ux-07-theme.md` |
| 08 | `~/src/dufs-cloud/prompts/dopamine-ux-08-motion.md` |
| 09 | `~/src/wake-alarm/prompts/dopamine-ux-wake-alarm.md` |

When a session finishes a prompt it **deletes its repo copy** (in the same
commit as the implementation) and **appends a row below**. A finished prompt left
in a repo is indistinguishable from a pending one, and the next session re-runs
it. Partial completion is never recorded as DONE — the file is edited to state
what remains instead.

### Completion log

| Prompt | Status | Impl commit | Note |
|---|---|---|---|
| 01-motion-tokens.md | DONE 2026-08-22 | `f741896` | `motion.md` frozen; `AppDuration`/`AppCurve` + `--duration-*`/`--ease-*` shipped. Tags: `design_system-v0.2.0`, `web_ui-v0.3.2`. |
| 02-structural-check.md | not started | — | — |
| todo note `85ca329b-9809-412c-a47f-eddf055322cf` | not started | — | — |
| todo note `73a20837-6480-4b31-b966-1898a4e7272e` | DONE 2026-11-01 | `89c65bd` | Status window `_section_streak` + week-transition reward text (kept in `extra_benefits_state.json`); the dead 09:00 early-bird claim is not shown. Per kuhy: no daily-streak state, no shutdown time, no freezes. Commit is on a worktree branch, unpushed. |
| todo note `e50d6a03-ae7d-4da5-bbd3-c33b17f6f074` | DONE 2026-11-01 | `e938201` | Set/warmup `selectionClick`, finish `mediumImpact` + generated chime (music_theory, pinned tag) + dialog arrival, `AppDuration`/`AppCurve` in theme.dart, streak counts up, reduced motion honoured, one Settings "Sound" switch for chime and break-end (foreground service too). Worktree commits, unpushed; `62c1c2c` covers old export/import gaps. |
| 06-todo.md | PARTIAL 2026-11-02 (step 1 DONE; step 2 sound REJECTED by kuhy) | `kuhyx/todo-app 2ffae26` | haptic + checkmark on capture, appRoute motion tokens, animated wizard bar; no sound by decision |
| 07-dufs-theme.md | not started | — | — |
| todo note `e301e090-b2ee-4e26-8387-00f356b63521` | not started | — | — |
| todo note `9e1e4922-9f29-4bad-bcf4-96826aa8ffa4` | not started | — | — |

## Keeping these prompts honest

Every path and symbol cited across these files is machine-checked:

```
python3 ~/src/utils/dopamine-ux/verify_prompts.py
```

Exit 0 means every cited path resolves and every cited symbol is still greppable
in the file it is attributed to. **Re-run it after any refactor of the surveyed
repos** — a prompt pointing at a renamed function is worse than no prompt, and a
path check alone cannot catch that (which is why it greps symbols too).

Verified 2026-08-16: 146 paths, 30 symbols, all passing.

## Rules that apply to every prompt

1. **Tag cuts and version bumps are explicit steps.** `todo` consumes
   `design_system` at git ref `design_system-v0.1.0`; `dufs-cloud/web` consumes
   `@kuhyx/web-ui` at `web_ui-v0.3.1`. Adding tokens to those packages does
   nothing for consumers until a new tag is cut. Prompt 01 ends by cutting
   `design_system-v0.2.0` and `web_ui-v0.3.2`; prompts 06 and 08 begin by
   bumping to those literal refs.
2. **Anchor on symbols, not line numbers.** Line numbers in these prompts are
   "as of 2026-08-16" and will drift. The symbol name is the real anchor —
   grep for it rather than trusting the line.
3. **Reduce-motion is mandatory and is NOT the sound toggle.** Web:
   `@media (prefers-reduced-motion: reduce)`. Flutter:
   `MediaQuery.of(context).disableAnimations`. The OS motion preference is
   honoured automatically; the sound opt-out is a separate user-facing toggle.
4. **Motion and haptics first, sound second.** Haptics need no dependency;
   sound needs a pubspec dep, an `assets:` block, and a settings toggle. Each
   prompt stages them separately so a short session still lands the valuable
   half, and sound stays independently revertable.
5. **Sound ships on (opt-out), never in screen-locker enforcement paths.**
6. **250-line cap** applies to code and prose alike (`~/src/utils/file_length`).

## Source

Article findings, verbatim from the piece:

- **Variable reward schedules** — unpredictable outcomes produce stronger
  dopaminergic activity than guaranteed ones. Duolingo streaks, feed ordering,
  pull-to-refresh.
- **Micro-animations** — "a button that bounces on press, a like counter that
  ticks upward with a slight delay". Replaces latency with feedback, so waiting
  reads as responsiveness rather than frustration.
- **Sound design** — "operates below the threshold of conscious attention";
  the article's judgement is that it is more powerful than visual design and
  gets less critical attention.
- **Near-miss effects** — a fitness ring at ninety-three per cent creates
  discomfort that drives re-engagement, and works *even when the user is
  explicitly told the mechanism*.
- Core claim: **dopamine is released in anticipation of a reward, not on
  receipt. The uncertainty is the trigger.**