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

<Info>
  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.
</Info>

***

## Decision Types

<Tabs>
  <Tab title="Approval">
    <Card title="Approval Decision" icon="check">
      Agent completed work and needs sign-off before shipping.
    </Card>

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

  <Tab title="Escalation">
    <Card title="Escalation Decision" icon="arrow-up">
      Agent hit its autonomy limit and needs permission to proceed.
    </Card>

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

  <Tab title="Clarification">
    <Card title="Clarification Decision" icon="question">
      Agent needs more context to proceed effectively.
    </Card>

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

  <Tab title="Conflict">
    <Card title="Conflict Decision" icon="code-branch">
      Agent detected competing priorities or blocking dependencies.
    </Card>

    **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
  </Tab>
</Tabs>

***

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

<CardGroup cols={2}>
  <Card title="Mission Control" icon="compass">
    Primary decision queue with relevant context and batch actions.
  </Card>

  <Card title="ChatGPT" icon="comments">
    Review and approve via natural conversation.
  </Card>

  <Card title="Configured notifications" icon="envelope">
    Notifications or summaries when the connected surface supports them.
  </Card>
</CardGroup>

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

***

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

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

<AccordionGroup>
  <Accordion title="Review the rationale and evidence">
    Review the concise rationale, supporting evidence, and artifact together.
    Together they show the observable basis for the proposed action.
  </Accordion>

  {' '}

  <Accordion title="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.
  </Accordion>

  {' '}

  <Accordion title="Use Edit Sparingly">
    If you frequently edit before approving, consider: - Improving task
    descriptions - Adjusting agent prompts - Adding constraints to the workflow
    spec
  </Accordion>

  {' '}

  <Accordion title="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>

  <Accordion title="Review Escalations Carefully">
    Escalation decisions often reveal gaps in your autonomy settings. After
    resolving, consider whether to adjust settings to prevent repeat
    escalations.
  </Accordion>
</AccordionGroup>

***

## 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](/docs/api/mcp-tools) for the current schema and
[REST API Reference](/docs/api/public-api) for the REST operations that are actually
published.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/docs/platform/agents">
    Understand how agents create decisions.
  </Card>

  <Card title="Artifacts" icon="file-lines" href="/docs/platform/artifacts">
    Learn about the outputs decisions approve.
  </Card>
</CardGroup>