Advisors and decisions
Agents work unattended, so Orion has rules for what happens when an agent is unsure, and for keeping what an agent proposes apart from what a person agreed to.
When an agent stops to ask: the advisor
An implementer that hits an ambiguity stops and asks. Orion carries the question to an advisor, carries the answer back, and resumes the run, up to five questions per run. See inside one worker.
The advisor is a second agent that answers from the design committed in the repository:
| Advisor | Reads | Answers |
|---|---|---|
| architect | spec.md and plan.md | how it should be built |
| pm | intent.md | what is being built, and why |
| dba | the schema and the migrations | how the data should be shaped |
Each advisor derives its answer from the artifact and cites it, or refuses. A refusal is a correct result: an invented answer would read as a cited decision, and when the artifact is silent, completing it is a person's call.
A refusal means blocked
When the advisor refuses, the run ends blocked: the ticket is
orion-failed with the question on it. Answer it by amending the artifact
(so the next ticket does not ask again) or by commenting on the ticket, then
requeue:
orion queue add KEY --reset
See the recovery runbook.
Recommendations and decisions
Every later stage treats the committed artifacts as true, so a recommendation is kept apart from them in two independent ways:
| Proposed | Decided | |
|---|---|---|
| The file's status line | - Status: unconfirmed | - Status: confirmed |
| The directory | docs/recommendations/pending/ | docs/recommendations/confirmed/ |
Only the confirmed directory is in scope for an advisor or in an implementer's prompt, so a later stage never reasons from an unconfirmed recommendation.
Confirming one
When an agent records a recommendation, Orion asks about it in the project's
Slack channel. Confirmation is the same approval that gates merges (see
Slack and approvals):
only people in slack.merge_approvers count, Orion's own reactions never do,
and a rejection beats every approval.
- Approved: the record moves to
confirmed/, its status changes, and the confirmation is appended to it, naming the person and linking the Slack message. - Rejected: the record stays in
pending/, still unconfirmed, and nothing downstream reads it. - No answer yet: the same, and the next run checks the Slack thread again.
Without Slack, confirm or reject from the terminal or from the
web dashboard, once the project's orion.json sets
collect.allow_local_approval:
orion confirm-plan PROJECT RECORD # confirm
orion confirm-plan PROJECT RECORD --reject # reject, with --reason <text>
The stage that asked turns it into a decision the next time it runs.
Where recommendations come from
Today, the database architect. When the idea involves storing data,
orion plan names the architect and the command that runs it:
orion run <id> --stage database
It works in this order:
- Recommend a database, with its reasoning, from the intent and spec.
- A person confirms it, and only then is it a decision.
- Design the initial schema on the database that was agreed, also as a recommendation that needs confirming.
No schema is designed while the database choice is unconfirmed.
Asking the database architect directly
orion dba [KEY] "why is the claims query slow?"
puts a database question (schema, migrations, indexes, a slow query) to the
same architect at any time, with or without a ticket. It only proposes: it
changes nothing, runs no migration, and only ever reaches the
non-production database named in dba.non_prod_dsn.
Not documented yet
- How the advisor chooses between architect, pm and dba for a given question.