The opportunity scan is a visual progress tracker that organizes diagnostic definitions by domain and tracks diagnostic progress driven by scans. A scan is an automated, end-to-end execution of the definitions in a diagnostic suite — or a single diagnostic definition — for a given entity and vintage — it creates all the diagnostics at once and drives the AI through every session sequentially, producing findings, respecting dependencies, and tracking progress as it goes. The page offers two views — Graphical (default) and List — toggled via a segmented control in the header.
Two Modes
The opportunity scan page operates in two mutually exclusive modes:
- Browse mode — Select a diagnostic suite from the dropdown on the left side of the header. The graphical view shows the suite's definitions organized by domain as a preview, with no progress overlay. This is the default state when the page loads.
- Scan mode — Select an entity and vintage from the dropdowns on the right side of the header. The graphical view shows an actual scan's progress. The suite dropdown clears.
Selecting a suite clears the entity and vintage selection. Selecting an entity or vintage clears the suite dropdown. The two modes cannot be active simultaneously.
On page load, the suite dropdown auto-selects a default suite, prioritizing one whose name contains "cost of care" (e.g., "Cost of Care Opportunity Analysis"). If no such suite exists, the first suite alphabetically is selected.
Shared Header
The header is divided into left and right control groups:
Left side:
- Suite dropdown (graphical view only) — Browse a diagnostic suite to preview its structure.
- New Scan button (Architects and above) — Opens an inline form to create a scan. The suite defaults to whichever suite is currently selected in the dropdown.
Right side:
- Entity dropdown — Filters by entities that have scans.
- Vintage dropdown — Filters by vintages matching the selected entity. Selecting both activates the corresponding scan.
- View toggle — Switches between Graphical and List views.
A Summary line shows aggregate diagnostic counts and completion status.
Graphical View
The graphical view organizes definitions into domains based on the active suite or scan. Each domain is an expandable panel. Click a domain to reveal the definitions it contains. The first domain alphabetically serves as the central anchor for the constellation visualization.
Progress Tracking (Graphical)
When a scan is active (scan mode), the graphical view tracks diagnostic progress at multiple levels:
- Per-domain — Each domain displays a progress indicator showing how many of its definitions are complete or in progress (e.g., "3/5 complete · 1 in progress") along with a progress bar.
- Overall — The header shows aggregate progress across all domains.
- Constellation — A star visualization grows as domains are activated. See The Constellation below.
Per-definition status is shown with moon icons:
- Empty circle — Not started (no diagnostic in the scan's plan for this definition)
- Spinning half-moon — In progress (diagnostic exists but not yet complete)
- Solid full moon — Complete (diagnostic finished all sessions)
In browse mode (no active scan), all definitions show empty circles — the structure is visible but there is no progress to display.
The Constellation
The graphical view includes a constellation graphic — a star visualization with the first domain at the center and lines connecting to each active domain. As domains gain started diagnostics from the active scan, new stars and connections appear.
Presentations (Graphical)
When the active scan has presentations, a Presentations panel appears above the domain panels. Each presentation shows a status icon and links to its detail page. The panel is collapsible.
List View
The list view shows all scans in a flat list. The suite dropdown is hidden in list view. Each row displays:
- Entity name and vintage
- Suite name, diagnostic count, creator, creation date
- Status (Not started, Running, Completed, Failed)
- Progress summary (e.g., "5/12 diagnostics complete")
- Last activity timestamp
Clicking a scan row selects it — the entity and vintage dropdowns update to match, and the row expands to show full detail. Clicking the already-selected row deselects it.
Expanded Detail
When a scan row is expanded, it shows:
- Presentations (if any) — Each presentation with a status icon and link to its detail page.
- Domains — Each domain lists its diagnostics with status icons (pending, running, completed, skipped). Within each diagnostic, individual sessions are listed with their status.
Creating a Scan
Click New Scan in the header to open the inline form. Provide:
- Diagnostic — What to run. The dropdown is divided into two groups: Suites (diagnostic suites containing multiple definitions) and Diagnostics (individual diagnostic definitions that have at least one session). Both groups are alphabetized. Selecting a suite runs all of its definitions; selecting a single diagnostic runs just that one definition as if it were a suite of one. Defaults to the suite currently selected in the browse dropdown.
- Entity — Optional; defaults to the currently selected entity. If no entity is selected, the scan covers all entities.
- Vintage — A label identifying the data period being analyzed (e.g., "April 2026"). Defaults to the current month and year.
A scan is unique on the combination of entity and vintage — you cannot create two scans for the same entity and vintage. After creation, the page switches to scan mode and the new scan is automatically selected.
Only Architects (and above) can create scans.
What Happens When a Scan Is Created
- A diagnostic is created from each definition in the selected suite (or from the single selected definition). Each diagnostic inherits the scan's entity and vintage.
- Execution starts automatically. There is no separate "start" step.
- The scan appears in the list view.
Execution
Scans execute sessions one at a time, in creation order, across all diagnostics. For each session:
- Dependency check — If the session has dependencies, they are evaluated against the current state. Unconditional dependencies require the upstream session to be complete. Conditional dependencies additionally check the upstream session's disposition values. If dependencies are not satisfied, the session is skipped.
- AI conversation — The session runs the same AI conversation loop used in interactive sessions, but with no human in the loop. Tool calls are limited to one at a time (no parallel tool calls).
- Completion enforcement — A session is considered complete when it produces at least one finding via PROMOTE_FINDING (which sets the session status to COMPLETE). If the AI returns control to the user (via PROMPT_USER) before promoting a result, the scan automatically sends a follow-up message asking it to continue and promote a finding. This retry happens up to 5 times.
Diagnostics are processed in plan order (domain by domain). Within each diagnostic, sessions run in creation order. Once all sessions in a diagnostic finish, the diagnostic is marked complete and the scan moves on to the next.
Scans that have not started, have been interrupted, or have failed show an Execute, Resume, or Restart button respectively in the list view and graphical view header.
Interrupting a Scan
A running scan can be interrupted at any time. When a scan is running, an Interrupt Scan button appears for Architects in both the graphical view header and the expanded list view row. Clicking it requests an interruption — the scan stops gracefully between sessions (not mid-conversation) and its status changes to Interrupted.
Interrupting a scan preserves all progress. Completed diagnostics and sessions are retained, and any session that was in progress at the time of interruption keeps its current state.
Resuming an Interrupted Scan
An interrupted scan can be resumed by clicking the Resume button, which appears in the same locations as the interrupt button. Resuming picks up where the scan left off:
- Completed diagnostics and sessions are not re-run.
- Sessions that were skipped (due to unmet dependencies) are not retried.
- A session that was mid-conversation when interrupted continues from its current state rather than starting over.
Presentation Building
After all diagnostics complete, the scan automatically builds a presentation. Findings from every completed session are snapshotted into the presentation, and the AI organizes them into slides with appropriate layouts. The presentation is scoped to the scan's entity and vintage.
Presentation progress is tracked alongside diagnostic progress — the scan is not fully complete until the presentation finishes building.
Progress Tracking
Scan progress is persisted after every session completes, enabling crash recovery. The list view shows:
- Top-level status — Not started, Running, Interrupted, Completed, or Failed.
- Diagnostic-level summary — How many diagnostics are complete out of the total, per domain.
- Session-level detail — Within each diagnostic, every session is listed with its individual status:
- Pending — Not yet reached.
- Running — Currently being executed by the AI.
- Completed — Finished successfully (produced at least one finding).
- Skipped — Dependencies were not satisfied.
- Last activity — Timestamp of the most recent progress update.
- Error detail — If a scan fails, the error message is displayed inline.
Restarting a Failed Scan
If a scan fails (due to an error in the AI conversation, a database issue, etc.), the list view shows a Restart button. Restarting resumes from where the scan left off — completed diagnostics and sessions are not re-run. Only sessions that were pending or in progress at the time of failure are retried.
Viewing Scan Results
Each diagnostic created by a scan is a normal Compass diagnostic. You can navigate to any diagnostic from the expanded scan detail to see its sessions, findings, and dispositions. When a scan has presentations, they appear above the diagnostic domains in both the graphical and list views. Each presentation links directly to its detail page.
Real-Time Updates
Both views receive real-time progress updates via websocket. As the scan executes, diagnostic and presentation statuses update live without requiring a page refresh.
Access Control
- Authenticated users can view the opportunity scan in both views and see scan progress.
- Architects (and above) can create scans, execute scans, interrupt running scans, resume interrupted scans, restart failed scans, and soft-delete scans.