DESIGN.md

# Design notes

## What this is

A private, low-stakes place to say something complicated out loud about a vote
— before, or instead of, saying it to a person. The model's job is to listen
well, not to adjudicate.

## The naming decision

Nothing in the interface names a candidate, a party, or an election. The
title is *Second Thoughts*; the subtitle frames it as a confidential place for exploring "the complicated feelings that come with second thoughts" and practicing how to put them into words — no diagnosis, no named emotion the person has to claim first

This is deliberate. The people most likely to benefit are the least likely to
click something that announces what they're about to admit — a landing page
that names the thing is a page you don't want in your browser history, or on
your screen when someone walks past. The specificity lives in the system
prompt, where it shapes the model's understanding without being broadcast at
the user.

The system prompt tells the model who tends to arrive here *and* instructs it
never to raise the name, assume the situation, or assume how the person feels
about it. The user introduces the specifics, or doesn't.

## What a good conversation leads to

Not a changed mind, a conclusion, or feeling better by the end. Someone
leaves having said more of the true thing than they could before, in their own
words; feeling met rather than managed; holding the feeling as something they
did rather than who they are; with their choices intact — including never
telling anyone; and, if they want it, a little closer to words they could say
to a person. A conversation where they mostly talked has gone well.

## Conversation craft

Every reply is built from a small set of moves, in rough order of frequency:
receive it plainly, reflect in their words, invite more without asking,
occasionally ask one genuinely open question, wonder aloud tentatively once
they've said a lot, gather it back at a pause, and answer straight when asked.
Replies are short — often one to three sentences — and many don't end in a
question.

Ruled out, because each one narrows what the person can say:

- **Either/or questions and menus of options**, in any mode — including
  offers ("I can do this, or we can do that"). They hand the person your
  categories. The one exception is safety: one plain, direct question about
  suicide, then stop.
- **Naming feelings they didn't name**, and opening with commentary on the
  disclosure ("That sounds…", "That's a lot…"). Both evaluate the person from
  outside and quietly turn them into a case.
- **Stock emotional imagery and therapy-script phrases** — weight, carrying,
  sitting with; "I hear you," "that's valid."
- **Reassurance that settles the question.** "You're not a bad person" is as
  much a verdict as its opposite.
- **Using contradictions as leverage.** Developing discrepancy is how
  motivational interviewing moves people toward change — a persuasion
  technique, which this space has promised not to use.

The prompt avoids quotable example phrases: in testing, any sentence given as
an example came back verbatim. `tools/battery.py` replays scripted
conversations against the live Space and flags regressions.

## Conversational approach

**Reflective, not persuasive.** Motivational-interviewing style: reflect
before adding, ask open questions, let the person voice their own reasoning
and notice their own contradictions. No verdicts, no lectures, no destination.

**Shame vs. guilt.** "I did something that doesn't fit who I want to be" is
workable; "I am fundamentally bad" is not, and produces defensiveness or
shutdown rather than change. When self-punishing language appears, the model
separates the action from the identity. It does not pile on, and it does not
contradict genuine self-reflection either — the goal is proportion, not
absolution.

**Shame resilience, not shame elimination.** The aim isn't to make the feeling
disappear. It's to keep it from generalizing into "I am irredeemable." Shame
survives on secrecy, silence, and judgment; it loses power in the presence of
empathy and being known. That's the mechanism the whole product rests on.

**Neutral language.** The model won't call the user's vote, beliefs, or the
people around them "fascist," a "cult," or "brainwashed" — even when the user
uses that language about themselves. It can acknowledge a framing without
adopting it. Factual political questions get plain factual answers, then the
conversation returns to the emotional thread.

**Autonomy.** No pressure, no timeline, no implied finish line. The model
doesn't assume the user is renouncing anything or wants to be told they were
wrong. Some people just want to be heard.

## The disclosure ladder

Telling people in your life is often the hardest part, and the risk is real —
disclosure like this can cost people marriages and friendships. Treating that
fear as an overreaction is invalidating, so the copy names the risk plainly.

The ladder — journaling → here → one trusted person → wider circle — is
offered as a frame, never a prescription. Talking here is framed as a
legitimate rung, not a lesser substitute for the real thing. Plenty of people
stay on rung 2 indefinitely, and the product does not treat that as failure.

## Scripture reflection

Strictly opt-in. The model never raises religion unprompted and never assumes
the user is religious.

The button is the one starter that *doesn't* disappear once the conversation
begins — it asks the model to reflect on what was already shared, so it only
becomes useful after there's something to reflect on. It docks to the top of
the transcript instead.

When invited, the model quotes only the King James Version (public domain),
picks one to three short passages about grace, healing, or belonging, connects
them to what the person actually said, and stops. It never selects verses to
render a verdict on a political choice, question someone's salvation, or say
what God thinks of a politician. If the framing lands badly, it drops it and
doesn't return to it.

## Safety

Crisis language triggers an immediate shift: calm, stabilizing, and 988
offered proactively rather than on request. The political topic never delays
this. The model does not diagnose, and it does not reinforce shame spirals.

A persistent footer carries 988 and states plainly that this is not a
therapist.

## Privacy

Nothing is persisted. History lives in the browser tab and is posted back each
turn for context; closing the tab ends it. No database, no content logging, no
analytics. This isn't incidental — it's the product. A space that only works
if people say the thing they're afraid to say can't also be quietly keeping
records.

The page is marked `noindex`: findable if you're sent here, not something that
surfaces next to your name in a search.

## Technical choices

**Docker over Gradio.** The design is a specific mobile-first artifact — an
arched, softly lit window, warm paper tones, a deep red that reads as hearth
rather than flag. Gradio's chat components would have meant fighting the
framework for every one of those values. FastAPI serving a static page costs
about the same amount of code and gives the design exactly.

**Streaming.** Replies arrive as they're written. In a conversation like this,
a spinner followed by a wall of text reads as a verdict being handed down; a
reply that appears gradually reads like someone thinking.

**Claude Opus 5 at medium effort.** Low effort was fast but leaned on stock
moves (labeling feelings, either/or questions). Medium follows the subtler
conversational rules noticeably better at an acceptable latency. The system prompt is long, stable, and identical
every turn, so it's marked for prompt caching.

**Rate limiting.** The key is server-side on a public Space. The endpoint is
metered per client (40 messages/hour) so a stranger can't run up the bill.

## Practice mode

"Practice saying it to someone" lets a person try the words out loud and find
out they can get through saying them. That builds capacity to feel what comes
up without being swept away by it. To the person it's never called exposure,
a skill, or distress tolerance; it's just trying it out loud.

It's opt-in and transparent: the steps are shown before anything starts, and
nothing begins until the person presses Begin. The six steps are Who (with a
safety check), Say it, Notice, Steady, Hear back (optional role-play), and
Keep. One step per reply, and they can skip, repeat, or stop at any point.
Stopping is framed as a complete outcome.

**Safety first.** If the person they'd tell sounds threatening or
controlling, the bot doesn't rehearse telling them. It responds warmly, not
as a refusal, and mentions the National Domestic Violence Hotline once.
Distress or crisis drops the steps entirely.

**Role-play is mild by design.** It starts with the most likely reply, never
the worst; plays the other person in a line or two, never cruel and never a
caricature; and steps back out of the role in the same reply. It only goes
harder if the person asks.

**Game elements are gentle, on purpose.** A visible path of six steps, an
optional breathing pace at Steady, and a closing card that shows the words
they tried, with a way to copy them. There are no points, streaks, or scores.
Those would turn shame into a performance and make stopping feel like
failure.

**How it's wired.** The protocol lives in the cached system prompt. While
practice is active, each request adds a mid-conversation system note. The
model ends each reply with a hidden `[[step:N]]` marker, which moves the path.
The client strips the marker from what the person sees but keeps it in
history, so the model always knows where the steps stand.