mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-11 12:07:48 +01:00
Krzysztof kuhy Rudnicki
af3c98a50e
Some checks failed
dependency freshness / dependencies on newest stable (push) Waiting to run
file length / file-length (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
palette drift / palette (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
shared gate tests / gate unit tests (push) Waiting to run
crdt_sync_dart tests / test (push) Has been cancelled
crdt_sync_flutter tests / test (push) Has been cancelled
music_theory tests / test (push) Has been cancelled
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
166 lines
8.7 KiB
Markdown
166 lines
8.7 KiB
Markdown
# 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.**
|