Concussion Recovery Pacer

Patient submits daily symptoms via Google Sheet — pipeline checks for red flags, matches CDC HEADS UP protocol, and delivers a personalized recovery plan to their inbox in 60 seconds.

Comment

Inspiration

1 in 4 concussion patients develops post-concussion syndrome — symptoms lasting months beyond the typical 2-4 week recovery window. The cause is almost always poor pacing: patients return to screens, exercise, or school too soon because nobody told them not to.

The CDC HEADS UP return-to-activity protocol is the clinical gold standard. It is public domain. It is free. It is specific: 5 stages, clear criteria for each. Nobody has built a daily delivery system around it.

I built Concussion Recovery Pacer to give every concussion patient a structured daily companion — protocol-grounded, red-flag-aware, and delivered to their inbox without requiring a clinician for routine days.

What it does

A patient or caregiver fills a Google Sheet each day — symptom score (0-10), screen time, sleep hours, exercise attempted, vomiting, vision changes, notes.

When a new row is added, the n8n pipeline fires:

  1. Red Flag Checker (deterministic IF node) — if symptom score 8 or above: immediate emergency alert email with CDC red flag symptoms, 911, and Concussion Alliance contacts. No LLM is called. No ML. A deterministic rule routes the highest-risk cases to care.

  2. GPT-4o-mini Agent (normal path) — receives patient data plus the full CDC HEADS UP 5-stage return-to-activity protocol inline. Determines the correct stage based on day number and symptom score. Generates a 2-3 sentence personalized recommendation citing the protocol stage by name.

  3. Structured output parser — enforces JSON schema: activity_level, activity_label, recommendation, protocol_stage, protocol_source, next_step, encouragement.

  4. HTML email delivery — color-coded by protocol stage. Stage 1 (red): complete rest. Stage 2 (orange): light aerobic. Stage 3 (yellow): sport-specific. Stage 4 (green): non-contact. Stage 5 (navy): full return with medical clearance.

End to end: under 60 seconds from sheet row to inbox.

How I built it

Stack:

  • n8n (cloud) — 12-node workflow, fully visual and inspectable
  • GPT-4o-mini — fast, cheap, 2-3 sentence outputs, temperature 0.2
  • OpenAI text-embedding-3-small — RAG embeddings for protocol KB
  • Google Sheets — patient daily check-in form (trigger)
  • Gmail — daily recovery email delivery

Red flag logic (deterministic, not ML):

IF symptom_score >= 8 → Emergency Alert → STOP ELSE → Pacer Agent → Build Email → Deliver

CDC HEADS UP staging (inline in agent prompt):

Stage 1 (days 1-2, score 7-10): Complete rest Stage 2 (days 3-5, score 4-6): Light aerobic 20-30 min Stage 3 (days 6-8, score 2-4): Sport-specific, no contact Stage 4 (days 9-12, score 0-2): Non-contact drills Stage 5 (day 13+, score 0): Full return, medical clearance required

Agent output fields: activity_level, activity_label, recommendation, protocol_stage, protocol_source, next_step, encouragement

Challenges I ran into

  1. Agent max iterations — RAG tool calls inside the agent caused iteration exhaustion. Fixed by moving the CDC protocol inline into the system prompt so the agent never needs to call the tool for routine staging decisions.

  2. Red flag determinism — the hardest design decision was keeping the safety gate as an IF node and not letting the LLM make the routing decision. The LLM could hallucinate a safe score. The IF node cannot.

  3. Email color-coding — mapping protocol stages to colors dynamically required a lookup in the Build Email code node, since n8n email templates do not support conditional styling natively.

Accomplishments that I'm proud of

  • 12-node pipeline running end-to-end — Google Sheets to inbox in under 60 seconds
  • Deterministic red flag detection — IF node, not ML, routes highest-risk cases
  • GPT-4o-mini staging all 5 CDC HEADS UP return-to-activity stages correctly
  • Both email paths working: emergency (coral red) and pacing (color-coded by stage)
  • Patent-safe — no novel architectural claims exposed, safe to publish publicly

What I learned

The most important lesson: the LLM should not make the safety decision. The red flag check is a hard IF node. A patient with a score of 9 gets an emergency email regardless of what the LLM would have recommended. Keeping the safety gate deterministic and the LLM downstream of it is the right architecture for health-adjacent tooling.

The second lesson: inline context beats RAG for small, stable knowledge bases. The CDC protocol has 5 stages. Putting them inline in the prompt is faster, cheaper, and more reliable than a vector store retrieval for every run.

What's next for Concussion Recovery Pacer

  • SMS delivery via Twilio — concussion patients should not be staring at email
  • Clinician dashboard — Google Sheets audit log to Looker Studio trends
  • Multi-language support — CDC HEADS UP is available in Spanish
  • Wearable integration — symptom score auto-populated from Fitbit/Oura heart rate variability
  • Supabase pgvector — persistent RAG store, no reseed on restart

Built With

  • buffalo-concussion-protocol
  • cdc-heads-up-protocol
  • embeddings
  • gmail
  • google
  • gpt-4o-mini
  • n8n
  • openai
  • rag
  • sheets
Share this project:

Updates

Submission history