content/engineering/modules/brief.html

<article class="doc" id="doc-modules-brief" aria-hidden="true"><div class="strip"><span class="path">modules/brief.md</span><span class="tag">Engineering, modules</span><span class="meta">~1 min read</span></div>
<h1>Module: <code>brief</code></h1>
<blockquote>
<p>Part of the Travi AI Agent monolith (<code>app/modules/brief/</code>). Read <code>00-overview.md</code> §3 (hard rules) before changing anything here.</p>
</blockquote>
<div class="tbl-wrap"><table class="plain col-table compact"><colgroup><col class="col-auto"/><col class="col-lg"/></colgroup>
<thead>
<tr>
<th></th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td data-label=""><strong>Purpose</strong></td>
<td data-label="">The clinician's one-screen snapshot: precompute, staleness, post-visit update loop.</td>
</tr>
<tr>
<td data-label=""><strong>Owns (data)</strong></td>
<td data-label="">brief_snapshot</td>
</tr>
<tr>
<td data-label=""><strong>Public surface</strong></td>
<td data-label=""><code>/clinician/brief/*</code>, <code>/clinician/confirmations</code>, <code>/clinician/post-visit</code></td>
</tr>
<tr>
<td data-label=""><strong>Depends on</strong></td>
<td data-label="">compiler (published facts only), identity (grants/step-up), ingestion (post-visit docs)</td>
</tr>
<tr>
<td data-label=""><strong>Requirements owned</strong></td>
<td data-label="">VIS-002/005/007, CLN-004/008</td>
</tr>
<tr>
<td data-label=""><strong>Constraining ADRs</strong></td>
<td data-label="">ADR-014, ADR-017 (step-up)</td>
</tr>
<tr>
<td data-label=""><strong>Key references</strong></td>
<td data-label="">reference/api.md (clinician table)</td>
</tr>
</tbody>
</table></div>
<hr/>
<h1>14. Clinician Brief Service</h1>
<h2 id="doc-modules-brief--h1">14.1 Content Contract (renders in this order)</h2>
<ol>
<li>Reason for hospitalization + discharge date.</li>
<li>Major hospital events only when they affect current care.</li>
<li>New / changed / stopped medications with source + current evidence state.</li>
<li>Patient-reported use, access barriers, material events since discharge.</li>
<li>Completed and outstanding tests, referrals, appointments.</li>
<li>Patient questions + discrepancies (pending_clinical_decision items).</li>
<li>Date + provenance of most recent update.</li>
</ol>
<h2 id="doc-modules-brief--h2">14.2 Generation &amp; Delivery</h2>
<p>Trigger: appointment detected → precompute at T−24 h (config <code>brief.lead_hours</code>) by the Brief Agent from <strong>published</strong> facts; snapshot persisted (<code>content JSON</code> + rendered PDF to S3) with <code>episode_version_at_build</code>; secure link + grant issued per §9.3; open p95 ≤2 s (snapshot read, no recompute); brief understandable ≤60 s is a usability exit criterion (§17.4).</p>
<h2 id="doc-modules-brief--h3">14.3 Post-Visit Loop (VIS-005/007)</h2>
<p>Clinician uploads note/AVS or submits structured summary → new <code>source_document</code> (level 5) → full compiler reprocess → supersessions + new tasks → patient Today updates ≤60 s after publication. Ambiguous material changes park as pending confirmations (step-up) and <strong>cannot</strong> alter patient instructions until confirmed.</p>
<h2 id="doc-modules-brief--h4">14.4 Staleness Algorithm (ADR-014, GAP-C1)</h2>
<pre><code>on brief open:
 cur = episode.version (SELECT)
 if cur == snapshot.episode_version_at_build: render(snapshot)
 else:
 delta = material_diff(snapshot, episode) # classes below
 if delta.empty: render(snapshot, banner="Updated &lt;ts&gt;; minor changes since")
 else: return 202 regenerating; enqueue rebuild (p95 ≤ 5 s); client polls
material classes: med plan item added/changed/stopped/confirmed;
 new pending_clinical_decision; episode paused/closed; new safety event
</code></pre>
<div class="pn"><a class="pn-prev" href="#"></a><a class="pn-next" href="#"></a></div></article>