4 Must-Do’s

1. Problem Description: Have you clearly defined the user problem(s) you intend to solve, and what value this creates? Write down a story, user insight, or quote about this problem (this is important because (1) this will motivate your team, and (2) without this your problem might not actually be a big problem for the users themselves).

2. User Stories: Have you clearly written at least 3 user stories and use cases?

3. Market Analysis: Have you surveyed what the market is doing here (e.g. comparison to other EMRs, or paper approaches; and don’t forget about learning from historic/existing OMRS instances)? Have you written down any possible gaps in your understanding of your users or their workflows? Have you reviewed the topic in FHIR to see what requirements or fields the global community references? (Eg if working on insurance, should look here)

4. Technical Considerations & Dependencies: Have you outlined what you need from cross-functional areas for success of the feature? E.g. do you need the platform to support a new API call? Have you explained how you’ve addressed dev concerns, such as designs that may not be feasible, or will be extra time-intensive to implement?

Optional/Encouraged

Sketches: Have you added a drawing or description of how the feature could work to solve the problem at hand? (Pictures of sketches are ok!)

Project Management: Have you created the Epic and JIRA tasks so you can share work clearly? Roll-out plan: Do you have an idea whether this will be an experiment, gradual roll out, and when? Have you added this to the timeline view? Have you planned how you will promote and/or work with communications folks in order to help this feature reach the widest audience and have the biggest impact it can?

Later but should do

QA Plan: Have you mentioned the plan for QA, such as how you will discover and address edge cases? Does your team/squad have a plan for automated tests to be added to new components (unit tests) or workflows (e2e tests)?

Safety & Tech Risks: Is there any reason you could regret rolling out this feature? (e.g. possible patient harm, heavy tech debt like introducing an unsupported library) Have you thought through the risks for this particular solution? And, how to reduce/address those?

This checklist was inspired by this article. Additional Business Analyst Resources here.

Status: IN PROGRESS

Technical Complexity: HARD / COMPLEX

Summary:

V1 (completed): lightweight manual pin/unpin of single drugs, stored per-user and capped, surfaced as a "My pinned orders" list above search.
V2 (this doc): V2 keeps the pinned-orders list useful on its own — it passively suggests drugs the prescriber already orders often (frequency/recency), then, once a backend aggregate exists, ranks them. Every suggestion is safe by construction: only already-prescribed drugs ever appear, capped and dismissible.

1. Problem

Clinicians in resource-limited settings process high patient volumes. Drug ordering requires navigating long lists, which slows the workflow. V1 gave prescribers a way to pin drugs manually; V2 aims to keep that list relevant passively, so it stays useful without ongoing manual curation.

Drug Order Favourite V1: COMPLETED

Lightweight pin/unpin of single drugs (no dose/frequency saved
- Stored per-user in userProperties
- Capped at maxPinnedDrugOrders (default 10),
- Surfaced as "My pinned orders" list above search + pin icons in results + a link on the order form.
- Drug Order Favourites foundation work: https://github.com/openmrs/openmrs-esm-patient-chart/pull/2996

Drugs Unpinned

Drugs Pinned

Drugs Pinning Inside the Order Basket

Drug Order Favourite V2: IMPROVEMENT IDEAS

Condition-aware suggestions
- Surface favorites/suggestions relevant to the patient's active conditions (hypertension → antihypertensives), turning a flat list into context.
- Highest value because it makes suggestions relevant instead of just frequent.
- The whole implementation question hinges on this question: how do you know amlodipine relates to hypertension? Ways to source that mapping?
  - Personal co-occurrence (recommended starting point)
    - Don't encode any clinical knowledge. Learn it from the prescriber's own behaviour: "drugs they tend to order when a patient has condition X active."
    - Re-rank the frequency/recency suggestions by how often they ordered each drug in encounters where one of this patient's active conditions was present.
    - Stays safe by construction: it only ever surfaces drugs already prescribed.
    - Explainable: "Hypertension · you've ordered this 12× for similar patients."
Smart suggestions (frequency/recency)
- Smart suggestions reduce manual curation / cognitive load.
- Surface frequency- and recency-based suggestions ("you've ordered this 18 times — add to favorites?") so the list stays relevant passively.
  - Trigger: frequency threshold ("ordered 18×"), recency ("ordered 6 of last 10 visits"), or a blend. A blend avoids suggesting a drug ordered 20× two years ago.
  - Placement: a dismissible "Suggested for you" strip inside the pinned-orders panel (empty-state and partially-filled), vs. an inline nudge on the search result row, vs. a one-time toast after saving an order.
  - Restraint: cap to 1–3 suggestions, let users dismiss permanently ("Not interested"), and never re-suggest a dismissed or already-pinned drug.
Starter / role-based favorites
- Seed new users with facility- or role-level default pins (then editable) so the panel isn't empty on first use.
- Solves the cold-start problem the same way smart suggestions do, but immediately.

2. User Stories

As a prescriber, I want to see 1–3 "Suggested for you" drugs drawn from my own ordering history, so my list stays curated without manual upkeep.
As a prescriber, I want to see the drugs I tend to order when a patient has condition X active, so the panel reflects the patient in front of me.
As a prescriber, I want to dismiss a suggestion permanently so it never reappears, and I never want an already-pinned drug suggested to me.
As a new prescriber, I want a sensible starter set of pins for my facility/role, so the panel is useful on my first shift.
As a prescriber, I want each suggestion to explain why it appeared ("ordered 18×" / "Hypertension · 12× for similar patients"), so I can trust it at a glance.

3. Market Analysis

Other EMRs. Personalised order lists are a well-established pattern in commercial EMRs, but they are overwhelmingly manually curated or role/facility-seeded rather than learned:

Epic — clinicians save frequently placed orders to a personal preference list, with a "My Favorites" section that stores each order's preferred dose/route/frequency for that user only. On top sit specialty order sets / SmartSets and one-click order panels for groups placed together. Lists are personal or facility-shared (the Facility List is IT-managed) and can be copied/merged between clinicians. Curation is explicitly manual — provider training guides advise saving your ~20 most common orders and grouping them into disease/body-system sections. (source)
Cerner / Oracle Health — per-user Favorites folders, a Quick Orders workflow tab, Prescription Favorites, and custom Order Sets, all manually curated and private to each user. The nearest analog to context-driven surfacing is LaunchPoint, where a site can configure contextual orders that appear against abnormal lab findings — but that is manually configured by the site, not learned or ranked per clinician. (source)

4. Technical Considerations & Dependencies

4.1 Feasibility

The feasibility verdict below is grounded in what openmrs-module-fhir2 supports today.

✅ Feasible now — no backend work

Capability	Why it works

Capability	Why it works
Read patient's active conditions	`Condition?patient=X&clinical-status=active` is supported today.
All UI + fatigue logic	Suggestion surfaces, the ≤3 cap, two-way dismissal, "never re-suggest pinned/dismissed" — pure frontend, plugs into V1's existing extension slots.
Store pins & permanent dismissals	Reuse V1's `userProperties` pattern under a sibling key.
The `useDrugSuggestions` seam against a mock	Build the whole feature behind the real interface while the data source matures.

⚠️ Feasible on the frontend, but a scaling liability — must be bounded

Capability	The catch

Capability	The catch
"Your most-ordered drugs" (frequency)	`MedicationRequest?requester=me` works, but returns 10/page with no sort and no server-side count → the browser must page through order history to tally. Acceptable only as a capped, approximate MVP over a recent slice — never a full scan.
Recency ("6 of last 10 visits")	No date search param and no sort → fetch-all-and-sort in JS. Same scaling problem, plus the visit-vs-encounter modelling wrinkle.

❌ Not feasible on the frontend — requires a backend

Capability	Why not

Capability	Why not
Condition-aware suggestions (the headline feature)	Needs the prescriber's orders joined to other patients' conditions. Doing that client-side pulls other patients' data into the browser — a privacy / de-identification problem — and there's no aggregation endpoint. Requires the pre-computed `(prescriber, condition, drug) → count` table + scheduled job.
Efficient frequency/recency at scale	Same root cause: FHIR search returns resources, not counts or rankings. The correct answer is a server-side aggregate.

4.2 Phased delivery

Phase 1 — ship the ✅ row against the useDrugSuggestions mock seam. Delivers real UI, real conditions lookup, and all fatigue logic. No backend dependency.
Phase 2 — bounded frequency MVP (⚠️). Capped, approximate, recent-slice-only. Explicitly labelled "approximate" in the UI (the mockup already does this: "based on your last 200 orders").
Phase 3 — the aggregate endpoint (❌). A pre-computed (prescriber, condition, drug) → count table built by a scheduled job, likely in openmrs-module-fhir2. This is the single gating backend ticket that unlocks both condition-aware ranking and non-approximate frequency/recency. The personal co-occurrence approach (Section 1) defines its scope: it only counts drugs the prescriber has already ordered.

4.3 Data pipeline (Phase 3 target)

Pre-compute (backend scheduled job): builds the (prescriber, condition, drug) → count table from past orders — how often each prescriber ordered each drug when each condition was active.
Read conditions (order-time): pull the patient's active conditions via Condition?patient=X&clinical-status=active, matched on CIEL/SNOMED so differently-coded conditions still resolve.
Re-rank (order-time): the frontend looks up those conditions in the table and boosts the matching drugs, naming the driving condition as the reason.
Restraint rules (all phases): capped, dismissible, never auto-added.

4.4 Cross-functional dependencies

Backend/platform: the Phase 3 aggregate endpoint + scheduled job. This is the critical-path dependency; Phases 1–2 do not require it.
Terminology: CIEL/SNOMED mapping so condition codes resolve consistently across instances.
Frontend: extension-slot integration reused from V1; userProperties for pins and dismissals.

5. Sketches

Claude Design Mockups: https://claude.ai/design/p/3fe4c75d-b923-4172-a714-4394af93d39d?file=Drug+Order+Favourites+-+Smart+Suggestions.dc.html

Pinned Panel + Frequency & Recency Blend (Fresh)

Pinned Panel + Frequency & Recency Blend (Typical)

Pinned Panel + Frequency & Recency Blend (Full)

Drug Orders Favourites V2