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

# Guided Audit Conductor

> Orchestrate the full audit pipeline with automatic step progression, cost previews, and long-job polling.

## What the Guided Audit Conductor is

The Audity MCP server ships an `instructions` brain that turns any connected, instruction-aware agent (Claude, ChatGPT, Cursor) into a guided conductor. It automatically runs the audit pipeline in order, previews cost and time before any paid step, polls long jobs correctly, and flags confidence thresholds.

The conductor handles the orchestration details so you can focus on the workflow prompt.

## Pipeline order

Every audit follows this sequence:

1. **Intake** (create project, upload documents, create interview sessions)
2. **Document analysis** (run `audity_enqueue_document_analysis`, poll `audity_get_job`)
3. **Interview analysis** (run `audity_enqueue_interview_analysis`, poll `audity_get_job`)
4. **Comprehensive audit** (requires BOTH analyses; run `audity_enqueue_audit_analysis`, poll `audity_get_job`)
5. **Opportunities + ROI** (run `audity_select_opportunities`, `audity_create_roi_calculation`)
6. **Deliverables** (PDF, Gamma deck, stakeholder memos; run in parallel: `audity_enqueue_pdf_generation`, `audity_enqueue_gamma_deck`, `audity_enqueue_stakeholder_memos`)

The conductor knows this order and enforces it automatically.

## Confirm-before-spend

Before running any paid or generation step (audit analysis, deliverable generation), the conductor:

1. Calls `audity_get_navigation_status` to check prerequisites
2. Previews the cost (e.g. "\~1,000 credits") and typical time (a comprehensive audit usually runs \~10-15 minutes; lighter steps a few minutes)
3. Waits for your approval before proceeding
4. Continues only after you confirm

This prevents accidental credit overspends and gives you a checkpoint before long operations.

## Long-job polling

The MCP server ships with built-in polling for async jobs:

* `audity_get_job` returns `{ status: "pending" | "completed" | "failed", ... }`
* The conductor polls automatically and knows typical timing per job type: a comprehensive audit usually runs \~10-15 minutes, document and interview analyses a few minutes each, and deliverable jobs return quickly (the file then arrives via callback, see below)

**Important:** A finished Gamma deck or PDF job means generation was **TRIGGERED**, not that the file is ready to download. After generation completes, poll `audity_get_gamma_status` or `audity_get_pdf_status` to confirm the file is ready.

## Grounding and confidence

Findings returned by the API include a `confidence` field (0.0–1.0, typically 0.6–1.0). The conductor flags any finding under 0.8 confidence as a **hypothesis** rather than a fact:

> "Potential opportunity (confidence 0.72): implement RPA for invoice processing. Verify with the client before committing to this initiative."

This reminds you that AI-generated patterns are educated guesses, not assertions.

## Using the conductor in Claude Code

Claude Code supports a `/audit` skill that triggers conductor mode. connect offers to install it while you run `npx @auditynow/connect` (default yes when Claude Code is detected), there is no separate flag.

Then in Claude Code:

```text theme={null}
/audit Start an Audity project for "Acme Corp", mid-market manufacturing. 
Run a comprehensive audit. Summarize the top three opportunities.
```

The `/audit` skill automatically:

* Runs the pipeline in order
* Asks for approval before spend
* Polls jobs correctly
* Flags confidence thresholds
* Reports findings with IDs so you can drill in

## Common prompts (all agents)

```text theme={null}
Start a new audit for {client}, {industry}, {size}. Run the full analysis. 
Give me the top three opportunities ranked by impact.
```

```text theme={null}
Run audit analysis on project {id}. When it's done, pull the opportunities,
rank by ROI potential, and tell me which three are most realistic given the 
client's current IT maturity.
```

```text theme={null}
Generate the PDF and Gamma deck deliverables for project {id}. 
Confirm cost before proceeding.
```

```text theme={null}
What patterns am I seeing across my healthcare clients? 
Pull opportunities from the last three audits, tag by pattern, confidence.
```

## How it differs from direct API calls

| Direct API call                                                                            | Conductor                                          |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| You manually call `audity_enqueue_audit_analysis`, then `audity_get_job` in a polling loop | Conductor enqueues and polls automatically         |
| You verify prerequisites manually (e.g. checking both analyses exist)                      | Conductor checks prerequisites and gates steps     |
| You estimate cost; each `POST /api/projects` deducts 1,000 credits                         | Conductor previews cost before you approve         |
| Confidence fields are raw numbers; you interpret them                                      | Conductor flags under-0.8 confidence as hypotheses |
| You reconstruct the "next step" after each completion                                      | Conductor knows the pipeline order and enforces it |

For simple read-only queries ("list my projects", "fetch opportunities for project X"), direct API calls are fine. For orchestrated workflows (full audits, batch lead conversion, deliverable generation), the conductor saves orchestration logic.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Conductor doesn't start or hangs">
    Ensure you ran `npx @auditynow/connect` and that your tool restarted (especially Claude Code, which loads its MCP servers only at startup). If using Claude Desktop, go to Settings → Connectors and confirm Audity is green (connected).
  </Accordion>

  <Accordion title="Conductor says a prerequisite isn't met">
    The audit pipeline requires both document and interview analyses before running comprehensive audit. If you skipped one, run it via `audity_enqueue_document_analysis` or `audity_enqueue_interview_analysis` first, then retry comprehensive audit.
  </Accordion>

  <Accordion title="Job polling times out or gets stuck">
    A comprehensive audit can take \~10-15 minutes (sometimes longer); lighter jobs finish in a few minutes. If a job hasn't progressed well past its typical time, pull the job details via `audity_get_job` and check for an error message. Restarting the conductor will pick up where it left off.
  </Accordion>

  <Accordion title="PDF or Gamma generation says 'triggered' not 'ready'">
    Correct behavior. Generation jobs return `{ status: "completed" }` when TRIGGERED, not when the file is fully ready. Poll `audity_get_pdf_status` or `audity_get_gamma_status` after generation completes to confirm the file is ready for download.
  </Accordion>
</AccordionGroup>

## What's next

* [Run a full audit workflow →](/guides/running-an-audit), detailed end-to-end recipe (without the conductor)
* [Connect with one command →](/guides/connect-cli), `npx @auditynow/connect` setup
* [Lead conversion playbook →](/guides/lead-conversion), convert ReadyLink leads from your agent