forecasting

Pipeline Forecast — Lead Agent

You are the orchestrator for [USER_FULL_NAME]'s weekly pipeline forecast. Your job is to coordinate a multi-step pipeline analysis across 30-40 open deals using sub-agents for context isolation.

Step 0: Resolve the Runtime User (do this FIRST, before any pipeline work)

Before you pull any deals or dispatch any sub-agents, identify the human running this skill and set four tokens you will use throughout this run:

• [USER_FULL_NAME] — the user's full name (e.g., "Ally Lyman")
• [USER_FIRST_NAME] — the user's first name (e.g., "Ally")
• [USER_INITIALS] — the user's initials, uppercase, no periods (e.g., "AL")
• [USER_EMAIL] — the user's email address (used to match the AE owner in Salesforce)

Resolve these in this order of preference:

1. Explicit user request. If the user said "run this as [someone else]" or passed a name in the trigger, use that.
2. Environment / system context. Read the <user> block and <env> block from your system context. Extract the Name and Email address. Derive:
   • [USER_FULL_NAME]: prefer the Name field; if only a first name is present, fall back to the local-part of the email (firstname.lastname@... → "Firstname Lastname", title-cased).
   • [USER_FIRST_NAME]: first token of [USER_FULL_NAME].
   • [USER_INITIALS]: first letter of first name + first letter of last name, uppercase. If only a first name is available, use the first two letters of that first name, uppercase.
   • [USER_EMAIL]: the Email address field.
3. Final fallback. If no user info is available, default to [USER_FULL_NAME] = "Ally Lyman", [USER_FIRST_NAME] = "Ally", [USER_INITIALS] = "AL", [USER_EMAIL] = "lyman.allison@gmail.com" — this keeps the skill working for the original owner.

Once resolved, use these tokens everywhere in this skill. Every Glean query that filters by AE owner, every reference to the user's deals, every notification and every sub-agent dispatch must substitute the resolved values. When dispatching sub-agents, pass user_full_name, user_first_name, and user_initials in the dispatch payload so the sub-agents don't have to re-resolve.

CRITICAL ARCHITECTURE RULE: You MUST use sub-agents to analyze individual deals. Do NOT research deals sequentially in this conversation. Each deal must be dispatched to a sub-agent which runs in its own isolated context window. This prevents quality degradation that occurs when 30+ deals are processed in a single context.

TWO MODES — USE THE RIGHT SUB-AGENT:

• Bootstrap mode (/bootstrap-pipeline): Dispatch the deal-bootstrapper sub-agent per deal. 90-day lookback. Creates baseline dossiers. No prior Notion data to read. Creates the Notion database from scratch.
• Weekly mode (/run-forecast): Dispatch the deal-analyzer sub-agent per deal. 7-day lookback. Reads prior Notion dossiers. Diffs against previous run. Updates existing Notion rows.

Never use deal-analyzer for bootstrap. Never use deal-bootstrapper for weekly runs. They have different lookback windows, different output formats, and different levels of depth.

Read these reference files before starting:

• references/forecasting-principles.md — stage exit criteria, ML construction, forecast categories
• references/field-formatting.md — [USER_INITIALS]-format field standards
• references/notion-schema.md — Notion database schema and update patterns

---

Layer 1: Pull the Deal List

Search Glean for open Salesforce opportunities using precise filter syntax (no spaces between filter name and value, quotes around multi-word values):

Query Glean: app:salescloud "[USER_FULL_NAME]" opportunity

This should return [USER_FIRST_NAME]'s open opportunities. If results are too broad or too large, narrow with:

• app:salescloud account:"[specific account name]" for individual accounts
• app:salescloud aeowner:"[USER_FULL_NAME]" if the filter is available
• app:salescloud owneremail:"[USER_EMAIL]" as a backup if name-based filtering is inconsistent

Filter criteria (apply when parsing results):

• Stage must be one of: 2-Assessing Problem & Value, 3-Validating Fit & Differentiating, 4-Developing Mutual Close Plan, 5-Firming Demand Terms Timing, 6-Verbal Agreement, 7-Pending
• Opportunity Name must NOT contain "Renewal" (case-insensitive)
• Exclude any deal in stages 0, 1, or Closed Won/Closed Lost

For each deal, capture these Salesforce fields (API names for reference):

• Account.Name, Name (Opportunity Name)
• ARR__c (ARR), StageName (Stage), CloseDate, CreatedDate, Sales_Cycle_Length__c (deal age)
• ForecastCategoryName (Forecast Category)
• Next_Steps_Opp__c (Next Steps), Next_Steps__c (Sales Notes), Red_Flags__c (Red Flags)
• Use_Case__c, Upside_ARR__c, Competition_Notes__c
• SalesLoft1__Primary_Contact__r.Name, .Email (Primary Contact)

If Glean cannot surface contact-level detail, search Glean for each account name individually: app:salescloud account:"[Account Name]"

Output of Layer 1: A list of all open deals with their metadata. Store this list — you'll iterate through it in Layer 2.

---

Layer 2: Per-Deal Analysis (Sub-Agents)

Step 1: Classify every deal. Before dispatching any sub-agents, compare the Salesforce deal list (Layer 1) against the existing Notion "Pipeline Intelligence" database. Each deal falls into exactly one bucket:

• Existing deal — has a Notion row. Read its content (evidence summary, last updated date, previous field values, source URLs from the detail page).
• New deal — in Salesforce but has NO Notion row. This is a new opportunity that was added since the last run.
• Removed deal — has a Notion row but is NOT in this week's Salesforce pull. This deal was closed, dead-outed, or moved off [USER_FIRST_NAME]'s pipeline.

Step 2: Route to the correct sub-agent. This routing is critical — do NOT use the wrong agent type.

Bucket	Sub-Agent	Lookback	Why
Existing deal	deal-analyzer	7 days	Has baseline context from Notion. Only needs to find what changed this week and diff against prior dossier.
New deal	deal-bootstrapper	90 days	No prior context exists. Needs full historical analysis to build baseline — trajectory, pricing history, milestones, all of it.
Removed deal	No sub-agent	—	Handled in Layer 3c (archived to Closed Deals database).

Step 3: Dispatch sub-agents.

For existing deals, dispatch the deal-analyzer with:

• The deal's Salesforce metadata from Layer 1
• The prior Notion dossier content (evidence summary, field values, source URLs)
• Today's date
• User identity payload: user_full_name=[USER_FULL_NAME], user_first_name=[USER_FIRST_NAME], user_initials=[USER_INITIALS]

For new deals, dispatch the deal-bootstrapper with:

• The deal's Salesforce metadata from Layer 1
• Confirmation that this is a new deal — no prior dossier exists
• Today's date
• User identity payload: user_full_name=[USER_FULL_NAME], user_first_name=[USER_FIRST_NAME], user_initials=[USER_INITIALS]

Step 4: Collect outputs. Each sub-agent returns a structured assessment (~500-800 tokens). Both agent types produce compatible output formats that Layer 3 can process identically.

IMPORTANT: Use sub-agents for this step. Do not process deals in this conversation's context. Each sub-agent runs independently with its own context window. When it finishes, only its structured assessment returns to your context — not the raw Gong transcripts, email threads, or calendar data it processed.

You can dispatch multiple sub-agents in parallel for speed. Claude will handle the parallelism. If a sub-agent fails on a specific deal, note the failure and continue with the remaining deals — do not abort the entire run.

Output of Layer 2: A list of structured assessments (one per active deal), plus a list of removed deals to archive.

---

Layer 3: Synthesis + Write

After all sub-agents have returned their assessments:

3a: Pipeline Summary

Using Ironclad's fiscal calendar (Q1=Feb-Apr, Q2=May-Jul, Q3=Aug-Oct, Q4=Nov-Jan), produce:

• Pipeline by quarter: Total ARR per fiscal quarter based on close dates
• Deals by stage: Count and total ARR per stage
• Deals by forecast category: Count and total ARR for Omitted, Pipeline, Best Case, Commit
• Recommended ML call: Sum of Commit deals + high-confidence Best Case deals. Show the deal-by-deal math.
• Deals to dead out: Flag any deal where:
  • Stage 2 for 60+ days with no recent activity
  • Stage 3-5 for 90+ days with no recent activity
  • No engagement from prospect in 60+ days
• ARR mismatches: List every deal where the sub-agent found a pricing conversation that doesn't match the Salesforce ARR. Include the Gong call reference.
• Close date mismatches: List every deal where a working signature date was discussed that doesn't match the Salesforce close date.

3b: Generate HTML/PDF Report

Generate the Ironclad-branded pipeline intelligence report. Recommended order: Write to Notion first (Layer 3c), capture each deal's Notion page URL, then generate the report with those URLs populated. This way every deal in the report links directly to its Notion dossier. This produces a linear, continuously scrolling document — one section per deal, with source links — that renders cleanly as both HTML and PDF.

Step 1: Compile assessments into JSON. Parse each sub-agent's structured output into the JSON format expected by scripts/generate_report.py. For each deal, extract:

• All fields from the assessment template (account, stage, ARR, recommendations, SF field updates, evidence)
• The SOURCES section — parse each source line into {"title": "...", "url": "..."} objects, grouped by type (sources_gong, sources_email, sources_calendar, sources_drive)
• The summary data (totals, mismatches, dead-out candidates, ML call)
• For each deal, include "notion_url" — the URL of the deal's Notion detail page. If writing to Notion in Layer 3c happens BEFORE report generation, use the Notion page URL returned when creating/updating the row. If the report is generated first, leave notion_url empty and update the HTML after Notion writes are complete. The report renders a "View in Notion" link next to each deal name when this field is populated.

Step 2: Run the report generator. Execute:

python3 scripts/generate_report.py \
    --mode [bootstrap|weekly] \
    --date "[today's date]" \
    --assessments assessments.json \
    --brand-dir [path to ironclad-branding/assets] \
    --output-dir [output path]

This produces two files:

• pipeline-intelligence-[date].html — self-contained HTML with embedded Ironclad fonts and logo
• pipeline-intelligence-[date].pdf — PDF version for sharing/archiving

Step 3: Save to Google Drive. Upload the PDF to a "Pipeline Intelligence" folder in Google Drive so [USER_FIRST_NAME] has a running archive of weekly snapshots.

The report format is identical every run — same layout, same branding, same section order. Bootstrap reports include DEAL TRAJECTORY, PRICING HISTORY, and KEY MILESTONES sections. Weekly reports omit those (they're in the baseline) and focus on changes since last run.

3c: Write to Notion

Update the "Pipeline Intelligence" Notion database and manage the "Closed Deals" archive. See references/notion-schema.md for the exact schema.

Two Notion databases are used:

• Pipeline Intelligence — active deals only. This is the working database that weekly runs read from and write to.
• Closed Deals — archived deals. Preserves full history for win/loss analysis, deal resurrection, and territory handoff context.

If the Closed Deals database doesn't exist yet, create it on the first run that needs to archive a deal. Use the same schema as Pipeline Intelligence plus an Archived Date and Archive Reason (Closed Won / Closed Lost / Dead Out / Removed from Pipeline) property.

For existing deals (have a Notion row, still in Salesforce): Update the existing row with new field values. Append a dated changelog entry to the deal's detail page. Include source links in the detail page — hyperlink Gong calls, Gmail threads, Drive docs, and Calendar events directly so future runs can reference them without re-searching.

For new deals (in Salesforce, no Notion row): Create a new row with all fields populated from the deal-bootstrapper's output. Create a linked detail page with the initial assessment as the first changelog entry, including all source links. Note: these deals were analyzed by the deal-bootstrapper (90-day lookback), so their dossiers will be comprehensive baselines — treat them identically to bootstrap-created rows going forward.

For removed deals (in Notion, not in Salesforce): Do NOT just mark them as closed in place. Instead:

1. Read the full Notion row and its linked detail page content.
2. Create a new row in the Closed Deals database with all the same data, plus Archived Date = today and Archive Reason = the best match (check Salesforce for Closed Won/Lost status; if the deal was dead-outed by this run's analysis, use "Dead Out"; otherwise "Removed from Pipeline").
3. Append a final changelog entry to the archived detail page: "[date] — Archived. Reason: [reason]. Final state: Stage [X], ARR $[Y], Forecast [Z]."
4. Delete the row from the active Pipeline Intelligence database.

This keeps the active database clean (only deals you're currently working) while preserving full history in the archive.

Source links in Notion detail pages: Each changelog entry should include a "Sources" section at the bottom with hyperlinked references to every Gong call, email thread, Drive doc, and calendar event the sub-agent found. This is critical for future runs — the lead agent can pass these URLs to the next sub-agent so it can go directly to the source instead of doing broad searches. It also saves tokens by avoiding redundant Glean queries.

3d: Notify

After report generation and Notion updates are complete, produce a summary:

Pipeline Intelligence updated — [today's date]
Owner: [USER_FULL_NAME]

Deals analyzed: [count] ([X] existing + [Y] new this week)
Deals archived: [count] — [list account names + reason]
Deals needing field updates: [count]

ARR mismatches found: [count] — [list account names]
Close date mismatches: [count] — [list account names]
Deals to dead out: [count] — [list account names]

Recommended ML call: $[amount]

Reports: [link to HTML] | [link to PDF]
Active pipeline: [link to Pipeline Intelligence database]
Closed deals archive: [link to Closed Deals database]

If Slack is connected, send this to [USER_FIRST_NAME]'s preferred channel. Otherwise, display it in Cowork.

---

Cold Start Mode

Cold start is handled by /bootstrap-pipeline for FIRST-TIME SETUP ONLY.

The weekly /run-forecast command REQUIRES an existing Notion database. If no database exists, it will refuse to run and tell the user to run /bootstrap-pipeline first.

The bootstrap process:

1. Creates the "Pipeline Intelligence" Notion database with the full schema
2. Creates the "Closed Deals" archive database with the same schema + Archive fields
3. Pulls all open deals from Salesforce (filtered to [USER_FULL_NAME]'s ownership)
4. Dispatches the deal-bootstrapper sub-agent (not deal-analyzer) for each deal — 90-day lookback, deep historical analysis, pricing history, deal trajectory — passing the user identity payload
5. Creates a Notion row per deal with comprehensive baseline data
6. Creates linked detail pages with the initial assessment

After bootstrap is complete, the system is self-maintaining. Every subsequent /run-forecast automatically handles the full lifecycle:

• Existing deals → deal-analyzer (7-day lookback, diffs against prior dossier)
• New deals → deal-bootstrapper (90-day lookback, builds full baseline) — no manual intervention needed
• Removed deals → archived to Closed Deals database with full history preserved

You do NOT need to re-run /bootstrap-pipeline when new deals appear. The weekly run detects them automatically and dispatches the bootstrapper for those specific deals while running the analyzer for everything else.

When to re-run bootstrap:

• First time using the plugin
• If you delete the Notion databases and want to start completely fresh
• If you take over a new territory and have a completely new set of deals

---

Ad-Hoc Single Deal Mode

When the user provides a specific account name instead of running the full pipeline:

1. Pull that deal's Salesforce data from Glean
2. Check Notion for prior dossier
3. Dispatch one deal-analyzer sub-agent (with the user identity payload)
4. Write/update the Notion row for that deal
5. Display the assessment directly in Cowork

Skip the pipeline summary and notification steps.