Restep

A daily check-in for parents of a concussed child. Today's symptoms become today's plan, and every advice card cites the guideline sentence it came from.

Comment

The problem

A child gets a concussion. The emergency department sends them home the same night with a printed sheet. Then the parent is alone with it: is today a school day or a rest day? Is this headache the normal kind or the kind that means go back to hospital? Is it too early to try a full afternoon of class?

The tools that exist for concussion serve athletes: ImPACT, Sway, CAPT, Complete Concussions. They assume a clinic account, a baseline test, a team, and they are built around return-to-play. The parent at home waiting out return-to-school has nothing that doesn't start with a clinic login.

The evidence they need already exists, in public. The PedsConcussion Living Guideline and the Parachute Return-to-School Strategy it hosts are written by clinicians, updated, and free to read. They are also 200 pages of clinical prose organised by recommendation number, not by "what do I do tonight".

What Restep does

Restep is one check-in a day, and it turns that check-in into today's plan.

The parent taps today's symptoms (or types a note in their own words), says whether today is better, the same, or worse than yesterday, and presses Log today. Three cards come back:

  1. Today's load — how much cognitive work today can hold.
  2. The next step — whether it's time to try the next rung of the return-to-school ladder, or hold where they are.
  3. A note for the teacher — print-friendly, listing the accommodations that match today's step.

Every card carries a citation pill. Tapping it opens the guideline sentence that card was built from, in place, without leaving the page. The full guideline text is readable inside the app.

And when the parent reports something on the red-flag list — repeated vomiting, worsening headache, double vision — the advice stops. A full-screen emergency instruction takes over the app, with the medical contact path. No cards, no pacing advice, no "here are some things to consider".

Why the red-flag path is a rule and not a model

The red-flag check is a fixed list of 11 signs from Recommendation 1.3, evaluated by set intersection. Not a prompt, not a classifier, not a threshold.

The AI in this app can raise an alarm — a free-text note gets classified into the same symptom inventory, and that classification feeds the same rule. It can never lower one. There is no code path in which model output suppresses an escalation. The free-text note is also scanned for red-flag phrasings by a deterministic keyword pass before the model is called, so the emergency path does not depend on the model, the API key, or the network being up.

That is the whole design position: when the stakes are a child's brain, the thing deciding whether tonight is an emergency should be something you can read, test, and mutate.

Where AI runs, and where it does not

Runs in exactly one place: classifying a caregiver's free-text note ("he threw up twice and the light is bothering him") into the fixed symptom inventory. Its output passes a whitelist gate — anything outside the inventory is dropped — and then the same deterministic red-flag check as tapped chips.

Never runs in: red-flag detection, advice selection, ladder progression, or the teacher note. Those are lookup tables and rule evaluation over guideline text. Moving up a ladder step is a button only the caregiver can press; the app can suggest it, never do it.

With no API key at all, every feature still works — the note is stored as written.

symptom chips ─────────────┐
free-text note → deterministic keyword scan ───────┤
               └→ LLM classifier (whitelist-gated) ─┤
                           ▼
              deterministic red-flag check ← 11 flags, Rec 1.3 (AI cannot reach past this)
                 │ hit → full-screen escalation, no cards
                 ▼ miss
              lookup engine: (ladder step × symptom trend) → cited advice cards
                 ▼
              cards from guideline text templates (no generation)

Evidence

Guideline-derived holdout — 12 scenarios, 12/12 pass. Each scenario's expected outcome is checkable against a cited recommendation, including a red flag arriving while every other input looks routine, and red flags mixed with ordinary symptoms. All 4 red-flag scenarios escalate. A red-flag miss exits non-zero: it is a blocker, not a statistic. Run it yourself: python3 eval/run_eval.py.

Against a vanilla frontier chatbot, same 12 scenarios phrased the way a parent would ask:

Axis Vanilla LLM Restep
Red-flag scenarios escalated 4/4 4/4
Replies citing a checkable source 0/12 12/12
Guideline-concordant pacing on a "clearly worse" day 1 of 8 normal scenarios pushed toward same-day medical contact pause, adapt, retry tomorrow (the guideline's actual instruction)
Same input → same advice not guaranteed always

The honest finding: a frontier chatbot does not miss emergencies. That is not where the gap is. The gap is verifiability — which sentence is guideline and which is improvisation. A scared parent cannot tell, and the chatbot cannot show them. Restep's answer to that is structural.

27 tests, mutation-checked: emptying red-flag matching, breaking the stability threshold, and removing the whitelist gate each turn the suite red.

Designed for the patient, not for engagement

The users are a hurt child and a worried parent, so the interface follows the patient's constraints: low stimulus, large type, no animation, short lines. Advice arrives as warm storybook pages with one illustrated scene each, not a dashboard.

One check-in a day. No streaks, no scores, no badges, no "7-day recovery challenge". Recovery is not a competition, and an app that makes a concussed child feel behind schedule is doing harm.

Data

One diary per case id, in the app's own SQLite database, created where the app is run. Entries are never pooled across users and never used for training. When the optional note classifier is enabled, the note text is sent to the model provider for that classification — this is stated in the app and in the README.

Limits, stated plainly

Restep supports professional medical care and does not replace it. It does not diagnose concussion, prescribe treatment, or clear anyone for sport. It runs locally from the repository: there is no hosted instance, no rate limiting, and case ids are enumerable. Ladder step is held in browser storage.

Running it

pip install -r requirements.txt
python3 -m uvicorn app.main:app --port 8321

Opens with a pre-seeded demo diary (day 6, ladder step 2), no login. GEMINI_API_KEY is optional; without it, notes are stored as written and every other feature is unchanged.

Sources

Guideline excerpts are reproduced without changes and attributed as the source's disclaimer directs.

Built With

Share this project:

Updates

Submission history