A run is an automated, end-to-end execution of multiple project templates for a given entity and vintage. Instead of manually creating projects and stepping through sessions one at a time, a run creates all the projects at once and drives the AI through every session sequentially — producing key results, respecting dependencies, and tracking progress as it goes.
Creating a Run
Runs are created from the Guided Tour page. Click New Run in the header to open the inline form. Provide:
- Vintage — A label identifying the data period being analyzed (e.g., "April 2026"). Defaults to the current month and year.
- Size — Full creates a project for every template across all guided tour domains. Limited creates projects for the Cost Overview domain only.
The selected entity filter on the Guided Tour page is carried over: if an entity is selected, the run is scoped to that entity. If no entity is selected, the run covers all entities.
A run is unique on the combination of entity and vintage — you cannot create two runs for the same entity and vintage.
Only Reviewers (and above) can create runs.
What Happens When a Run Is Created
- A project is created from each applicable template (all eight guided-tour domains for Full, Cost Overview only for Limited). Each project inherits the run's entity and vintage.
- Execution starts automatically. There is no separate "start" step.
- The run appears in the Runs list page, accessible from the sidebar.
Execution
Runs execute sessions one at a time, in creation order, across all projects. 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 key result via PROMOTE_RESULT (which sets the session status to COMPLETE). If the AI returns control to the user (via PROMPT_USER) before promoting a result, the run automatically sends a follow-up message asking it to continue and promote a key result. This retry happens up to 5 times.
Projects are processed in plan order (domain by domain). Within each project, sessions run in creation order. Once all sessions in a project finish, the project is marked complete and the run moves on to the next.
Presentation Building
After all projects complete, the run automatically builds a presentation. Key results 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 run's entity and vintage.
Presentation progress is tracked alongside project progress — the run is not fully complete until the presentation finishes building.
Progress Tracking
Run progress is persisted after every session completes, enabling crash recovery. The Runs list page shows:
- Top-level status — Not started, Running, Completed, or Failed.
- Project-level summary — How many projects are complete out of the total, per domain.
- Session-level detail — Within each project, 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 key result).
- Skipped — Dependencies were not satisfied.
- Last activity — Timestamp of the most recent progress update.
- Error detail — If a run fails, the error message is displayed inline.
Restarting a Failed Run
If a run fails (due to an error in the AI conversation, a database issue, etc.), the Runs list shows a Restart button. Restarting resumes from where the run left off — completed projects and sessions are not re-run. Only sessions that were pending or in progress at the time of failure are retried.
Viewing Run Results
Each project created by a run is a normal Compass project. You can navigate to any project from the expanded run detail to see its sessions, key results, and dispositions. Projects created by runs are also visible on the Guided Tour page, where they appear as started or completed investigations.
When a run has presentations, they appear above the project domains in both the Runs list (expanded detail) and the Guided Tour page. Each presentation links directly to its detail page.
Access Control
- Authenticated users can view the Runs list and see run progress.
- Reviewers (and above) can create runs, execute runs, restart failed runs, and soft-delete runs.