> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Decisions
> The human-in-the-loop checkpoint where you approve, reject, or guide agent work.
**Decisions** are the primary way you interact with OrgX agents. When an agent needs human judgment—approval, clarification, or a tie-breaker—it surfaces a decision for you to act on.
## Questions This Page Answers
* When should a decision be created instead of auto-shipping?
* What is the fastest safe way to triage pending decisions?
* How do decision outcomes improve future agent behavior?
* What autonomy settings reduce noise without losing control?
## Why Decisions?
Agents are powerful, but they shouldn't operate unchecked. Decisions ensure:
* **Quality**: Human review catches errors before they ship
* **Alignment**: You stay in control of strategic direction
* **Trust**: Build confidence in agents incrementally
* **Compliance**: Maintain audit trail for governance
The goal isn't to slow agents down—it's to keep you in the loop on what
matters while agents handle the routine work.
***
## Decision Types
Agent completed work and needs sign-off before shipping.
**Examples**:
* PR ready for merge
* Campaign brief ready to send
* Outreach sequence ready to launch
**Actions**:
* **Approve**: Ship the artifact
* **Reject**: Send back with feedback
* **Edit**: Modify before approving
Agent hit its autonomy limit and needs permission to proceed.
**Examples**:
* Budget exceeded threshold
* Action outside granted scopes
* Conflicting priorities detected
**Actions**:
* **Approve**: Grant permission for this instance
* **Approve + Expand**: Grant and update autonomy settings
* **Reject**: Stop and reassess
Agent needs more context to proceed effectively.
**Examples**:
* Ambiguous requirements
* Missing stakeholder info
* Unclear success criteria
**Actions**:
* **Answer**: Provide the requested information
* **Skip**: Agent proceeds with best guess
* **Reassign**: Route to someone who knows
Agent detected competing priorities or blocking dependencies.
**Examples**:
* Task A blocks Task B
* Resource contention
* Timeline conflicts
**Actions**:
* **Prioritize**: Choose which takes precedence
* **Defer**: Postpone one or both
* **Resolve**: Provide resolution strategy
***
## Decision Anatomy
Every decision includes:
```typescript theme={"dark"}
interface OrgDecision {
id: string;
type: 'approval' | 'escalation' | 'clarification' | 'conflict';
// Context
title: string;
description: string;
agent_reasoning: string;
// Links
artifact_id?: string;
work_item_id: string;
initiative_id?: string;
agent_instance_id: string;
// Evidence
evidence: Evidence[];
citations: Citation[];
// State
status: 'pending' | 'approved' | 'rejected' | 'expired';
urgency: 'low' | 'medium' | 'high' | 'critical';
// Resolution
resolved_by?: string;
resolved_at?: string;
resolution_note?: string;
// Metadata
created_at: string;
expires_at?: string;
}
```
### Decision Card UI
In the Mission Control, decisions render as actionable cards:
```
┌─────────────────────────────────────────────────────┐
│ 🟡 APPROVAL HIGH PRIORITY │
├─────────────────────────────────────────────────────┤
│ Campaign brief ready for Q1 launch │
│ │
│ Agent Reasoning: │
│ "Created 3 variants based on past high-performers. │
│ CTAs optimized for mobile. Ready for review." │
│ │
│ Evidence: │
│ • ENG-123: Original campaign request │
│ • Past campaign performance data │
│ │
│ [View Artifact] │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Approve │ │ Reject │ │ Edit │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────┘
```
***
## Decision Flow
```mermaid theme={"dark"}
sequenceDiagram
participant Agent
participant OrgGraph
participant DecisionQueue
participant Human
participant Artifact
Agent->>OrgGraph: Complete work
Agent->>DecisionQueue: Create decision
DecisionQueue->>Human: Notify (Mission Control, ChatGPT, etc.)
Human->>DecisionQueue: Review decision
alt Approved
Human->>DecisionQueue: Approve
DecisionQueue->>Artifact: Ship
Artifact->>OrgGraph: Update state
else Rejected
Human->>DecisionQueue: Reject with feedback
DecisionQueue->>Agent: Route feedback
Agent->>Agent: Revise and retry
else Edited
Human->>Artifact: Edit content
Human->>DecisionQueue: Approve edited
DecisionQueue->>Artifact: Ship edited
end
```
***
## Urgency Levels
Decisions are prioritized by urgency:
| Level | Description | SLA | Notification |
| ------------ | ------------------------------ | -------- | ------------------ |
| **Critical** | Blocking production or revenue | 1 hour | Push + email + SMS |
| **High** | Blocking other work | 4 hours | Push + email |
| **Medium** | Should handle today | 24 hours | Push |
| **Low** | Can batch with others | 72 hours | Badge only |
### Urgency Triggers
Urgency is set based on:
* **Time sensitivity**: Deadlines, SLAs
* **Dependencies**: Is other work blocked?
* **Impact**: Revenue, users, compliance
* **Agent confidence**: Low confidence → higher urgency
***
## Decision Queue
Access decisions from multiple surfaces:
Primary decision queue with full context and batch actions.
Review and approve via natural conversation.
*Coming soon*: Approve directly in Slack threads.
Daily summary of pending decisions.
### Batch Actions
In Mission Control, you can batch-approve similar decisions:
1. Select multiple decisions
2. Review the batch summary
3. Approve all with a single note
Batch approval is convenient but risky. Only batch decisions you've
individually reviewed or that are low-stakes.
***
## Autonomy Settings
Configure when decisions are required:
### Per-Agent Settings
```typescript theme={"dark"}
interface AgentAutonomy {
agent_type:
| 'engineering-agent'
| 'product-agent'
| 'marketing-agent'
| 'sales-agent'
| 'design-agent'
| 'operations-agent'
| 'orchestrator-agent';
level: 'shadow' | 'tutor' | 'supervised' | 'autonomous' | 'full_auto';
budget_threshold: number; // Actions above this $ value require approval
scope_limits: string[]; // Tools that always require approval
}
```
### Autonomy Levels
| Level | Decisions Created | Use Case |
| -------------- | ------------------------------- | ------------------------ |
| **Shadow** | Every action | Learning mode |
| **Tutor** | Every action with explanation | Training |
| **Supervised** | All artifacts before shipping | Default |
| **Autonomous** | Only when budget/scope exceeded | Trusted workflows |
| **Full Auto** | None (dangerous) | Low-risk automation only |
### Adjusting Autonomy
1. Go to **Settings → Agents**
2. Select the agent type
3. Adjust the autonomy slider
4. Optionally set budget thresholds
5. Save changes
Start conservative (Supervised), then gradually increase autonomy as agents
earn trust through the Intelligence Flywheel.
### Autonomous Sessions
At the **Autonomous** or **Full Auto** level, you can start budget-bounded sessions that run while you're away:
* Set `max_cost_usd` and `max_receipts` to cap spending
* Agents work through the IWMT task queue automatically
* Every action generates a receipt in the value ledger
* Review all session output the next morning with `orgx_recommend`
***
## Decision Analytics & the Flywheel
Track decision patterns in Mission Control. Every decision outcome feeds the **Intelligence Flywheel**, improving agent quality over time.
### Metrics
| Metric | Description |
| -------------------- | ---------------------------------------- |
| **Approval Rate** | % of decisions approved vs rejected |
| **Time to Decision** | Average time from creation to resolution |
| **Escalation Rate** | % of decisions that are escalations |
| **Edit Rate** | % of approvals that required edits |
### How Decisions Feed the Flywheel
* **Approvals** increase agent trust for that capability, potentially unlocking higher autonomy
* **Rejections with feedback** become org learnings that prevent repeat mistakes
* **Quality scores** from `record_quality_score` weight future trust calculations
* **Morning brief value signals** via `orgx_recommend` track the ROI and downstream impact of approved decisions
### Proactive Sentinels
Decisions that go unresolved trigger **proactive sentinels**:
* **Pending Decision Sentinel**: Escalates decisions waiting too long
* **Blocked Workstream Sentinel**: Creates decisions when workstreams are stuck waiting
* **Stale Initiative Sentinel**: Flags initiatives with no recent activity
### Insights
High edit rate might indicate:
* Agent prompts need improvement
* Task descriptions are unclear
* Verification checks are too lenient
High rejection rate might indicate:
* Agent selection is wrong for task type
* Autonomy settings are too aggressive
* Context is insufficient
***
## Best Practices
Before looking at the artifact, read the agent's reasoning. It helps you
understand the approach and catch logical errors early.
{' '}
When rejecting, always include feedback. This helps the agent (and the system)
learn what you want. Vague rejections lead to repeated mistakes.
{' '}
If you frequently edit before approving, consider: - Improving task
descriptions - Adjusting agent prompts - Adding constraints to the workflow
spec
{' '}
Stale decisions block agent work. Set aside time daily to clear your decision
queue, or delegate to team members.
Escalation decisions often reveal gaps in your autonomy settings. After
resolving, consider whether to adjust settings to prevent repeat
escalations.
***
## Decision API
For programmatic access, use the decisions API:
```typescript theme={"dark"}
// Get pending decisions
GET /api/decisions?status=pending&urgency=high
// Approve a decision
POST /api/decisions/{id}/approve
{ "note": "Looks good, ship it!" }
// Reject a decision
POST /api/decisions/{id}/reject
{ "reason": "Budget too high, reduce by 20%" }
```
Or via MCP:
```typescript theme={"dark"}
// Get pending decisions
await mcp.tool('orgx_search', {
type: 'decision',
status: 'pending',
limit: 10,
});
// Approve
await mcp.tool('orgx_decide', {
decision_id: 'dec_123',
note: 'Approved',
});
```
`orgx_decide` remains available as a compatibility alias for older clients, but new integrations should prefer `orgx_search`.
***
## Next Steps
Understand how agents create decisions.
Learn about the outputs decisions approve.