quill: draft Timmy daily health summary generator spec

wizard-work/quill/timmy-daily-health-summary-draft.md

@@ -0,0 +1,47 @@
+# Timmy — Automated Daily Health Summary Generator
+
+## Problem
+Timmy tracks bowel health in a paper journal. The data is captured but never
+summarized. Patterns are invisible. Clinicians get anecdotes, not trends.
+
+## Goal
+Build a local-only pipeline that ingests Timmy's daily entries and emits a
+plain-text daily summary file (date, key metrics, anomalies flag, trend
+direction) plus a weekly aggregate.
+
+## Inputs
+- Daily journal entries (free text + optional scale ratings 1–5)
+- Timestamp; date is the primary key
+
+## Outputs
+1. `daily-summary-YYYY-MM-DD.txt` — single-day snapshot
+2. `weekly-aggregate-YYYY-Www.txt` — 7-day trend summary
+
+## Pipeline
+```
+entries/  ->  parse.py  ->  validated.jsonl  ->  summarize.py  ->  summaries/
+```
+
+1. `parse.py`: extract date, ratings, keywords from free text; validate schema
+2. `summarize.py`: compute daily counts, averages, flag deviations >1σ from
+   rolling 14-day baseline; write plain-text files
+
+## Constraints
+- Runs on local Linux, no external APIs
+- Python 3.10+, stdlib only
+- Outputs are append-safe (existing files are rewritten per date, not
+  concatenated)
+
+## Acceptance Criteria
+- [ ] Given 7 valid entries, `summaries/` contains exactly 7 daily files
+- [ ] Each daily file contains date, mean rating, and flag line
+- [ ] Weekly aggregate lists mean, min, max, and direction vs prior week
+- [ ] Pipeline exits 0 on valid input, exits non-zero on validation failure
+
+## Timeline
+Day 1: schema + parse.py skeleton + tests
+Day 2: summarize.py + output formatting
+Day 3: integration test against 30-day sample dataset
+
+## Owner
+Quill (draft/prototype). Handoff to executor for hardening.