> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dispute Handling Workflow

> Build the deterministic backbone for dispute case handling

The dispute handling workflow is the main orchestrator. It should own the case lifecycle and call agents only for the parts that need judgment.

## What the Workflow Owns

The workflow should control:

* Case state
* Deadline checks
* Branch routing
* Tool call order
* Retry and failure paths
* Human approval gates
* Handoffs to subflows
* Status updates back to the source system

Autonomous agents should not own these process states. They should return structured outputs that the workflow can validate and route.

## Main Flow

```mermaid theme={null}
flowchart TD
  Start["Validated case"] --> Deadline["Check deadline and status"]
  Deadline --> TooLate{"Can still respond?"}
  TooLate -->|No| RecordLoss["Record closed or missed case"]
  TooLate -->|Yes| Classify["Call reason classification agent"]
  Classify --> Branch{"Recommended path"}
  Branch -->|Accept| Accept["Acceptance workflow"]
  Branch -->|Counter| Evidence["Evidence preparation workflow"]
  Branch -->|Withdraw| Withdraw["Withdrawal workflow"]
  Branch -->|Need info| Account["Account communication agent"]
  Account --> Wait["Wait for account response"]
  Wait --> Evidence
  Evidence --> Approval["Human approval workflow"]
  Approval --> Approved{"Approved?"}
  Approved -->|Yes| Submit["Submission or recording workflow"]
  Approved -->|Changes requested| Evidence
  Approved -->|Rejected| Manual["Manual review queue"]
  Submit --> Outcome["Outcome tracking workflow"]
```

## Subflows

Break repeated deterministic logic into callable workflows:

| Subflow                           | Purpose                                                         |
| --------------------------------- | --------------------------------------------------------------- |
| **Case validation workflow**      | Normalize and validate required fields.                         |
| **Deadline workflow**             | Calculate deadline risk and escalation priority.                |
| **Acceptance workflow**           | Record that the business accepts liability or will not contest. |
| **Evidence preparation workflow** | Gather evidence, draft packet, and prepare approval request.    |
| **Human approval workflow**       | Route packet to reviewers and wait for decision.                |
| **Submission workflow**           | Submit to processor or record manual submission.                |
| **Outcome tracking workflow**     | Check outcome, update source systems, and notify stakeholders.  |

<Tip>
  If two use cases need the same approval logic, make that logic a callable workflow instead of rebuilding it inside every blueprint.
</Tip>

## Agent Calls

Use focused agents with clear contracts:

| Agent                           | Called by         | Expected output                                                   |
| ------------------------------- | ----------------- | ----------------------------------------------------------------- |
| **Reason classification agent** | Main workflow     | Reason category, confidence, recommended path, explanation.       |
| **Account communication agent** | Main workflow     | Message draft, requested information, language, next wait state.  |
| **Evidence drafting agent**     | Evidence workflow | Draft narrative, evidence checklist, missing facts, confidence.   |
| **Slack escalation agent**      | Approval workflow | Reviewer decision, comments, required changes, approver identity. |

The workflow should validate the output shape before continuing.

## Branching Guidelines

Use deterministic branches for conditions such as:

* Response deadline has passed
* Case value is above approval threshold
* Required evidence is missing
* Account response is overdue
* Reviewer rejected the evidence packet
* Tool call failed

Use agent judgment for conditions such as:

* Whether the reason text maps to one or more categories
* What clarification to request from the account
* How to summarize evidence in a clear narrative
* Whether reviewer comments imply a specific correction

## Related Docs

<CardGroup cols={2}>
  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    Learn when to use deterministic workflows.
  </Card>

  <Card title="Nodes and Conditions" icon="code-branch" href="/workflows/nodes-and-conditions">
    Build branches, tool nodes, and conditions.
  </Card>

  <Card title="Sub-Agents" icon="diagram-project" href="/agents/sub-agents">
    Call focused agents from workflows and agents.
  </Card>

  <Card title="Guardrails" icon="shield" href="/guardrails/overview">
    Add escalation and restriction rules.
  </Card>
</CardGroup>