The opportunity scan is a tool 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, which is available in the graphical view only. 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, with a suite already selected.
- Scan mode — Select an entity and vintage from the dropdowns on the right side of the header. The entity dropdown offers only entities that have scans, and the vintage dropdown only vintages matching the chosen entity; picking both activates the corresponding scan and the graphical view shows its progress.
Selecting a suite clears the entity and vintage selection, and selecting an entity or vintage clears the suite dropdown. The two modes cannot be active simultaneously.
The rest of the header holds the view toggle between Graphical and List, a New Scan button for Compass Authors and above, and a Summary line showing 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 revealing the definitions it contains.
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 one 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 collapsible Presentations panel appears above the domain panels. Each presentation shows a status icon and links to its detail page.
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:
- Action bar (Compass Authors and above) — Execute/Resume/Restart buttons (based on scan status), an Interrupt button (when running), and an Edit button to enter edit mode.
- 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.
Edit Mode
The scan owner and its editors can use Edit on an expanded scan row to manage the scan's Editors and Viewers (see Sharing). Delete Scan is also available here, and soft-deletes the scan along with all of its diagnostics.
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.
- Presentation Guidance — Optional; selects a scan presentation guidance prompt that will be appended to the AI's instructions when building the scan's automatic presentation. If set to "None", no additional guidance is included.
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 Compass Authors (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. If the AI returns control to the user (via PROMPT_USER) before promoting a result, the scan sends a follow-up message asking it to continue and promote a finding, retrying a few times before giving up.
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 Compass Authors (and above) 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 or Restarting a Scan
An interrupted scan offers a Resume button, and a scan that failed — from an error in the AI conversation, a database problem, or similar — offers Restart. Both are the same operation under different statuses, and both pick 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 added to the presentation, and the AI organizes them into slides with appropriate layouts. The presentation is scoped to the scan's entity and vintage. If a scan presentation guidance prompt was selected when the scan was created, it is appended to the AI's starting instructions for the presentation builder.
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, so a scan survives a crash rather than starting over. A scan itself is Not started, Running, Interrupted, Completed, or Failed, and a failed scan shows its error message inline. Each session within it carries one of four statuses:
- Pending — Not yet reached.
- Running — Currently being executed by the AI.
- Completed — Finished successfully, having produced at least one finding.
- Skipped — Dependencies were not satisfied.
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, and to the scan's presentations from the panel above the diagnostic domains.
Sharing
Scans support the same two levels of shared access as diagnostics:
- Editors have the same rights as the owner: they can execute, interrupt, resume, restart, and delete the scan, and manage who else has access. Only Compass Author-level users (or higher) can be added as individual editors; any user group can be added as an editor group. When a user group is added as an editor, all members of that group receive editor-level access. Editors of a scan also gain editor-level access to all diagnostics and presentations created by that scan.
- Viewers have read-only access to the scan and all of its diagnostics and presentations, including sessions, conversation logs, and findings. Any authenticated user or user group can be added as a viewer. When a user group is added as a viewer, all members of that group receive read-only access.
Sharing is managed in edit mode, where the Editors and Viewers multi-selects combine individual users and user groups under labeled headers.
Scan-level sharing is additive with diagnostic-level and presentation-level sharing. A user who has access through either the scan or the individual diagnostic or presentation — whether granted directly or through a user group — will be granted access. Removing a user or group from a scan does not revoke access they have directly on a diagnostic or presentation.
Access Control
- Authenticated users can view scans that have been shared with them, and see scan progress.
- Compass Authors (and above) can create scans, execute scans, interrupt running scans, resume interrupted scans, restart failed scans, and soft-delete scans — provided they are the owner or an editor of the scan.