Align offline agitation retrieval signals

[BigSimmo]

Summary

• Share medication amount, route, and frequency intent between clinical text-query construction and retrieval selection.
• Preserve explicit numeric units, SC, SL, PRN, and frequency signals for focused agitation medication queries.
• Keep broad agitation-management queries on the compact pharmacological-management path instead of restoring the former ten-term expansion.

Why

PR #666 was squash-merged while its late review fix was still being reconciled. The merged bot fix duplicates the retrieval alias regex and maps every mg/mcg request to mg; this focused follow-up keeps the stronger tested implementation without changing thresholds or provider behavior.

Verification

• npx vitest run tests/clinical-search.test.ts tests/retrieval-query-variants.test.ts — 112/112 passed after syncing merged PR Fix offline release retrieval latency #666.
• Scoped ESLint — passed.
• Scoped Prettier — passed.
• git diff --check — passed.

Checks pending / intentionally delegated

• Hosted CI is authoritative for full TypeScript/build checks due severe local lag.
• Full Playwright and aggregate release composites are intentionally not rerun locally.
• The original OpenAI-backed evaluator remains deferred and no OpenAI request is permitted.

Clinical governance

• No patient-identifiable workflow or provider configuration changed.
• Source-backed claims and conservative source-governance behavior are unchanged.
• Production Supabase remains Clinical KB Database (sjrfecxgysukkwxsowpy).
• This narrows deterministic retrieval intent only; it introduces no new clinical recommendation or deployment-classification change.

Summary by CodeRabbit

• Bug Fixes

  • Improved medication-related search results for agitation queries.
  • Preserved requested dose amounts, units, administration routes, and dosing frequencies.
  • Prevented relevant medication details from being dropped or replaced by unrelated search terms.

• Tests

  • Added coverage verifying that supported medication evidence signals remain intact in search results.

• Documentation

  • Recorded the retrieval issue and its resolution in the review ledger.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 546a9502-9a3e-4f61-9420-0412cc8c2fb0

📥 Commits

Reviewing files that changed from the base of the PR and between c1b6c70 and ef448e2.

📒 Files selected for processing (4)

• docs/branch-review-ledger.md
• src/lib/clinical-search.ts
• src/lib/retrieval-selection.ts
• tests/clinical-search.test.ts

---

📝 Walkthrough

Walkthrough

Changes

Medication evidence retrieval

Layer / File(s)	Summary
Canonical medication evidence terms src/lib/clinical-search.ts, tests/clinical-search.test.ts	Adds canonical amount, route, and frequency term extraction and uses it to constrain agitation-related query expansion, with coverage for explicit medication signals.
Retrieval intent signal integration src/lib/retrieval-selection.ts, docs/branch-review-ledger.md	Uses normalized medication evidence intent for dose and route detection, and records the related remediation in the review ledger.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Query
  participant ClinicalSearch
  participant RetrievalSelection
  participant RetrievalIntent
  Query->>ClinicalSearch: provide agitation medication query
  ClinicalSearch->>ClinicalSearch: derive amount, route, and frequency terms
  ClinicalSearch-->>Query: return constrained clinical search query
  Query->>RetrievalSelection: provide normalized query
  RetrievalSelection->>RetrievalSelection: derive medication evidence intent
  RetrievalSelection-->>RetrievalIntent: set dose and route signals

Loading

Possibly related PRs

• BigSimmo/Database#581: Introduced the medication evidence intent reused by this change.
• BigSimmo/Database#666: Tightened related agitation medication query expansion behavior.
• BigSimmo/Database#571: Modified the same medication-dose evidence retrieval path.

Suggested reviewers: claude

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/offline-retrieval-signal-followup

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

_{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 ↗︎.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ef448e212d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve hyphenated dose units

When users write doses as adjectival forms like 5-mg or 100-mcg (common in clinical copy), this regex does not match because it only allows whitespace between the number and unit. Since buildClinicalTextSearchQuery() replaces the token list with medicationDoseEvidenceSearchTerms(), those agitation queries collapse to agitation arousal dose and drop the explicit amount/unit instead of preserving 5 mg, weakening recall for dose-specific rows; a focused test such as buildClinicalTextSearchQuery("What 5-mg option is listed for agitation?") would catch it.

Useful? React with 👍 / 👎.