> ## 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.

## 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

> [!NOTE]
>
> 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

> [tab] Approval
>
> > [card] Approval Decision
> >
> > Agent completed work and needs sign-off before shipping.
>
> **Examples**:
>
> * PR ready for human merge review
> * Campaign brief ready for send review
> * Outreach sequence ready for launch review
>
> **Actions**:
>
> * **Approve**: Record approval or authorize the configured next step
> * **Reject**: Send back with feedback
> * **Edit**: Modify before approving

> [tab] Escalation
>
> > [card] Escalation Decision
> >
> > 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

> [tab] Clarification
>
> > [card] Clarification Decision
> >
> > 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

> [tab] Conflict
>
> > [card] Conflict Decision
> >
> > 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

A decision can include:

```typescript theme={"dark"}
interface OrgDecision {
  id: string;
  type: 'approval' | 'escalation' | 'clarification' | 'conflict';

  // Context
  title: string;
  description: string;
  rationale_summary: 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  │
├─────────────────────────────────────────────────────┤
│ <work_title> ready for review                       │
│                                                     │
│ Rationale:                                          │
│ "Three variants use the supplied brief and mobile    │
│  constraints. Ready for review."                   │
│                                                     │
│ Evidence:                                           │
│ • <source_reference>: Original request             │
│ • <evidence_reference>: Supporting evidence        │
│                                                     │
│ [View Artifact]                                     │
│                                                     │
│ ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│ │ Approve  │  │  Reject  │  │   Edit   │          │
│ └──────────┘  └──────────┘  └──────────┘          │
└─────────────────────────────────────────────────────┘
```

***

## Decision Flow

```mermaid theme={"dark"}
sequenceDiagram
    participant Agent
    participant OrgGraph
    participant DecisionQueue
    participant Human
    participant Artifact

    Agent->>OrgGraph: Record work and evidence
    Agent->>DecisionQueue: Create decision
    DecisionQueue->>Human: Notify (Mission Control, ChatGPT, etc.)
    Human->>DecisionQueue: Review decision

    alt Approved
        Human->>DecisionQueue: Approve
        DecisionQueue->>Artifact: Record decision or dispatch eligible action
        Artifact->>OrgGraph: Record resulting state when available
    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: Record edited version
    end
```

***

## Urgency Levels

Urgency is a prioritization signal, not a promised response time or delivery
SLA. The exact levels and notifications available depend on the surface and
workspace configuration.

| Level | Meaning |
| - | - |
| **Critical** | A decision may block a high-impact outcome. |
| **High** | A decision is blocking dependent work or has material impact. |
| **Medium** | A decision is useful to resolve in the current work cycle. |
| **Low** | A decision can usually be reviewed in a batch. |

### Urgency Triggers

Urgency is set based on:

* **Time sensitivity**: Deadlines, SLAs
* **Dependencies**: Is other work blocked?
* **Impact**: Revenue, users, compliance
* **Evidence quality and uncertainty**: Less supporting evidence can increase urgency

***

## Decision Queue

Depending on the workspace and client, decisions may be accessible from:

> [card] Mission Control
>
> Primary decision queue with relevant context and batch actions.

> [card] ChatGPT
>
> Review and approve via natural conversation.

> [card] Configured notifications
>
> Notifications or summaries when the connected surface supports them.

### Batch Actions

Where the client supports batch actions, you can batch-approve similar
decisions:

1. Select multiple decisions
2. Review the batch summary
3. Approve all with a single note

> [!WARNING]
>
> 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** | Actions are proposed for review | Learning or observation |
| **Tutor** | Actions include public context before review | Training |
| **Supervised** | Configured consequential actions require review | Review-first default |
| **Autonomous** | Review is required at configured budget or scope boundaries | Trusted workflows |
| **Full Auto** | No decision is inserted for configured low-risk actions | Only where explicitly enabled |

### 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

> [!TIP]
>
> Start conservative (Supervised), then gradually increase autonomy as agents
> earn trust through the Intelligence Flywheel.

### Autonomous Sessions

If the **Autonomous** or **Full Auto** level is enabled for a workspace, a
client may start a budget-bounded session that runs without an interactive
turn:

* Set `max_cost_usd` and `max_receipts` to cap spending
* Agents work through the IWMT task queue automatically
  * Eligible actions can generate a receipt in the value ledger
* Review all session output the next morning with `orgx_recommend`

***

## Decision Analytics & the Flywheel

Track decision patterns where the client provides those views. Eligible decision
outcomes can inform OrgX learning and trust signals; recording a decision does
not itself prove improved agent quality.

### 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** may contribute to trust signals for that capability, subject to policy
* **Rejections with feedback** become org learnings that prevent repeat mistakes
* **Quality scores** from `record_quality_score` weight future trust calculations
* **Recommendation or value signals** can summarize available downstream evidence

### Proactive Sentinels

Where configured, unresolved work can produce follow-up signals:

* **Pending decision signal**: Highlights decisions waiting for review
* **Blocked workstream signal**: Highlights workstreams waiting on a decision
* **Stale initiative signal**: Highlights 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

> [accordion] Review the rationale and evidence
>
> Review the concise rationale, supporting evidence, and artifact together.
> Together they show the observable basis for the proposed action.

&#x20;

> [accordion] Provide Feedback on Rejections
>
> When rejecting, always include feedback. This helps the agent (and the system)
> apply the decision on the next attempt. Vague rejections lead to repeated
> mistakes.

&#x20;

> [accordion] Use Edit Sparingly
>
> If you frequently edit before approving, consider: - Improving task
> descriptions - Adjusting agent prompts - Adding constraints to the workflow
> spec

&#x20;

> [accordion] Don't Let Decisions Pile Up
>
> Stale decisions block agent work. Set aside time daily to clear your decision
> queue, or delegate to team members.

> [accordion] Review Escalations Carefully
>
> Escalation decisions often reveal gaps in your autonomy settings. After
> resolving, consider whether to adjust settings to prevent repeat
> escalations.

***

## Programmatic review

Decision review is MCP-first in the current public surface. Use the published
MCP decision tool to list, create, approve, reject, or remember a decision.
There is no public REST `/api/decisions` resource in the published contract.

```typescript theme={"dark"}
// Example request shape; IDs and results vary by workspace.
await mcp.tool('orgx_search', {
  type: 'decision',
  status: 'pending',
  limit: 10,
});

// Approve
await mcp.tool('orgx_decide', {
  action: 'approve',
  decision_id: '<decision_id>',
  note: 'Approved after reviewing the artifact and evidence',
});
```

See [MCP Tools](https://docs.useorgx.com/docs/api/mcp-tools.md) for the current schema and
[REST API Reference](https://docs.useorgx.com/docs/api/public-api.md) for the REST operations that are actually
published.

***

## Next Steps

> [card] [Agents](https://docs.useorgx.com/docs/platform/agents.md)
>
> Understand how agents create decisions.

> [card] [Artifacts](https://docs.useorgx.com/docs/platform/artifacts.md)
>
> Learn about the outputs decisions approve.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.