Build Log

Known UX pass — getting ready for Jan

July 2, 2026

Reframed Known's language from backward-looking to present-tense, fixed a broken-promise button flow, and built a zero-effort way to surface repeated daily notes onto the Known Card.

KnownUXCrucibleCopy

Crucible customer/UX rounds run

files changed

new schema table

new API routes

deployed to production

Timeline

Start

UX pass on Known ahead of Jan's first use

Zeb flagged 'Add a Memory' / 'Add from a Conversation' as backward-looking

Round 1-4

Crucible customer persona on real page copy

Home buttons, portrait page, Known Card fill-in-the-blank framing

Mid

Copy sweep applied across 4 files

Present-tense language, 'When confused, try' reordered to position 2

Turn

Zeb caught 7 entry points routing to one generic flow

Screenshot-driven finding — empty state had 8 differently-worded promises, all identical destination

Fix

Collapsed to 2 honest entry points

'Share what to avoid' now actually jumps to what_hurts questions via startCategory param

Turn 2

Zeb asked what happens to notes after 7 days

Found they vanish from every UI surface permanently, though the data persists

Build

Past notes view + repetition-flag suggestion system

Crucible (ux persona) design review before building the auto-surface mechanism

Retro

Session retro written, Crucible wrap run, closed

First retro pass — engine-health A (87), one gate_checks gap caught and fixed

Deploy

Zeb asked to deploy Known to production

Deploy Gate run; prod schema push hit the same env-precedence bug from Chapter 3, this time blocking the deploy outright

Fix

Found and fixed the real root cause

drizzle.config.ts unconditionally reloaded .env.local — fixed to only fall back when DATABASE_URL isn't already set

End

Known live at known.forgekits.build; retro updated to reflect the resolved spin

s2/s3 moved from deferred to a real prevention artifact, not left open

What shipped

Present-tense copy sweep across home screen, portrait page, Known Card, and HelperPanel — replaced backward-looking labels ('Add a memory', 'Add from conversation', 'Helper notes') with forward-looking ones

Reordered Known Card sections so 'When confused, try' (the highest-stakes line for a stranger in a crisis) moved from position 6 to position 2

Collapsed 8 empty-state entry points (3 buttons + 4 prompt cards, all routing to the same generic question 1) down to 2 honest ones

Added startCategory routing so 'Share what to avoid' actually jumps the capture session to what_hurts questions instead of dropping at question 1 of 24

Added a welcome-screen intro line that confirms what the user asked to share, when a targeted entry point was used

Built a 'Past notes' collapsed view so handoff notes older than 7 days stop disappearing from the UI forever (data was already persisted, just never re-shown)

Built a repetition-detection suggestion system: when a keyword recurs across 3+ daily notes, Jan sees a single dismissible one-tap suggestion to add it to the Known Card — accepting promotes the notes into a real memory entry + draft enrichment via the existing review pipeline, never auto-writing to the card

Deployed the full session's work to production at known.forgekits.build, including a prod schema push for the new table

Fixed drizzle.config.ts to stop unconditionally overriding an already-set DATABASE_URL — the actual root cause of two separate spins this session, in both the dev and prod direction

“how can we do this without causing more actions on the users part (Jan)?”
— Zeb, shaping the note-suggestions feature — the constraint that ruled out manual tagging and pointed toward repetition-detection