Health Diary — How a Patient Actually Uses It
Issue: #2291 Status: Built, pending manual QA. What a patient sees is written up in the user guide. Companion docs: Product spec · Web interface design · Developer guide · QA guide Revised: 2026-09-16 — after product review. Audience settled as general app users; purpose settled as making care available, not selling it; voice confirmed as polish, not core; assumptions in §9 accepted as design decisions since the platform is pre-launch.
The product spec says what we promise. This says how a real person reaches for it, where it will be hard for them, and what we do about that. §7 lists the changes this makes to the design we already have.
0. The purpose, stated plainly
The chat is where a person arrives at the decision to ask for help. Our job is to make that help available immediately — not to sell it.
This is not a distinction of tone; it changes what we build and what we count.
| Because it is not a funnel… | …this follows |
|---|---|
| "See a doctor" is offered when it helps, not when it converts | The assistant must be free — and visibly willing — to say "this doesn't need a doctor". That answer is the one that earns the trust that brings people back. |
| The next step is about removing friction, not capturing intent | Once someone has decided they want help, the number of taps between that decision and care being arranged is the thing to minimise. |
| CTA tap-rate is the wrong success metric | It is a conversion number. Optimising it would quietly turn this into the funnel we said we didn't want. §8 measures availability, not uptake. |
1. The six moments someone opens this
Not personas — moments. The same patient hits several across a year.
| # | Moment | What they need | How much they'll type |
|---|---|---|---|
| M1 | The 11pm worry. Something hurts, the clinic is shut, they're alone with it. | To stop spiralling. To know if this can wait until morning. | One sentence, badly spelled. |
| M2 | "Is this worth a doctor?" | An OPD visit costs money, travel and half a working day. This is a budgeting decision as much as a medical one. | A sentence or two, calmer. |
| M3 | Before a visit. They want to remember everything that's happened. | A list they can hand over. | More — there's a payoff. |
| M4 | After a visit. New medicine, three weeks of "is this working?" | Somewhere to note the dizziness came back. | Short, repeated, low drama. |
| M5 | Caregiving. A daughter phones her mother daily and records what she hears. | To keep a record for someone who won't keep one. | Third-person, typed by someone fluent. |
| M6 | Living with something. Diabetes, back pain, migraines. | To see a pattern, and feel less alone with it. | Habitual, brief. |
The uncomfortable observation
We designed for M1 and M2. Retention lives in M3, M4 and M6 — and those currently sit behind a History tab with folder and date filters, which is a thing product teams build and patients don't open. §7 acts on this.
2. What a first session actually looks like
Ninety seconds, on a phone, one-handed, in bed.
opens app → sees something that invites a sentence → types it
│ │
│ (3–8 seconds of waiting)
│ ▼
└──────────── reads ~4 lines ───────────────► leaves with one of three things:
"I'll sleep on it"
"I'll book tomorrow"
"I need to go now"Everything else — thread, folder, diary entry, tags — happens around them without being asked for. The patient's job is one sentence and one decision. The rest is our bookkeeping, and it stays invisible at capture time.
3. The arc that decides whether this succeeds
Session 1 the gap Session 2 habit
───────── ─────── ───────── ─────
M1 crisis → 2–6 weeks → ??? → M3/M4/M6
one message nothing this is where
one answer happens the product
leaves lives or diesThe audience is general app users, not the subset with appointment history — so the return trigger cannot depend on us knowing they have a visit booked. It has to be created inside the conversation itself.
| Trigger | Works for everyone? | Assessment |
|---|---|---|
| The invitation inside the answer — "if it's not better by Friday, tell me and we'll look again" | ✅ Yes | The one to build first. It costs nothing, it is already half-present as the clinical tripwire (§6.6), and it makes the assistant — not a notification — the thing that asks them back. It also sets a date, which is what turns "maybe later" into a return. |
| The dashboard card | ✅ Yes | Passive, but it is on the one screen they see whenever they open the app for any reason. Already planned. Cheap. |
| A follow-up nudge — "how's the headache?" three days later | ✅ Yes | Now more important than it was, since the appointment trigger doesn't generalise. Highest value, highest risk: needs the opt-out and content rules already written into the notification design. |
| An appointment-linked prompt | ❌ Only the subset who book | Still worth doing for those who have one — but it is a bonus, not the mechanism. |
The move: the answer itself sets the return date. The notification, when we build it, just honours a date the patient already agreed to — which is a very different thing from us deciding to ping them.
4. Who is on the other end
Reasoned from what we know, not from research (§9 lists the checks).
- On a phone, on mobile data, one-handed. Web is the minority case.
- Often typing in Latin script regardless of the language they think in. "sar dard ho raha hai" is how a great many people actually type Hindi. This matters more than it looks — see §6.3.
- Frightened, and text is how we set the tone. A clinical wall of bullets at 11pm reads as a machine covering itself.
- Doing a cost calculation. "See a doctor" is a recommendation to spend money and a day.
- Some of what they want to write is embarrassing. Sexual health, mental health, alcohol, money worries. If they doubt who can see it, they won't write it.
- Possibly new to Kulcare entirely. General app users means the diary may be someone's first real interaction with us — with no clinic history, no doctor relationship, and no reason yet to trust us. §7 C5 covers what that implies.
- A meaningful share are caregivers, writing about a parent in the third person.
5. Where it will be hard for them
Ranked by how many users each one loses.
| # | Friction | Why it kills usage |
|---|---|---|
| F1 | Writing in their own language | The barrier arrives before the value does. Note this is writing, not only typing — see §6.3. |
| F2 | Blank-box paralysis | "Tell us how you're feeling" is an essay prompt. People don't know what to say, how much, or in what order. |
| F3 | The answer is a hedge | "Consult a healthcare professional" with nothing else is what people already expect from health apps, and why they distrust them. A safe answer that helps nobody is still a failure. |
| F4 | Too much text | Four lines get read. Twelve get skimmed. Twenty get abandoned — especially in a second language, at night. |
| F5 | Filing before writing | Asking "which folder?" before they've said anything puts admin in front of help. |
| F6 | Not knowing who can see it | Uncertainty is answered by writing less — about exactly the things that matter most. |
| F7 | The wait | 3–8 seconds of nothing, on bad data, looks like a hang. |
| F8 | Writing into the wrong diary | A caregiver with two contexts recording their own headache in their mother's record. Quietly corrupts the thing we're asking them to trust. |
| F9 | Forgetting it exists | The commonest failure, and the one that looks like nothing is wrong. |
6. Twelve moves that make it easy
At the front door
6.1 · Never show an empty composer. (F2) Four one-tap starters drawn from what people actually arrive with — Fever · Headache · Stomach pain · Can't sleep — plus "Something else". A tap opens a thread with that as the first message. The blank page is the enemy; a tap is a start. Source the four from our own appointment data, not from intuition (§9).
6.2 · Zero filing at capture time. (F5) Never ask for a folder before a message. Everything lands in General; the assistant offers to organise afterwards, one tap, reversible. Folders are a reward for coming back, not a toll on arriving.
6.3 · Understand people who write their language in Latin script. (F1) — new, and the cheapest big win here Voice is confirmed as polish (§7 C3), which leaves typing as the front door for launch — so the typing door has to be wider than "type in Devanagari". A large share of users write Hindi, Tamil or Malayalam in Latin characters. That input must be understood, and the reply must come back in the same script the patient used — romanised in, romanised out. Someone who writes "sar dard" should not receive a paragraph of Devanagari they find harder to read than what they typed.
This needs no new infrastructure: it is prompt and language-detection work inside the chat unit, and it does for the typing barrier much of what voice will later do — at a fraction of the cost.
In the answer
6.4 · Four lines, then stop. (F4) Cap the visible answer; longer content sits behind "More detail" that most people won't open, which is fine — they didn't want it.
6.5 · One follow-up question, not five. (F4) "How bad is it out of ten?" is answerable. A five-point checklist is an interrogation.
6.6 · Always give a tripwire — and a date. (F3, F9) The most useful thing a good clinician says is "if this happens, come back straight away." Every answer should leave the patient with a concrete rule — "if the pain reaches your jaw or arm, get help now" — and, where it fits, a time: "if it's no better by Friday, tell me." One sentence doing two jobs: it converts a summary of possibilities into a decision, and it is the return invitation from §3.
6.7 · Be willing to say "you don't need a doctor for this." (§0, F3) If everything is pointing to rest and fluids, say so plainly — with the tripwire attached. An assistant that recommends a consult every time is a funnel wearing a stethoscope, and people recognise it immediately. This is the single clearest expression of the purpose in §0.
6.8 · Respect what a visit costs. (F3) When we do suggest seeing someone, say what kind and how urgently — "a GP this week" reads very differently from "consult a healthcare professional." Where a teleconsult genuinely would do, say so: it is cheaper and faster, and we have one. This is friction removal, not upsell.
Around the writing
6.9 · Name whose diary this is, in the composer itself. (F8) When a caregiver is switched in, the placeholder reads "Tell us how Amma is feeling" — not just a banner at the top of the page that goes invisible after a week. The reminder belongs where the typing happens.
6.10 · Say plainly who can see it. (F6) One line, once, on first use: only you (and anyone you've added as a caregiver) can read this. Nobody at a clinic sees it. Then a visible delete on every entry. Control is what makes the claim believable — and for a first-touch user it is the whole basis of trust.
6.11 · Make the wait honest and escapable. (F7) Because the message is saved before the model is called, we can say so: "Saved — getting you an answer." If they close the app, nothing is lost and the answer is waiting.
Bringing them back
6.12 · Turn the record into something they can use. (F9, M3) A short, printable "what to tell your doctor" — printing it now produces the summary on its own, not the whole page: dates, what they reported, what changed, current medicines. It is what makes the 11pm scribbles worth having written, and it is the bridge from M1 to M3. Patient-held — it does not break the v1 rule that no clinician sees the diary.
7. What this changes in the design we already have
| # | Change | From → to | Status |
|---|---|---|---|
| C1 | The summary becomes a pre-visit handout | GET /summary?days=30 currently reads as a wellness recap. Same endpoint, different framing and copy: "What to tell your doctor" — ordered as a clinician would want it, printable and shareable by the patient. The API barely changes; the product changes a lot. | Approved |
| C2 | "Before your visit" replaces the History archive | Lead with the purpose-built view; keep filtered browsing underneath for the minority who want it. For users with no visit booked it reframes as "your health story so far" — same content, same value. | Approved |
| C3 | Transliteration in the core build; voice in polish | Voice stays in its planned phase. In its place, the chat unit handles Latin-script Indic input and mirrors the patient's script in the reply (§6.3). When voice does land, the ASR choice should be revisited against the Deepseek/ASR stack rather than defaulting to Deepgram — that stack handles transcription, translation and transliteration together. Note: no Deepseek integration exists in this repo; its details need confirming before the provider decision (D-3) is closed. | Revised |
| C4 | The answer sets the return date; appointments are a bonus | The in-conversation invitation (§6.6) is the primary Session-2 mechanism because it works for every user. The appointment-linked prompt stays as a secondary trigger for the subset who book. | Revised |
| C5 | Design for a cold start | General app users means many patients arrive with no patient.* history and no doctor relationship. The prompt builder must produce a good answer from zero context, and the care CTA must lead somewhere useful for someone who has never seen a Kulcare clinician — discovery, not "your doctor". | New |
Deliberately unchanged: folder CRUD stays in the API — mobile needs it and M6 users do organise — but the UI never demands it. Build the capability; don't spend the patient's attention on it.
8. What "working" looks like
Framed as availability, not uptake — per §0. Each line is the observable behaviour, not the KPI.
| If this is working… | You'd see |
|---|---|
| People leave with a decision | Answers that carry a concrete tripwire, and sessions that end in an action or a stated plan rather than a silent close. |
| Care is available, not pushed | A healthy share of answers that say no consult is needed — and those patients returning anyway. If that share is near zero, we have built a funnel. |
| Friction is gone for those who want help | Time and taps from "I want to see someone" to an appointment existing. |
| It brings them back | Second session within 30 days — the single number to watch — and return rates against the dates the assistant itself suggested. |
| It's usable by people who don't write in English | Share of first messages in Latin-script Indic input, and whether those threads continue to a second turn at the same rate as English ones. |
| The record earns its keep | Pre-visit handouts opened — and, later, whether patients say they used one. |
| It's trusted with the hard things | Entries about topics people don't raise casually. |
| It isn't frightening people | Emergency guidance shown rarely, and acted on when it is. |
9. What we are assuming — and how v1 answers it
There is no production data to check against. This platform is pre-launch: the local database holds 18 seeded users and zero appointments. Every assumption below is therefore a design decision we are making deliberately, not a finding — accepted as the basis for v1 (product review, 2026-09-16).
Being pre-launch is not a reason to guess and move on. It is a reason to build v1 so that it answers these questions for us, rather than leaving us still guessing in six months.
| # | Assumption we are proceeding on | How v1 answers it |
|---|---|---|
| A1 | A large share of users write their language in Latin script | Record the detected script and language of every first message. The answer arrives in the first fortnight of real use. |
| A2 | Four starter chips cover most arrivals | Record which chip was tapped, or that "Something else" was. The tail names itself. |
| A3 | Caregivers are a meaningful share | Record whether the message was written on behalf of someone. We already carry the actor and subject on every row — this is free. |
| A4 | The late-evening worry is the dominant trigger | Message timestamps give it away immediately. |
| A5 | People want a "tell your doctor" handout | Count handouts opened, and ask a handful of users directly once there are some. |
9.1 What this costs us now
Almost nothing, if we do it while the schema is being designed rather than after.
languageand the detected script already belong onhealth_diary_messages(A1).- One
entry_pointcolumn onhealth_diary_threads— chip, free text, dashboard card, voice — covers A2 and gives us the dashboard card's own conversion for nothing. - A3 and A4 need no new columns at all:
recorded_by_user_id ≠ user_idandcreated_atalready carry them.
Adding a column now is free. Adding it in three months is a migration and a backfill we cannot do, because the data was never captured.
9.2 The one assumption we can retire today
A2 has a better answer than intuition. reference.complaints already ships seeded with a
curated clinical list — Fever, Headache, Abdominal Pain, Cough, Sore Throat, Back Pain, Nausea,
Dizzy, Chest Pain, Fatigue, Joint Pain, Shortness of Breath… Source the starter chips from that
list rather than inventing four, and the clinical vocabulary matches what the rest of the product
already uses. (Drop the ones that are diagnoses rather than complaints — Diabetes, Hypertension,
Pancreatic Cancer are in that table and are not things a patient arrives saying.)
9.3 What being pre-launch changes elsewhere
| Consequence | So |
|---|---|
| No production feedback loop to catch a bad answer | The clinician review of sample answers per language, per the product spec's launch gate, is now the only quality check before real patients see it. It moves from "important" to "the thing standing between us and a bad first impression." |
| The team is the only user we have | The web surface built for debugging is also our evaluation environment. That raises its priority: it is where answer quality gets judged before launch, not just where requests get inspected. |
| Nothing is locked in by existing clients | The contract divergences can still be settled the cheap way. Worth re-asking whether the mobile client has actually been written against the proposed shapes yet. |
| No history to migrate | Confirmed 2026-09-18: the on-device chat in the mobile app was a prototype built to test the hypothesis, not a shipped feature with users. Nothing needs importing, and promise P5 starts clean rather than starting broken. |
10. One thing to hold on to
A patient at 11pm is not looking for information. Information is free and they have already searched it — that is precisely why they are frightened. They are looking for someone to tell them what to do next, in a way that respects that they cannot casually spend a day and a thousand rupees finding out. And sometimes what they need to hear is that they don't have to.
Everything in §6 is downstream of that. If a design decision makes the next step clearer, it is right. If it adds a field, a folder, a paragraph or a caveat, it is probably wrong.