Add patient-friendly plain-language report mode

[Liohtml]

Part of #51. Positioning: patient-education track (see epic) — an understand-and-prepare-questions layer, not a diagnostic output.

Summary

Add an optional patient-facing report mode that renders the report in plain
language at a controlled reading level, with a jargon glossary and explicit
"talk to your doctor" routing. This is additive: the existing professional
report stays unchanged and remains the default for the research/developer track.

Why (research-backed)

Patient comprehension — not access — is the single best-evidenced pain point
in radiology:

• Only 4.2% of radiology reports (study of 97,052 reports) are written at the
  average adult reading level; ~96% exceed patient comprehension.
• Interview studies: 85% of patients are confused by medical terms/acronyms,
  ~40% feel anxious.
• LLM plain-language simplification raised lay comprehension dramatically
  (e.g. 46% → 95% in an RCT; Lancet Digital Health 2025 meta-analysis rated
  LLM-rewritten reports ~87% more understandable).
• Patients overwhelmingly prefer to ask their doctor over self-research, so
  the tool should contextualize and route to clinicians, not replace them.

⚠️ Safety constraints (load-bearing — research-confirmed)

LLM report simplification carries a documented 0–10% harmful-error rate
(fabricated/dropped findings, inverted qualifiers). The mode MUST:

• Never add or remove findings relative to the source report/analysis.
• Never invert hedged language — preserve qualifiers like "cannot exclude…"
  verbatim in meaning.
• Never tell the patient something "looks normal/fine" or "looks concerning"
  on its own (false reassurance is the feat: MedCheck v0.1.0 - AI-powered medical imaging analysis toolkit #1 documented patient harm and crosses
  into regulated-device territory — see epic [Epic] Validation & enhancement pipeline stages — improve and verify results before reporting #51 positioning note).
• Always frame output as assistive, pair any AI uncertainty with error-rate
  context, and prominently route serious/incidental findings to a clinician.

Proposed implementation

• New report option --report patient (or an --audience patient modifier) and a
  report_audience field on PipelineContext (default professional).
• New renderer in src/medcheck/pipeline/report.py:
  generate_patient_report(ctx) producing HTML/PDF tuned for laypeople.
• Readability target FKGL grade 6–8 (AMA/NIH recommend ≤6th grade for patient
  materials). Compute and display the Flesch-Kincaid grade (+ optionally SMOG)
  on the report so quality is visible; add textstat (MIT) or a tiny in-repo FK
  implementation as a light dependency.
• Glossary mapping jargon → plain language: prefer PORTER-style lay
  definitions (readable at ~grade 4) and link out to RadiologyInfo.org
  (ACR/RSNA patient resource). Use RadLex only as an internal term-normalization
  backbone — it is NOT patient-readable (median grade 12.6, only 8% of terms
  defined), so never display RadLex text to patients.
• Reinforced patient-facing disclaimer + a "questions to ask your doctor" section
  generated from the findings.

Acceptance criteria

• Optional patient mode; professional report unchanged and still default.
• Output measured at FKGL ~6–8; grade shown on the report.
• Glossary/lay-definitions applied; RadLex used only internally, never displayed.
• Findings are neither added nor dropped vs. source; qualifiers preserved
  (unit test with a hedged finding).
• No "looks normal/concerning" style statements; "talk to your doctor" +
  serious-finding escalation present.
• Tests: readability threshold met on sample reports; glossary substitution;
  qualifier-preservation; disclaimer present.

Effort

~1 day. Light dependency (textstat or inline Flesch-Kincaid).

References (session research, not committed)

97k-report readability study (PMID 30639521); Lancet Digital Health 2025 LLM
simplification meta-analysis; PORTER vs RadLex readability (PMID 29310924);
AMA/NIH 6th-grade guidance; RadiologyInfo.org.

[Liohtml]

Assessment

Value: High — and I'd argue it's table-stakes for patient trust, not a nice-to-have.

Complexity: Moderate — the actual generation is another LLM pass; the hard part is prompt discipline (reading level control, glossary coverage, "ask your doctor" framing) and making it impossible to accidentally ship this as the primary clinical output.

Fits architecture: Yes — this maps cleanly as either a separate ReportStep variant or a post-processing step in the existing ReportStep. The workflow YAML engine already supports composable steps.

My take

The feature makes sense, but the risk is that a well-designed plain-language summary gets copy-pasted by a patient into a symptom checker or used to self-diagnose. The disclaimer strategy matters more than the generation quality here.

I'd frame it structurally as: the plain-language layer never stands alone — it always appears alongside (or as a clearly subordinate section of) the clinical report. The PDF/HTML templates should make the hierarchy obvious visually.

If we build this

The cleanest implementation is a second VisionAnalysisStep-like step that takes the structured output (the AnalysisResult already in context) as input — not the raw images — and translates it, rather than re-analyzing from scratch:

1. Add plain_language_summary: str to PipelineContext (alongside overall_impression).
2. Add a PlainLanguageSummaryStep that calls the LLM with the structured findings as input, a controlled reading-level prompt, and a forced disclaimer suffix.
3. Add report_mode: Literal["clinical", "patient", "both"] to AnalyzeRequest and the CLI --report-mode flag.
4. Update ReportStep to include the plain-language section when report_mode is "patient" or "both".

The prompt for step 2 needs careful design: you want to prevent the model from adding new clinical information not in the structured findings, which could happen if the LLM "remembers" the images.

Concern

The reading-level claim ("8th grade" or similar) needs to be tested rather than assumed. LLMs are notoriously overconfident about their ability to simplify medical language. A short eval suite of 10-20 output samples reviewed by a non-medical reader would be worth building before shipping.