CedarCopilot/cedar-mail

# Pipeline Reasoning Research
**Date:** May 2, 2026

## The Problem Statement

We process sales pipeline data, aggregate it, and execute agents on top of it. Currently agents only see events *within* the conversation they are working on — they have no access to org-wide pipeline patterns, won/lost deal baselines, or cross-conversation intelligence. We want to enable an agent to reason over a sales pipeline so it can:

1. **Pattern match**: "Won deals at the proposal stage typically have X, Y, Z — this deal is missing Y."
2. **Recommend interventions**: "You're losing momentum between meetings; won deals at this stage show sell-between activity."
3. **Generate targeted artifacts**: A meeting prep doc, a sell-between agent, a coaching playbook section.

---

## Part 1: Current State of Cedar's Pipeline Data Infrastructure

### 1.1 Two Turbopuffer Namespaces

**Events namespace: `user_{userId}`**
- Every email, meeting, Slack, and external CRM event is chunked and embedded (OpenAI `text-embedding-3-small`, 1536 dims)
- Each vector stores: `eventId`, `conversationId`, `eventType`, `eventTime`, `aopId`, `threadId`, `isSignificant`, `direction`, `emailClassification`
- Supports: semantic ANN search, BM25 keyword (FTS), or hybrid
- Used by agents via `searchTurbopufferTool` — available in the event-execution path
- **Scope: per user, per conversation event — purely retrospective**

**Field values namespace: `org_{orgId}_field_values`**
- CRM custom field values extracted from meeting transcripts by LLM (`extractOrgFieldValues`)
- Each document stores: `fieldId`, `content` (markdown), `outcomeStage`, `stageAtEventTime`, `sourceUserId`, `sourceEventId`, `conversationId`, `extractionConfidence`, `occurredAt`, and flexible `meta_*` attributes
- Two extraction types: **moment** (timestamped verbatim rep quotes + coaching context) and **scorecard** (call quality scores)
- Only embeddable field types are vectorized: `text`, `select`, `number`, `currency` — not `boolean`, `date`, `url`, `phone`
- Min confidence threshold of 0.4 to persist
- **Scope: org-wide, outcome-tagged, stage-tagged**

The `searchOrgFieldValues()` function and its agent wrapper `searchIntelligenceTool` already support filtering by:
- `fieldId` — specific intelligence category (e.g. `_ii_competitive`, `_ii_pricing`)
- `outcomeStage` — `open` | `closed_won` | `closed_lost`
- `stageAtEventTime` — deal stage when the call happened
- `sourceUserId` — filter to a specific rep
- `metadata` — arbitrary k/v (e.g. `{ competitorName: "Salesforce" }`)
- `isListField` — extraction fields vs. working-memory fields

### 1.2 The Existing `sales-intelligence` Skill

The skill wraps `searchIntelligenceTool` + `fetchConversationTool` + `getKnowledgeBaseItemsTool`, loads BANT/SAYA/MEDDPICC methodology resources, and dynamically injects the org's configured field definitions into the prompt. It is available in the **chat path** but **not wired into the event-execution path** (automated pipeline).

### 1.3 The Document Store

Postgres-backed, four scope levels, multiple document types:

| Scope | Description |
|---|---|
| `conversation` | Per-deal docs: `deal_overview`, `deal_strategy`, `meeting_prep`, `research` |
| `chat_thread` | Working memory: `task_canvas`, `task_summary`, `task_buffer`, `chat_history` |
| `user` | Personal persistent: `scratch`, `notes`, `custom`, `attachment`, `agent_file` |
| `org` | Org-wide: `notes`, `custom` — **currently unused by agents in structured ways** |

Documents support:
- Inline Cedar reference syntax: `[[event: id]]`, `[[conversation: id]]`, `[[company: domain]]`, `[[person: email]]`, `[[doc: path]]`
- Read (single doc), list (metadata only), grep (Postgres regex), write (upsert/append/patch)
- Agent tools: `listDocumentsTool`, `readDocumentTool`, `grepDocumentsTool`, `writeDocumentTool`

### 1.4 The Critical Gap

The `org_field_values` namespace has org-wide, outcome-tagged, stage-tagged pipeline intelligence — but it is **only accessible during interactive chat** through the sales-intelligence skill. The automated event-execution agent (which runs on every meeting, email, and CRM event) **never reads it**. There is also **no aggregate view** — no structured representation of what won deals look like, how long deals stay in stages, what sell-between activities correlate with closes. The document system has `org`-scoped docs but no pipeline-level document type and no process for generating or maintaining one.

---

## Part 2: External Research on This Problem

### 2.1 The Three Retrieval Modes for Pipeline Reasoning

The most important finding from research is that "reasoning over a pipeline" is actually **three distinct problems** that need different retrieval approaches:

**Mode 1 — Semantic/Content Search** (Cedar already has this)
- Question: "How have we handled security objections in discovery calls?"
- Answer: Pull examples from the `org_field_values` namespace filtered by fieldId + stageAtEventTime
- Tool: `searchIntelligenceTool` / `searchOrgFieldValues()`
- Pattern: Dense vector ANN + BM25 hybrid

**Mode 2 — Aggregate/Statistical Queries** (Cedar does not have this)
- Question: "What does a won deal look like at the proposal stage? How long do deals typically stall in discovery?"
- Answer: SQL GROUP BY over `crm_custom_field_values` × `crm_conversations` × `crm_events`
- Tool: Does not exist — needs `queryPipelineTool` or equivalent
- Pattern: **ReAcTable** (VLDB 2024) / NL2SQL — iterative SQL + Python generation over intermediate tables

**Mode 3 — Pattern-Matched Recommendations** (Cedar does not have this)
- Question: "Given this deal's current state, what is missing vs. won deals at this stage?"
- Answer: Compare current conversation's field values + stage timing + activity frequency against won-deal baseline
- Tool: Does not exist — needs pre-computed "pipeline intelligence" document + comparison logic
- Pattern: Pre-computed synthesis document + retrieval-time diff

### 2.2 Key Academic References

**ReAcTable (Zhang et al., VLDB 2024 / arXiv 2310.00815)**
The most directly relevant paper. Introduces the ReAcTable framework for Table Question Answering (TQA): the agent iteratively generates SQL or Python to transform the target table into intermediate representations, each iteration simplifying the data until the agent can directly answer. Applied to pipeline data, this means: instead of feeding the agent a raw CSV of all deals, the agent issues a SQL query to get "won deals in Q4 by stage timing," then Python to compute velocity ratios, then answers from that. The key insight: **don't try to reason over raw tabular data in one shot**.

**KG-Enhanced LLM Reasoning (Chen et al., EMNLP 2024)**
"A New Pipeline for Knowledge Graph Reasoning Enhanced by LLMs Without Fine-Tuning" — three-stage pipeline: (1) knowledge alignment (LLM enriches incomplete KG edges), (2) structure-aware KGR model trains on the enriched graph, (3) LLM reranks top-scored entities. Relevant to Cedar in the sense that deals, stages, reps, companies, and field values form a knowledge graph — and LLMs can enrich it (e.g. inferring that a deal with high competitive mentions + long stage stall is a "risk" node).

**K-Paths for KG reasoning (NeurIPS 2025)**
Training-free framework that retrieves multi-hop reasoning paths from KGs as natural language descriptions for LLMs. Applied to Cedar: you could represent "won deals → have sell-between activities → which contain ROI discussions" as a path and surface it to the agent as evidence.

### 2.3 Key Industry References

**Rox's Opportunity Interface** (most architecturally relevant to Cedar)
They unify CRM fields, emails, call transcripts, and meetings into a single opportunity view. The risk detection agent:
- Uses a large context window containing both current activity AND historical resolution state
- A **context manager** deduplicates, excludes previously resolved signals, prunes old context via sliding time window
- Categorizes risk with citations directly back to underlying email/meeting sources
- Key challenge they solved: activity-to-opportunity linking (participant email → opportunity mapping) — Cedar already has this via `conversationId` on every event

**vladkol/crm-data-agent** (NL2SQL pattern)
Gemini 2.5 Pro + BigQuery. The agent interprets questions about business state as reflected in CRM data, generates SQL, creates Vega-Lite diagrams, provides insights + recommended actions. Cedar's equivalent would be a safe query layer over `crm_custom_field_values` + `crm_conversations` instead of open SQL generation.

**Deal Intelligence Pipeline (SaraSoleymani/deal-intelligence)**
4-agent pipeline for meeting prep: Research Agent (web) → CRM Agent (deal history + episodic memory) → Validation Agent (quality gate) → Synthesis Agent (final brief with conflict resolution rules). The conflict resolution rule is key: "CRM data is authoritative for relationship context; research is authoritative for market signals." Cedar's equivalent would be: "field_values data is authoritative for pipeline patterns; live conversation context is authoritative for deal state."

**AI Win/Loss Analysis (MarketBetter, NeuroGTM)**
Patterns that predict wins vs. losses and should be in the "pipeline map":
- Time in stage: deals not closed by day 45 → 70% loss rate
- Stakeholder count: won deals average 2.8 vs. lost deals 1.4
- Finance involvement by Stage 3: 3.2x close rate when finance engaged early
- Competitor mention → win rate drops from 34% to 18%
- Sell-between cadence: activity between meetings correlates strongly with wins
- Stage where deal was decided (not where it was lost): if 60% of losses are decided in Evaluation, that's a demo problem, not a qualification problem

**Salesforce/Production RAG failure modes (Salesforce blog)**
For production pipeline reasoning: use hybrid retrieval (BM25 + dense), always rerank top-K with a cross-encoder, evaluate with Precision@K / MRR / nDCG. State-of-the-art embedding models: `e5-large-v2`. Don't rely solely on semantic search for structured questions.

---

## Part 3: Proposed Architecture — The "Sales Map"

### 3.1 Core Insight

The agent should not reason directly over raw pipeline data — it should reason over a **pre-computed synthesis** that summarizes what patterns matter, with the ability to **drill down** for specific examples. This maps to a two-layer architecture:

```
Layer 1: Pipeline Intelligence Document (org-scoped, pre-computed)
  → Answers: "What does good look like at each stage for this org?"
  → Lives in: DOCUMENT_SCOPE_TYPE.ORG, new DOCUMENT_TYPE.PIPELINE_INTELLIGENCE

Layer 2: Retrieval Tools (on-demand, per-query)
  → Semantic: searchIntelligenceTool (already exists)
  → Aggregate: queryPipelineTool (new)
  → Deal comparison: compareDealToBaselineTool (new)
```

### 3.2 The Pipeline Intelligence Document

A new org-scoped document type that acts as the "sales map." Generated by a background job, refreshed periodically (e.g. weekly or on deal close events). Contains:

```markdown
# Pipeline Intelligence — [Org Name]
**Generated:** [date] | **Deals analyzed:** N won, M lost, K open

## Stage Timing Benchmarks
| Stage | Won avg days | Lost avg days | Risk threshold |
|---|---|---|---|
| Discovery | 12d | 28d | >21d flagged |
| Proposal | 8d | 41d | >20d flagged |
...

## What Won Deals Look Like (by stage)

### Discovery Stage
- **Multi-threading**: 2.4 contacts avg (lost: 1.1)
- **Top rep techniques** (from closed_won field values): [examples from searchOrgFieldValues]
- **Common objections handled**: [from _ii_competitive field, closed_won, stageAtEventTime=discovery]
- **Sell-between patterns**: [email/Slack activity between meetings]

### Proposal Stage
...

## Win/Loss Drivers
**Top 3 win factors** (extracted from field_values, outcomeStage=closed_won):
1. ...
**Top 3 loss factors** (extracted from field_values, outcomeStage=closed_lost):
1. ...

## Competitive Intelligence Summary
[From _ii_competitive field across all outcomes]

## Stage Transition Signals
What moves deals forward from each stage (from stageAtEventTime filters):
...
```

### 3.3 New Tools Needed

**`queryPipelineTool`** — safe structured queries (not open SQL) over pipeline data
- Input: query type (stage_timing, activity_frequency, field_value_distribution, deal_comparison), filters (stage, outcome, dateRange, fieldId)
- Implementation: pre-built query functions wrapping `crm_custom_field_values` × `crm_conversations` × `crm_events` JOINs
- Returns: structured results with deal counts and statistical summaries
- Follows ReAcTable pattern: agent can chain calls to iteratively refine its understanding

**`compareDealToBaselineTool`** — given a conversationId, compare against org baseline
- Loads the pipeline intelligence doc + queries stage timing for the deal's current stage
- Returns: specific gaps vs. won deals ("missing finance stakeholder by Stage 3", "15 days since last customer reply — 72% of stalled deals don't recover after 18 days")

**`generatePipelineIntelligenceDoc`** — background job / tool to regenerate the pipeline map
- Called periodically by cron or on deal-close webhook
- Queries aggregate data, calls `searchOrgFieldValues` with various filters, synthesizes the doc
- Writes to `DOCUMENT_TYPE.PIPELINE_INTELLIGENCE`, `DOCUMENT_SCOPE_TYPE.ORG`, `scopeId = orgId`

### 3.4 How It Flows for the User Examples

**"I want to get better at running discovery calls":**
1. Agent reads `PIPELINE_INTELLIGENCE` doc — gets the discovery stage benchmarks + top techniques from won deals
2. Calls `searchOrgFieldValues({ fieldId: '_ii_discovery_techniques', outcomeStage: 'closed_won', stageAtEventTime: 'discovery', topK: 10 })` to get specific examples with timestamps
3. Cross-references with KB for methodology (BANT/SAYA/MEDDPICC)
4. Writes a `MEETING_PREP` doc with stage-specific questions informed by what worked at this org
5. Creates a meeting prep agent scoped to the next call

**"I'm losing momentum between meetings":**
1. Agent reads `PIPELINE_INTELLIGENCE` doc — finds sell-between activity patterns from won deals
2. Calls `queryPipelineTool({ type: 'activity_frequency', outcome: 'closed_won', stage: currentStage })` to get average email/Slack cadence between meetings in won deals at this stage
3. Compares against this deal's actual cadence (from events timeline)
4. Searches for sell-between content that worked: `searchOrgFieldValues({ fieldId: '_ii_sell_between', outcomeStage: 'closed_won' })`
5. Searches for ROI evidence extracted from meetings: `searchOrgFieldValues({ fieldId: '_ii_roi_evidence', outcomeStage: 'closed_won' })`
6. Writes a `DEAL_STRATEGY` doc with the gap analysis + recommended sell-between plays
7. Creates a sell-between agent with the compiled resources

---

## Part 4: Implementation Phases

### Phase 0: Prerequisites (days 1–3)
- Add `PIPELINE_INTELLIGENCE` to `DOCUMENT_TYPE` in `document-types.ts`
- Confirm `org_field_values` namespace has enough data for the target org to make this useful (the backfill should already cover historical data)
- Add `queryPipelineTool` shell with 2–3 pre-built query types

### Phase 1: Pipeline Intelligence Document (week 1)
- Background job / cron: `generatePipelineIntelligenceDoc` that:
  1. Queries aggregate stage timing from `crm_conversations` (stage history)
  2. Calls `searchOrgFieldValues` with combinations of `outcomeStage` + `stageAtEventTime` + `isListField`
  3. Synthesizes into the markdown pipeline map template
  4. Writes to `DOCUMENT_SCOPE_TYPE.ORG`, `DOCUMENT_TYPE.PIPELINE_INTELLIGENCE`
- Trigger: weekly cron + on `closed_won` / `closed_lost` events

### Phase 2: Wire into Chat Agent (week 2)
- Add `PIPELINE_INTELLIGENCE` to the document management skill's discovery instructions
- Teach the sales-intelligence skill to read the pipeline doc first, then drill down with `searchIntelligenceTool`
- Add `queryPipelineTool` to the sales-intelligence skill's tool set

### Phase 3: Wire into Event-Execution Agent (week 3)
- The event-execution agent (on meeting / email events) should check the pipeline doc + compare the deal against baseline
- On every meeting completion: run `compareDealToBaselineTool`, surface gaps in the conversation update
- This is where the automated "you're losing momentum" detection happens without the user having to ask

### Phase 4: Dynamic Agent Generation (week 4+)
- Based on pattern analysis, the agent proposes and creates specialized sub-agents
- Sub-agents are scoped to a conversation + initialized with the pipeline intelligence as context
- The pipeline doc becomes the "training data" for the sub-agent's instructions

---

## Part 5: Things to Investigate / Open Questions

1. **Stage history**: Do we currently store deal stage transitions with timestamps? The win/loss research depends heavily on "time in stage" — need to confirm `crm_conversations` has this or that it can be inferred from events.

2. **Sell-between detection**: Can we detect email/Slack activity *between* meetings from the existing events data? This requires knowing meeting timestamps and then querying inbound events in the windows between them.

3. **Minimum data threshold**: The pipeline intelligence doc is only useful once an org has enough closed deals. What's the minimum N? The win/loss research suggests 30–40 deals is enough to start seeing patterns. We should gate the feature on this.

4. **Rep-level vs. org-level baseline**: Should the comparison be against the full org's won deals, or the specific rep's won deals? Different reps have different styles. The `sourceUserId` filter in `searchOrgFieldValues` already supports this.

5. **Context window management**: If the pipeline intelligence doc grows large (it will), the agent needs a context manager pattern like Rox's — pruning old/irrelevant signals, de-duplicating, sliding time window. Start with a word limit + summary approach.

6. **The "coaching framework" field**: Currently `crm_custom_field_values.ts` uses `generateCoachingExtractionContext` — what coaching framework context is being injected during extraction? Is this SAYA/BANT methodology? This will determine what's already in the field values vs. what needs to be added.