Integration Plan: Avoma Notes into Extraction Pipeline

Based on Phase 1 (structure analysis) and Phase 2 (comparison analysis) findings.

Strategy: Supplement, Don't Replace

Avoma notes and Claude extraction are complementary systems with different strengths:

• Claude extraction → insight quality (verbatim quotes, speaker attribution, interest scoring, positioning)
• Avoma notes → deal mechanics (action items, decision authority, deployment risks, current workflow)

Integration approach: Three additions, one enhancement.

Integration 1: Add actionItems to schema (from Avoma notes)

Why: Action items are the highest-value new data. Present in 100% of calls, person-attributed with timestamps. Our nextSteps captures commitments; action items capture concrete deliverables.

Schema addition (schemas/call.ts):

export interface ActionItem {
  text: string          // what needs to be done
  owner: string         // who is responsible
  timestamp?: string    // time in call (mm:ss)
  source: 'avoma'       // always from Avoma notes (not Claude extraction)
}

Add to CallData:

export interface CallData {
  // ... existing fields ...
  actionItems?: ActionItem[]  // optional, populated from Avoma notes
}

Pipeline change: Parse Avoma notes for highlight_category_action_item section blocks. This can happen in build-index.ts at index time (no re-extraction needed) or via a new pipeline/enrich-from-notes.ts script.

Data flow:

Avoma API → notes JSON → parse action_item section → inject into processed JSON

Not added to Claude extraction prompt — action items are factual data Avoma extracts well.

Integration 2: Add decisionMaking to Claude extraction prompt

Why: Decision-maker identification is critical for deal progression. Avoma captures this in 3/5 calls, but Claude would produce higher quality output with verbatim quotes and speaker attribution.

Schema addition (schemas/call.ts):

export interface DecisionMaking {
  decisionMaker?: string      // name of the person with authority
  authority?: string           // description of their authority level
  process?: string             // how decisions are made (committee, sole authority, etc.)
  approvers?: string[]         // other people who need to sign off
  verbatim?: string            // exact quote revealing decision dynamics
  speaker?: string
  confidence: 'high' | 'medium' | 'low'
}

Add to CallData:

export interface CallData {
  // ... existing fields ...
  decisionMaking?: DecisionMaking  // optional, from Claude extraction
}

Prompt addition (pipeline/prompts/extract-call.md): Add a decisionMaking section to the output schema with extraction guidelines emphasizing: who has budget authority, who can approve a POC, what the procurement process looks like.

Integration 3: Add risks to Claude extraction prompt

Why: Risks/blockers are distinct from objections (prospect pushback) and pain points (pre-existing problems). Risks are deployment obstacles that need mitigation — CrowdStrike eBPF conflicts, missing object stores, custom Envoy filter requirements. Avoma captures these in 4/5 calls but they'd benefit from Claude's verbatim + speaker attribution treatment.

Schema addition (schemas/call.ts):

export interface Risk {
  text: string
  verbatim?: string
  speaker?: string
  category: RiskCategory
  confidence: 'high' | 'medium' | 'low'
}

export type RiskCategory =
  | 'technical-compatibility'    // conflicts with existing tools (CrowdStrike, eBPF)
  | 'deployment-blocker'         // missing prerequisites (object store, namespace setup)
  | 'organizational'             // approval needed, wrong team, internal politics
  | 'security-privacy'           // data sensitivity, privacy policy conflicts
  | 'resource-constraints'       // team bandwidth, competing priorities

Add to CallData:

export interface CallData {
  // ... existing fields ...
  risks?: Risk[]  // optional, from Claude extraction
}

Prompt addition: Add a risks section to the output schema with guidelines distinguishing risks from objections. Key distinction: an objection is "I don't think this will work" (pushback); a risk is "our CrowdStrike agent also uses eBPF" (a factual obstacle).

Enhancement: Feed Avoma notes as supplementary context

Why: Avoma notes provide a "second opinion" that can help Claude catch edge cases. Phase 2 comparison found several items Avoma caught that Claude missed (certificate rotation pain in Brooks, Datadog competitive framing in Starbucks/Wunderkind).

Implementation: When both transcript and Avoma notes are available, inject notes as supplementary context in the extraction prompt.

Data flow:

data/raw/{uuid}.txt          → transcript (primary)
data/raw/{uuid}.notes.json   → Avoma notes (supplementary)

Pipeline changes to extract.ts:

1. Check for notes sidecar file at data/raw/{uuid}.notes.json
2. If found, parse into readable text (reuse blocksToMarkdown from fetch script)
3. Inject into prompt before ## Transcript section:

## Avoma AI Notes (supplementary context)
The following AI-generated notes were produced by Avoma's meeting intelligence system.
Use these as supplementary context — they may surface details the transcript alone misses.
Do NOT treat these as ground truth. If the notes conflict with the transcript, trust the transcript.

{notes markdown}

Pipeline changes to avoma.ts:

1. When fetching a call, also fetch notes via GET /notes/?meeting_uuid={uuid}
2. Save raw notes JSON as data/raw/{uuid}.notes.json sidecar

Prompt guidance: Add a note to the extraction guidelines:

If Avoma AI Notes are provided, use them to identify insights you might otherwise miss. But always verify against the transcript — Avoma sometimes misattributes speakers or conflates features demoed with features requested.

Implementation Order

Steps 3+4 both require re-extraction, so they should be batched together in step 5. Step 2 can happen independently — parse notes into action items without re-extraction.

Estimated batch re-extraction cost: ~$0.90 for 22 calls (based on c5 benchmark of $0.037/call, slightly more input tokens from notes context).

Dashboard Implications

New fields unlock new visualizations (to be designed in a future cycle):

• Action items view — across all calls, who owes what, overdue items
• Decision maker map — per company, who has authority, approval chains
• Risk heatmap — common deployment blockers across prospects
• Deal readiness score — composite of interest + urgency + decision maker identified + risks mitigated

What NOT to Do

• Don't use Avoma's Pain Point, Feature Mention, or Positive Moment sections to populate our extraction. Claude's extraction is higher quality for these (better speaker attribution, distinguishes features requested from features demoed, doesn't misattribute team member quotes).
• Don't store Avoma notes in the processed JSON. Notes are supplementary context for extraction, not a data source to persist. The exception is action items, which we parse and store.
• Don't add currentWorkflow or background as structured fields. These are useful for reading but too free-form to structure reliably. They live fine in the summary and company.description fields.