Introduction
Building a custom Diagnostic from scratch is the most technically demanding task you can perform in Compass. A Diagnostic intended for non-technical end users must be highly prescriptive — which means every prompt you write needs to be precise and deliberate.
If you have an existing Diagnostic Definition that's close to what you need, editing it (as covered in Session Three) is almost always the faster path. This guide is for when that's no longer enough.
Tip: Before writing your first Diagnostic prompt, spend time in Explorer. Use it as a conversational sandbox to identify available measures, objects, and fields. Most analysts do significant exploratory work in Explorer before authoring their first Diagnostic. |
Part 1: Step-by-Step Guide
Phase 1 — Create the Diagnostic
1 | Navigate to New Diagnostic From the Diagnostic Instances screen, click New Diagnostic. |
2 | Name and Domain Enter a name and select a domain from the dropdown (or type a new one). During development, choose the smallest Entity that covers your needs to save time and compute. |
3 | Add a Description Describe what this Diagnostic is designed to analyze. |
4 | Configure the System Prompt (optional) The System Prompt contains instructions that apply to every Session in this Diagnostic. Use it for things like a specific table or measure to always use, or a filter that cannot be expressed as an Entity. Example: "For all queries in this diagnostic, exclude where Utilization Category Type 2 = Swing Bed." Many Diagnostics will leave this blank. |
5 | Configure Tools The Tools section controls what the agent can access. For prescriptive Diagnostics, leave out Search Data Model and Full Search Data Model — these tools allow open-ended searches and can cause the agent to pull in unexpected objects and go off-script. |
6 | Review the Prompt Preview The Prompt Preview window is read-only. It shows the complete prompt the agent will receive, including tool instructions and your System Prompt. Review it before proceeding. |
7 | Create the Diagnostic When everything looks correct, click Create Diagnostic. |
Phase 2 — Author Session 1
You'll land on an empty screen that says "No sessions yet." Click New Session to open a blank chat window.
Important: This is a prescriptive Diagnostic. Resist the urge to be conversational. You are writing instructions, not having a conversation. |
Session 1 Prompt Structure
Follow this order when composing your Session 1 prompt:
- Specify the measure or object — Be explicit. Include the code, state whether it is a measure or an object, and use exact casing. Example: "Use the measure URSA-PHF-029 URSA-CORE Encounters per 1000 Member-Years for this analysis."
- Define the filter — Tell the agent how to narrow the data. Example: "filtering to where encounter type = 'Hospital Inpatient Admission.'"
- Provide calculation context — Give the agent any additional context it needs: lookback periods, how to identify specific provider types, how to calculate derived fields, etc.
- Handle claims lag dynamically — Instead of hard-coding a date range, instruct the agent to detect incomplete months. Example: "Due to claims lag, it is expected that the last few months of data will be incomplete (typically 2-3 months). Start by checking total cost (Document Plan Paid Amount) by month to identify these incomplete months and remove them from the analysis." This keeps the Diagnostic accurate without requiring manual updates.
- Define key findings — Lead with "Return the following key findings" and enumerate each one precisely. Example: "1) Admits per K trended by month with a 2-year lookback. 2) Admits per K broken out by admit type using the CMS Admit Type Description column and trended by month with a 2-year lookback."
Run and Iterate
Click Start Session and watch the agent closely. Check for:
- Measure or object not found — likely a typo in the identifier, or you forgot to specify whether it was a measure or object.
- Unexpected data pulled — the agent may have used search tools; consider removing them from the Tools section.
- Missing or incorrect findings — the prompt may need more precision in the key findings list.
To iterate: click the paper icon beside the session title to open the session prompt, copy it, return to the Diagnostic screen, click New Session, paste, edit, and run again.
Finalize Session 1
Once the session runs consistently and produces the correct results:
- Click the pencil icon beside the session version you are keeping.
- Rename it "Session 1: [descriptive name]" and add a description of the analysis.
- Click Save.
- Delete any failed iterations using the pencil icon on each.
Phase 3 — Build Subsequent Sessions
Click New Session to begin Session 2. You will now see two additional sections: Disposition Schema and Dependencies.
Disposition Schema
Dispositions let you save a specific result from a session so that a later session can reference it — or use it as a condition to decide whether it should run at all.
Three disposition types are available:
- String — A Key (field name) that stores a text value. Example key: Highest Utilization Category.
- Number — A Key that stores a numeric value. Example key: Max Spend.
- Custom List — A Key plus pipe-delimited possible values. Example: True|False.
To instruct the agent to set a Disposition, add the instruction inside the key findings section of the prompt, attached to the relevant finding. Examples:
- String: "Save the utilization category having the highest utilization for the previous month as the Highest Utilization Category disposition."
- Number: "Save the maximum total cost for inpatient admissions during the prior 12 months as the Max Spend disposition."
- Custom list: "If the rate of SNF Readmissions is greater than 12%, set SNF Readmissions to True, otherwise set to False."
When a session with a Disposition runs, the agent will confirm at the end that it has set the disposition and state the value saved. |
Dependencies
Dependencies let you reference the prompt instructions and findings from an earlier session. Select the session from the dropdown and click Add Dependency. Then reference it in your prompt wherever relevant. Example: "Use the same measure and population as listed in Session 1."
Dependencies are used frequently. Dispositions are used only when you need conditional logic to determine if the agent should run a subsequent session.
Conditional Sessions
When adding Session 3 (or later), select the prior session in the Dependency dropdown. You will see a Conditional checkbox. Checking it means this session will only run when a prior session's Disposition meets a specific condition.
Once the box is checked, select the Disposition key and the value that must be met for the session to run. Example: only run a SNF readmission deep dive when the SNF Readmissions disposition = True.
Continue adding sessions until the Diagnostic covers everything it needs to.
Phase 4 — Add a Summary Session (Recommended)
Many prebuilt Diagnostics include a final summary session that asks the agent to review all prior sessions and surface the highlights. To add one, create a new session with all previous sessions as dependencies and use a prompt like:
"Review the analyses conducted in the previous sessions and surface 1) the baseline insights that would be needed for a high-level overview of this population and 2) the most interesting and/or actionable insights to support the value-based care management of this population. Surface key results (charts & tables) for each insight/recommendation selected." |
Part 2: Best Practices for Creating Prescriptive Diagnostics
The following best practices are drawn directly from experience building prescriptive Diagnostics in Compass. Apply them throughout the authoring process.
Category | Best Practice |
|---|---|
Prompt Style | Write instructions, not conversation. Avoid pleasantries, hedging, or open-ended questions. Every line should tell the agent precisely what to do. |
Measure/Object ID | Always specify the exact identifier code and state whether it is a measure or an object. The agent may not guess well with vague references. |
Explore First | Use an Explorer session to identify available measures, objects, and fields before authoring a Diagnostic from scratch. This saves significant iteration time. |
Entity Selection | During development, choose the smallest Entity that covers your needs. This reduces compute time and speeds up iteration. |
Tool Configuration | Remove Search Data Model and Full Search Data Model for prescriptive Diagnostics. These tools allow open-ended data searches and can cause the agent to deviate from your intent. |
Claims Lag | Never hard-code date ranges. Use dynamic claims lag instructions so the Diagnostic stays accurate across runs without manual updates. |
Key Findings | Lead with "Return the following key findings" and enumerate each one with a numbered list. The more specific you are, the more consistently the agent will deliver the right output. |
Session Naming | Name each session "Session N: [descriptive name]" and add a description. This makes the Diagnostic much easier to maintain and share. |
Iteration Hygiene | Delete failed session iterations once you have a working version. Do not leave dead ends in the Diagnostic. |
Dependencies | Reference prior sessions by name in your prompt wherever relevant. Do not assume the agent will infer the connection without explicit instruction. |
Conditional Logic | Use Conditional sessions to narrow analyses only to populations where they are relevant. This improves both performance and output quality. |
Summary Session | Add a final summary session with all prior sessions as dependencies. This gives end users a curated set of highlights without requiring them to review every session individually. |
Watch the First Run | Stay present when running a new session for the first time. Early errors (missing measures, unexpected filters) are much faster to catch and fix in real time. |
Quick Reference: Session Prompt Checklist
Use this checklist when writing any session prompt:
- Specify the exact measure or object (code + type)
- Define the filter/population
- Provide calculation context and lookback instructions
- Include dynamic claims lag handling (no hard-coded dates)
- List key findings with "Return the following key findings" followed by numbered items
- Add Disposition instructions inside the relevant key finding (if applicable)
- Reference prior sessions in the prompt (if using Dependencies)