docs(medications): clinician reading worklist for the lexicon review (#318)

[BigSimmo]

Summary

• Adds docs/medication-lexicon-review-worklist.md, a reading aid for the clinician pass #318 asks for. It lists the top ten lexicon terms by severe usage (236 of 390 severe firings, 61%) with their resolved drug sets, and six prioritised questions. It does not fill in the sign-off block and changes no lexicon or catalogue data — the sheet stays UNREVIEWED, which only the clinician can change.
• Queues one immutable inbox request (46750cbf) updating #318 with these findings. #318 stays open; the sign-off is still owed.

The generated sheet was regenerated against this base and came back byte-identical, so it is current: 28 catalogue terms, 1 flagged.

Two of the three defects #318 cites are already closed. The ARB/Carbapenem substring match is fixed and now guarded by a standing check; lithium is reachable across 9 rows / 9 severe and is absent from the unreachable-drugs table. Only the divergent Warfarin pair remains, and it is worse than the row states — warfarin-vka and warfarin-anticoagulant carry three interaction rows each with zero in common, so which record is opened changes which warnings appear.

Three findings the sheet did not surface, none of which needed live access:

• tcas carries a dead slug. The selector lists dothiepin; the catalogue slug is dosulepin. A search of data/medications-snapshot.json for "dothiepin" returns zero records, so Dosulepin — whose own record flags Toxicity in OD: FATAL — fires none of the 20 severe TCA rows. This is a mechanical defect, not a judgment call.
• nsaids excludes the coxibs. It selects on subclassIncludes: ["NSAID"], so Celecoxib and Parecoxib (subclass COX-2 Inhibitor, tag NSAID) sit outside all 38 severe rows, while Meloxicam is included only because its subclass happens to be spelled NSAID (COX-2 preferential).
• maois excludes Moclobemide. It selects on subclassIncludes: ["MAOI"] and Moclobemide's subclass is RIMA, so it sits outside all 17 severe rows. Its tyramine risk is genuinely lower than the irreversible agents; its serotonin-syndrome risk is not.

The review instrument itself has two blind spots. Verified by executing the guard's own logic against the real surfaces and haystacks rather than reasoning about it: missedClassMembers() in scripts/build-medication-lexicon-report.ts skips any surface stem shorter than four characters, which leaves the check unable to fire for tcas and arbs (ppis is rescued by its long surface proton pump inhibitors), and the check reads only class and subclass, never tag. So the sheet's printed "Checks that ran and found nothing" line is overstated for two terms — which is how the Dosulepin miss stayed invisible. Neither fix is made here.

A near-miss is recorded in the doc's method note: an earlier pass was going to report Omeprazole as a catalogue drug missing from ppis. It is not a catalogue record — a substring search had matched it inside Esomeprazole. Every drug named in the worklist was re-checked by exact record name afterwards.

Verification

• npm run verify:pr-local — selected the low-risk docs route and completed 11 checks:

PR-local verification summary:
- completed: check:runtime, check:installed-lock-parity, format:changed, sitemap:check,
docs:check-index, docs:check-inventory, docs:check-scripts, docs:check-links,
check:branch-review-ledger, check:outstanding-issues, check:ledger-write-discipline
- failed: (none)
- not reached: (none)

• npm run check:ledger-write-discipline re-run after committing the inbox request: Ledger write discipline passed for 806918834b43..HEAD.
• npm run check:outstanding-issues: Outstanding-issues guard passed: 341 rows (97 open, 244 archived); Ledger inbox check passed: 2 pending request(s), 189 applied.

UI verification not run: no UI, routing, styling, or browser behaviour changed. Separately, this container cannot run Chromium gates at all — Playwright ships chromium-1194 against a pinned 1234 (#255/#312), so check:playwright-browser-revision fails closed and verify:ui / verify:phone-chrome are unavailable here. No browser coverage is implied by this PR.

Risk and rollout

• Risk: none to running behaviour. The change is one new documentation file plus one queued inbox request. No lexicon, catalogue, source, or application code is touched, and no alert mapping changes. The residual risk is editorial — that a clinical judgment framed in the worklist is wrong — which is why every item is written as a question for the reviewer rather than a determination, and why each is traced to the exact selector and catalogue field it comes from.
• Rollback:git revert the single commit. Nothing depends on the file.
• Provider or production effects: None. All findings were derived from tracked repo files (data/medications-snapshot.json, src/lib/medication-interaction-lexicon.ts, scripts/build-medication-lexicon-report.ts) with no live Supabase or OpenAI access.

Clinical Governance Preflight

Not required for this diff — classifyPullRequestFiles returns clinicalRisk: false, operationalRisk: false, ragRanking: false for both changed paths. The PR adds documentation about clinical mappings; it does not change ingestion, answer generation, search/ranking, source rendering, document access, privacy, production env, or clinical output.

Worth stating explicitly even so: the interaction alerts described here remain unvalidated mappings over source-backed text, exactly as before this PR. The wording a clinician sees is still verbatim catalogue prose. #318's stop condition is unchanged and was honoured — check:medication-lexicon-report passing was not treated as review, and the sign-off block was left empty.

Notes

• #318 remains open. Only a clinician filling in the sign-off block closes it. The three new findings in §2.1–2.3 and the two instrument blind spots in §4 are additional work this PR deliberately does not perform.
• The tcas dead slug (§2.1) is the one item that needs no clinical opinion to confirm and is a one-word fix plus a regenerate. It is left out of this PR because #318 says do not change the lexicon; it is a good candidate for its own small PR once you confirm Dosulepin belongs in the class.
• Run npm run issues:reconcile on its own serialized branch after this lands to apply the queued #318 update.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PZL59KVSBWURMKvfc9mbJr

---

Generated by Claude Code

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in:53 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bf35a379-867d-4a05-9a94-fa807ba7d1bc

📥 Commits

Reviewing files that changed from the base of the PR and between 8069188 and 242487b.

📒 Files selected for processing (3)

• docs/branch-review-records/1750578822f17106f9029aa52fbe2ba972c2610971d057b366f68f12bc87baba.record.md
• docs/medication-lexicon-review-worklist.md
• docs/outstanding-issues-inbox/46750cbf-f4f4-4a00-ab93-bdac644afbde.json

---

_{Comment @coderabbitai help to get the list of available commands.}

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.