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

# Complex Reasoning with AI

> Atlas shows its reasoning and proposes a plan before acting on multi-step, consequential work — nothing runs until the human approves.

## When to Use

Use this pattern when work spans multiple steps, a wrong action is costly, and the human owns the outcome.

## When Not to Use

Avoid this pattern for trivial, low-stakes, easily-undone actions.

**Related:** [Match effort to stakes, PR-05](https://service-titan-ai-playbook.vercel.app/principles/match-effort-to-stakes)

## UX Pattern

### Human-Initiated Interaction

#### 1. Atlas proposes an Action Plan

The plan shows the high-level steps Atlas intends to take, each with the reason behind it. Atlas revises the plan as needed, and the conversation doesn't progress until the human approves one.

**Related:** [Action plans, PTN-36](https://service-titan-ai-playbook.vercel.app/patterns/action-plans)

#### 2. Atlas assembles content and reasons through judgment calls

As it assembles and reasons, Atlas shows what it's reading, checking, and assuming. It surfaces this as a one-line summary the human can expand for detail.

**Related:**

* [Show the work, PR-03](https://service-titan-ai-playbook.vercel.app/principles/show-the-work)
* [Working transcript, PTN-16](https://service-titan-ai-playbook.vercel.app/patterns/working-transcript)
* Assemble and Reason steps from the 5 parts

**UX Surface:** Atlas thinking pattern

#### 3. The situation package appears when review needs it

Atlas surfaces the read-only situation package — the context and evidence its reasoning is based on — whenever the human needs to validate that reasoning against the underlying data.

**Related:**

* [Match effort to stakes, PR-05](https://service-titan-ai-playbook.vercel.app/principles/match-effort-to-stakes)
* [Artifacts, PTN-17](https://service-titan-ai-playbook.vercel.app/patterns/artifacts)
* [Verification affordances, PTN-27](https://service-titan-ai-playbook.vercel.app/patterns/verification-affordances)

**UX Surface:** Situation Package

#### 4. Atlas proposes recommendations

Each recommendation carries what Atlas recommends, why, and the evidence it used. It offers the actions the human can take.

**Related:**

* [Approval gates, PTN-31](https://service-titan-ai-playbook.vercel.app/patterns/approval-gates)
* [Suggested actions, PTN-04](https://service-titan-ai-playbook.vercel.app/patterns/suggested-actions)
* [Verification affordances, PTN-27](https://service-titan-ai-playbook.vercel.app/patterns/verification-affordances)

**UX Surfaces:** Atlas in-line message, Suggested Changes pattern

#### 5. The human decides

The human acts on the recommendation, or asks questions and requests changes. Atlas revises and re-presents, and nothing runs until the human confirms.

**Related:**

* [Interrupt and steer, PTN-33](https://service-titan-ai-playbook.vercel.app/patterns/interrupt-and-steer)
* [Keep the human senior, PR-04](https://service-titan-ai-playbook.vercel.app/principles/keep-the-human-senior)
* Decide step from the 5 parts

**UX Surfaces:** User message, Atlas in-line message, Suggested Changes pattern

#### 6. Modify in place

If the human chooses to modify, the content appears in edit mode in the right panel (for now), pre-filled with the selected changes. The human edits fields directly, then saves or cancels.

**Related:** [Reversibility, PTN-32](https://service-titan-ai-playbook.vercel.app/patterns/reversibility)

**UX Surface:** Suggested Changes pattern

#### 7. The human confirms and Atlas acts

Atlas performs the action. Every executed action and decision stays visible for the audit trail.

**Related:** Act step from the 5 parts

**UX Surfaces:** Atlas in-line message, What Atlas Did pattern

#### 8. Atlas proposes the next step

Atlas keeps the conversation moving by bringing the human directly to the next step, or by suggesting next-step options.

**Related:** [Suggested actions, PTN-04](https://service-titan-ai-playbook.vercel.app/patterns/suggested-actions)

### Scheduled or Time-Based Trigger

#### 1. Atlas performs a skill on its own

Atlas triggers on a schedule or an event, without a human initiating it first. Scheduled triggers run at a fixed time — a morning brief at 6am daily, an AR staging scan at 10pm on Mondays. Event triggers fire when something happens — a payment fails, an estimate sits dormant for 48 hours, a job completes.

#### 2. Atlas assembles content and reasons through judgment calls

This step stays invisible in the moment because Atlas runs in the background. Its output becomes the guidance content surfaced in the next step.

**Related:** Assemble and Reason steps from the 5 parts

#### 3. Atlas surfaces guidance in the human's Workspace

When surfacing guidance is part of the skill, Atlas presents one or more recommendations in the human's Workspace. Each piece of guidance carries what Atlas recommends, why, the evidence it used, what it's unsure about, and whether it's one action or several sequenced steps. Atlas offers specific actions — accept, modify, defer, reject, escalate, or assign — using concrete action copy like “Approve and Send” rather than a generic “Accept.”

**Related:**

* [Approval gates, PTN-31](https://service-titan-ai-playbook.vercel.app/patterns/approval-gates)
* [Suggested actions, PTN-04](https://service-titan-ai-playbook.vercel.app/patterns/suggested-actions)
* [Verification affordances, PTN-27](https://service-titan-ai-playbook.vercel.app/patterns/verification-affordances)

**UX Surfaces:** Workspace, recommendations pattern

#### 4. Some recommendations open a guided flow

For recommendations that need more detail — specific line-item changes, for example — the action brings the human into Atlas to walk through a flow. The human allows, denies, or modifies each item individually or in bulk.

**UX Surfaces:** Atlas UI shell, Suggested Changes pattern

#### 5. The human decides

The human accepts, modifies, defers, rejects, escalates, or assigns the recommendation, and can ask Atlas for more information before deciding.

**Related:**

* [Interrupt and steer, PTN-33](https://service-titan-ai-playbook.vercel.app/patterns/interrupt-and-steer)
* [Keep the human senior, PR-04](https://service-titan-ai-playbook.vercel.app/principles/keep-the-human-senior)
* Decide step from the 5 parts

**UX Surfaces:** Workspace, recommendations pattern

#### 6. The human confirms and Atlas acts

Atlas performs the action — it saves the invoice, sends the note, creates the task. High-stakes actions, like customer-facing sends or escalations, sometimes include an explicit confirmation step before execution.

When the action launches inside an Atlas conversation, Atlas confirms what happened in-line. The What Atlas Did section is the person's audit of the act: what actually changed in ServiceTitan, on whose authority, and when. When the action launches a confirmation dialog instead, the recommendation card shows as a completed step once the human confirms.

**Related:** Act step from the 5 parts

**UX Surfaces:** Atlas in-line message, What Atlas Did, recommendations pattern

#### 7. Atlas remembers this interaction

Atlas creates a Decision Trace for every interaction, so the person can audit a past decision and so Atlas gets better over time. The domain team authors two things for every trace:

* **What carries forward** — what goes into Memory versus what stays in the record. Not every trace becomes a lesson: the domain team writes only governed, durable lessons to Memory.
* **At what scope** — customer-level (this customer always short-pays), tenant-level (shop policy), or platform-level. A lesson stays at the person's scope unless the domain team deliberately promotes it.

The Decision Trace stays available on any past guidance: what Atlas assembled, what it reasoned, what it recommended, what the person decided, and what actually happened. This is the causal trust layer in retrospect — the person can always ask why something happened.

**Related:**

* Remember step from the 5 parts
* [Legible Memory, PTN-38](https://service-titan-ai-playbook.vercel.app/patterns/legible-memory)
* [Relationship Continuity, PTN-42](https://service-titan-ai-playbook.vercel.app/patterns/relationship-continuity)

**UX Surfaces:** Decision Trace (surfaced only when the human asks, not revealed by default), What Atlas Did

## Do / Don't

<Check>**Do**</Check>

* State each step's concrete impact — the specific records, recipients, or amounts it touches — so a wrong step is easy to spot
  * [Action plans, PTN-36](https://service-titan-ai-playbook.vercel.app/patterns/action-plans)
* Let the human edit the plan — remove, reorder, or adjust steps — before running, not just approve or reject it whole
  * [Action plans, PTN-36](https://service-titan-ai-playbook.vercel.app/patterns/action-plans)
  * [Keep the human senior, PR-04](https://service-titan-ai-playbook.vercel.app/principles/keep-the-human-senior)
* Approve once at the plan level, then run the full sequence without re-asking about each step
  * [Action plans, PTN-36](https://service-titan-ai-playbook.vercel.app/patterns/action-plans)
* Stop and re-present the plan if a step fails or the approach changes mid-run — never improvise silently
  * [Action plans, PTN-36](https://service-titan-ai-playbook.vercel.app/patterns/action-plans)
* Let the human interrupt and redirect mid-run without losing completed work
  * [Interrupt and steer, PTN-33](https://service-titan-ai-playbook.vercel.app/patterns/interrupt-and-steer)
  * [Keep the human senior, PR-04](https://service-titan-ai-playbook.vercel.app/principles/keep-the-human-senior)

<Danger>**Don't**</Danger>

* Ask for approval on a vague plan, like “update the relevant records” — the human should know exactly what they're approving
  * [Action plans, PTN-36](https://service-titan-ai-playbook.vercel.app/patterns/action-plans)
  * [Keep the human senior, PR-04](https://service-titan-ai-playbook.vercel.app/principles/keep-the-human-senior)
* Show one plan, get approval, then execute a different one
  * [Action plans, PTN-36](https://service-titan-ai-playbook.vercel.app/patterns/action-plans)
* Put trivial steps behind a full plan — it teaches people to approve without reading
  * [Match effort to stakes, PR-05](https://service-titan-ai-playbook.vercel.app/principles/match-effort-to-stakes)
  * [Action plans, PTN-36](https://service-titan-ai-playbook.vercel.app/patterns/action-plans)
* Make reviewing the plan cost more than doing the task itself
  * [Keep the human senior, PR-04](https://service-titan-ai-playbook.vercel.app/principles/keep-the-human-senior)
* Expose raw tool logs — summarize, and let the human expand for detail
  * [Show the work, PR-03](https://service-titan-ai-playbook.vercel.app/principles/show-the-work)
  * [Progressive disclosure, PTN-18](https://service-titan-ai-playbook.vercel.app/patterns/progressive-disclosure)