beam-ai-team/operating-diagnostic

Operating Diagnostic

The Operating Diagnostic is the first artifact in a three-document Palantir-shape engagement sequence (Project 86 thesis). It maps the customer's back-office operation, ranks pain by ROI and complexity, shows where Beam agents will sit architecturally, and asks the team to validate the operation view before any pricing conversation.

Canonical example: Saudi Paper Group v1.0, shipped 2026-05-21 → see examples/saudi-paper-group-v1.0/.

Purpose

This document earns the right to send the priced commercial proposal. It positions Beam as a transformation partner, not a vendor with a price sheet. The CFO reads it and recognises their own operation written back to them, plus a defensible cost-of-current-operation hero number derived from their own disclosure.

Three documents, three gates:

| Gate | Artifact | Earns | |---|---|---| | 1 | Operating Diagnostic (this) | "You understand our operation." Operational validation only, no pricing. | | 2 | Capability Statement | "You can actually deliver this." Methodology, proof points, FDE model. (Often embedded as Section 5 of the diagnostic.) | | 3 | Commercial Proposal | "Here's the deal." Sizing, structure, fees, gates. Sent separately after Gate 1 + 2 land. |

Workflow

Step 1: Initialize TodoList

- [ ] Customer research (public filings: revenue, employees, entities, DSO/AR, recent disclosures)
- [ ] Source customer's logo as transparent PNG (square or near-square, no white box)
- [ ] Discovery call notes synthesis (every call recording transcribed; volumes, FTE, pain confirmed)
- [ ] Build process-inventory.yaml (25-35 processes across 4 clusters)
- [ ] Select 5-8 Y1 anchor processes (across 2-3 production agents)
- [ ] Identify cluster-level value pools (one hero number, customer-derived)
- [ ] Draft architecture diagram (around-your-ERP framing)
- [ ] Draft How-We-Deliver methodology (12-week timeline + 2x2 capability grid)
- [ ] Render diagnostic PDF (light theme, 16 pages target)
- [ ] Run check_overflow.py to detect silently-clipped pages (MUST exit code 0)
- [ ] Run pre-send checklist (jargon, names, em-dashes, sensitive content, visual integrity)
- [ ] Draft email (CFO primary, partner CC)
- [ ] Brief partner 60s before send

Inputs you must supply per customer

| Input | Source | Where it lives | |---|---|---| | Customer's logo (PNG, transparent) | Their website / press kit / partner | Drop at 03-projects/NN-customer/03-working/handbook/assets/customer-logo.png | | Customer's revenue, employees, entities | Public filings or partner brief | Used in cover meta + exec summary + architecture entity banner | | AR balance + DSO (or equivalent hero $ math) | Public filings or CFO call | Used in Section 4 cost strip — the ONE hero number | | Discovery call recordings/transcripts | Your own meetings | Used to write Section 3 cards in customer's own language | | Anchor process selection (5-8 of the 25-35) | Judgment from calls + sector pattern | Set pilot_anchor: true in the YAML | | Customer's ERP stack + migration status | IT director call or research | Drives Section 4 architecture + Section 5 sequencing | | Primary wedge per CFO | First commercial call (e.g., "AP-first, not AR-first") | Used in anchor selection rationale + email body | | Partner / intro contact info | Your CRM | CC on email + 60-second brief before send |

The Beam logo + Satoshi fonts are bundled in the skill (assets/). You only supply the customer-specific inputs above.

Step 2: Gather customer context

Required public data (always derivable):

• Annual revenue, employee count, entities, geographic footprint
• For listed companies: DSO, AR balance, recent quarterly performance
• Industry, ERP stack (SAP/Oracle/etc), any in-flight transformation (migration, IPO, etc)

Required call data (from your discovery sessions):

• Per-call attendees by role (CFO, IT Director, AP lead, etc), never by name in the doc
• Volumes the team disclosed: invoices/day, customers, orders, headcount per function
• Pain points the team named, in their own language
• The CFO's wedge ask (e.g., "Phase 1 in AP, not AR")
• Any timing constraints (Eid, fiscal close, ERP cutover, IPO window)

Required strategic context:

• Any forward EBITDA / growth trajectory the CFO volunteered (soften in writing, do not put hard numbers)
• ERP migration status (drives rollout sequencing)
• Owner-family / first-tenure CEO context (frame as "natural moment for transformation")

Step 3: Build process-inventory.yaml

See templates/process-inventory.yaml for the canonical schema. 25-35 processes across 4 clusters:

• P2P (Procure-to-Pay): 8-12 processes
• O2C (Order-to-Cash): 6-10 processes
• FP&A + Reporting: 3-5 processes
• Master Data + Adjacent: 4-7 processes

Per-process fields: id, cluster, short_name, description, volume, volume_confidence, current_fte, current_state, target_state, roi (LOW/MED/HIGH), complexity (LOW/MED/HIGH), target_year (1/2/3), pilot_anchor (bool).

Confidence flags drive everything downstream:

• GREEN/HIGH = directly observed in discovery or public-disclosure
• YELLOW/MEDIUM = estimated from sector pattern + partial signals
• RED/VALIDATE = assumed; needs team validation

Step 4: Select Y1 anchors

Rule: 5-8 anchor processes across 2-3 production agents.

Anchor selection criteria, in order:

1. Volume validated in discovery (skip RED-confidence volumes for Y1)
2. HIGH ROI rating (concentrates value)
3. LOW/MEDIUM complexity (manageable Y1 risk surface)
4. Bundleable into agents (3 process IDs per agent is the sweet spot)
5. Customer's stated priority (CFO's wedge ask leads)

Typical agent shapes:

• P2P Agent = Invoice Extraction + Three-Way Match + FX/Posting (~3 anchors)
• AR Agent = Daily Reporting + Collections + Bank Reconciliation (~3 anchors)
• Credit & Dispatch Agent = Credit Check + Warehouse Dispatch (~2 anchors)

Step 5: Identify the ONE hero cost number

This is the single most important number in the diagnostic. It should:

• Be derived from the customer's own disclosure (Tadawul, SEC, or CFO-volunteered)
• Be structural, not labour-cost-additive (working capital trapped, financing carry, missed early-pay discounts)
• Be large enough to justify the engagement (typically multi-million in their currency)
• Be defensible at the 24-month CFO checkpoint

Default hero pattern: working capital trapped in DSO above sector benchmark.

Formula: (AR balance / current DSO) × (current DSO − sector benchmark DSO) × cost-of-funds

Example (Saudi Paper): SAR 290M AR / 127 DSO × (127 − 90) × 7% = ~SAR 80M trapped + ~SAR 5M/yr carry.

The hero number lives on the architecture page (Section 4) in a red-accented strip. NEVER label it "CFO-disclosed" or attribute the framing — the customer recognises the math without being told it's theirs.

Step 6: Build the architecture diagram

Three-column visual on Section 4 ("Around your ERP, and what it costs today"):

1. Left column: Unstructured inputs (PDF invoices, customer orders, bank statements)
2. Middle column: Beam Agents Y1 (3 agent boxes, each with process IDs + volume)
3. Right column: Their system of record (SAP S/4HANA / Oracle / whatever, labeled "OWNED BY [CUSTOMER]")

Plus:

• Entity banner across the top
• Cost strip at bottom with hero number (e.g., "SAR 80M of cash trapped in DSO 127 above 90-day sector benchmark")
• Year-2-plus teaser below the strip
• Tagline: "Beam runs around your ERP, not inside it. These numbers are your current operation, not our promise."

Step 7: Build How We Deliver (Section 5)

12-week timeline + 2x2 capability grid:

Timeline (horizontal, 4 phases with arrows between):

1. Week 1-2: Kickoff (data access, sandbox setup)
2. Week 3-5: Agent build (configuration, SAP integration)
3. Week 6-8: Sandbox validation (Quality Gate at Week 8)
4. Week 9-12: Production go-live (staged cutover, real posts to system of record)

2x2 capability grid: | Top-left: Working cadence | Top-right: How we connect to your systems | | Bottom-left: Quality gates before go-live | Bottom-right: Forward Deployed Engineering |

The Integration block is critical for IT director credibility:

• Standard ERP integration (RFC/OData APIs, never direct DB access)
• Read-only by default, write enabled per workflow
• Locally-hosted LLM option for sensitive data
• Full audit log on every action

Step 8: Render

Dependencies (one-time per machine):

pip install pyyaml playwright
playwright install chromium

Bootstrap the customer's working directory (copies the renderer scripts + YAML template; brand assets stay in the skill's assets/ folder and are auto-resolved):

CUSTOMER=NN-new-customer
mkdir -p 03-projects/$CUSTOMER/{03-working/handbook,04-outputs/handbook}
cp 00-system/skills/sales/operating-diagnostic/scripts/render_diagnostic.py 03-projects/$CUSTOMER/03-working/handbook/
cp 00-system/skills/sales/operating-diagnostic/scripts/render_blueprint.py 03-projects/$CUSTOMER/03-working/handbook/
cp 00-system/skills/sales/operating-diagnostic/templates/process-inventory.yaml 03-projects/$CUSTOMER/03-working/handbook/

Customize for the new customer — follow templates/CUSTOMIZATION-CHEATSHEET.md for the full find-and-replace list (customer name, entity banner, hero $ number, agent boxes, etc).

Drop the customer logo at 03-projects/NN-customer/03-working/handbook/assets/customer-logo.png (transparent PNG).

Render the diagnostic (light theme, what you send the team):

cd 03-projects/$CUSTOMER/03-working/handbook/
python3 render_diagnostic.py --pdf

Render the priced blueprint (dark theme, sequenced followup for CEO/CFO):

python3 render_blueprint.py --pdf

Output: [Customer]-Operating-Diagnostic-v1.0.pdf, 16 pages, light theme.

Full rendering walkthrough with troubleshooting at HOW-TO-RENDER.md.

Step 9: Pre-send review

Run the checklist in templates/pre-send-checklist.md — five passes minimum, more if high stakes.

Step 10: Brief partner, then send

Before hitting send: 60-second WhatsApp/call to whoever made the customer intro (Ousama, Cisco, Mindware, etc) so they know diagnostic is going first and priced proposal sequences after. Protects their relationship and gives them veto power.

Voice rules (NEVER violate)

These are learned from multiple iterations of the Saudi Paper diagnostic. Each rule has a reason.

| Rule | Why | |---|---| | No em dashes | Mo's preference. Use commas, colons, periods. | | No customer team names in the diagnostic itself | Spellings often wrong (Arabic transliteration variance); strip to titles ("CFO", "IT Director", "AP team") | | No FTE counts as the impact framing | "~5 AP × loaded cost = $150K" looks small vs. a multi-million project. Use department-level pain framing instead. | | No "wedge" | Internal Beam jargon. Customer reads it as marketing-speak. Use "scope" or "anchor" or "entry point". | | No "exit gates" / "no lock-in" | Sounds defensive. Use "quality gates" — same content, different posture. | | No "honored / humbled / privileged" | Mo is peer-to-peer, not deferential. | | No industry name-drops | "Beam has shipped at Tier-1 banking, pharma, industrial customers" → sounds salesy. Use "enterprise customers globally" or just drop. | | No Beam team-size exposure | "Solution engineer + AI engineer on site" exposes thin staffing. Use "dedicated Beam team embedded with yours". | | No competitor naming except where customer mentioned them first | Saudi Paper: Klippa/Kyriba OK because they came up in their stack discussion. Otherwise: no. | | No "we believe / we've done this before" | Weak claims. State the methodology, let it stand on its own. | | No "explicit pivot from the deck's framing" | Internal-meta language. Customer doesn't care about our deck history. | | No FY2030 EBITDA numbers in writing | Even if the CFO volunteered it verbally. Soften to "trajectory materially above trailing FY[year] net income". | | No Eid / timeline pressure language | "Return by Thursday" / "no rush around Eid" both create awkward posture. Use "whenever your team has had a chance to review". | | No "single throat to choke" | Old enterprise jargon. Use "single point of accountability from kickoff". |

Content rules

1. Diagnostic does NOT propose pricing. Pricing follows under separate cover. Email body and Section 9 both signal this sequencing.
2. One hero $ number max. That number must be customer-derived (working capital, financing carry).
3. All other costs framed by department impact, not FTE. "AR function carries the DSO overhang" not "2 AR staff × $30K".
4. "Around your ERP, not inside it" is the architectural framing. Use it twice: in Section 4 title and tagline.
5. Attribute decisions to customer's own statements. "Per the CFO's request on May 17" beats "we have decided".
6. Quality gates not exit gates. Same content, different posture. Less defensive.
7. Peer-to-peer voice in the confirmation page. "Mark it up. Push back. Return it." beats "please review and provide feedback".
8. The architecture must acknowledge their ERP migration. If they're mid-Oracle→S/4HANA or similar, the architecture page calls it out.
9. Year 2+ is mentioned but not detailed. Teases multi-year transformation without committing the priced shape.

Structure (16 pages)

| Page | Section | Content | |---|---|---| | 1 | Cover | Abstract diamond motif, customer logo cluster, audience as titles only, v1.0 working draft tag | | 2 | Executive Summary | "What we heard. What we mapped." 4 KPIs (process count, cluster count, anchor count, time to first agent live) + What's-in-this-doc index | | 3 | What we heard | Cards attributed by role/call (CFO, AP/AR teams, operational context) — NO names | | 4 | How we view your operation | 4-cluster grid with anchor highlights + "real transformation starts from complete view not list of pains" framing | | 5 | Around your ERP, and what it costs today | Three-column architecture diagram + ONE hero $ strip (working capital) | | 6 | How we deliver | 12-week timeline + 2x2 grid (cadence, integration, quality gates, FDE) | | 7-11 | Process inventory | 25-35 processes ranked with confidence flags, by cluster | | 12 | Priority matrix | ROI vs complexity scatter, anchor zone highlighted, anchor callouts below | | 13-15 | Deep dives | 5-8 anchor process cards (Today vs With agents + 3 metric tiles each) | | 16 | What we'd like you to confirm | 4 question blocks + How to mark this up + Next step (no timeline pressure) |

Calibration heuristics

| Metric | Conservative anchor | Aggressive limit | |---|---|---| | Y1 anchor processes | 5 | 8 | | Y1 production agents | 2 | 3 | | Time to first agent live in production | 8 weeks | 6 weeks (AP-only scope) | | Y5 annual contribution | 4-5% of forward EBITDA | 8-10% of forward EBITDA | | 5-yr cumulative gross | 12-15× Y1 fees | 18-20× Y1 fees | | Gross ROI claim | 2.0× | 3.0× | | Net ROI claim | 1.2× | 2.0× | | Payback period | 18 months | 9 months |

Stay conservative. The diagnostic is operational, not commercial. The priced blueprint is where the ROI math earns its keep.

Email template

See templates/email-template.md. Key structure:

Subject: [Customer] × Beam AI · Operating Diagnostic

Dear Mr. [Surname],

Following our [Date 1] call and the [Date 2] scoping session, attached is the
Operating Diagnostic for [Customer]. It is a written-back view of the operation:
[N] processes mapped across four clusters, with [N] anchors flagged for Year 1,
[primary wedge] per your request.

This is a v1.0 working draft, deliberately scoped to the operation, not the
commercial case. Please mark it up where we have it wrong, missing, or
mis-sequenced, in whichever format is fastest. If the view aligns with how you
and the team see things, let us know and we will move forward with the Phase 1
commercial proposal.

Available to walk through any part of this whenever suits.

Best,
[Sender]
Beam AI

CC the partner/intro contact. ~90 words max. No em dashes.

Strategic context (Project 86)

This skill is a direct output of Project 86's transformation thesis:

• Beam is shifting from agent vendor to transformation-led product company with multi-year engagements
• Each transformation deal sells in 3-document sequence (Diagnostic → Capability → Commercial)
• IP retention clauses, multi-year MSA, outcome gates at every milestone
• Forward Deployed Engineering as named function

The Operating Diagnostic earns the right to send the priced blueprint. Skipping it = leading with price = vendor positioning. Doing it well = transformation partner positioning.

Enterprise ontology framing (optional upgrade)

Project 86's evolving thesis (per 03-working/1_enterprise-ontology-and-self-evolving-organisations.md and follow-ups) positions Beam as building a self-evolving operating graph for enterprises. Use this richer framing when:

• The customer is further along the transformation conversation (e.g., has internal AI strategy already)
• The CFO has demonstrated systems-thinking (talks about data flows, not just process automation)
• The IT director engagement is deep (S/4HANA migration mid-flight, MDM concerns, etc)
• The deal sequencing is multi-year from the start (not entry-wedge)

When using ontology framing, layer these phrases:

| Default framing | Ontology upgrade | |---|---| | "Operating Diagnostic" | "First artifact in your operating graph" | | "Around your ERP, not inside it" | "Beam discovers how work flows across your ERP, spreadsheets, email, exceptions, and local team habits — then maps that into a typed operating graph" | | "29 processes mapped" | "29 nodes in the seed graph, each with typed inputs, outputs, ownership, and confidence" | | "Mark it up. Push back. Return it." | "Mark it up. This becomes the foundation of your automation roadmap, not a one-time deliverable." | | Linear sequencing (Diagnostic → Capability → Commercial) | Graph evolution sequencing (Discovery graph → ROI graph → Implementation graph → Operating graph → QBR graph) |

Default rule: use the simpler framing (what shipped with Saudi Paper). Upgrade to ontology framing only when the buyer is ready. Mixing both confuses.

Confidence tiers as a delivery gate

Per 03-working/3_enterprise-ontology-product-engineering-priorities.md, confidence flags (GREEN/YELLOW/RED in the inventory) should be referenced as a first-class quality gate, not just a hidden YAML field. The Week 8 sandbox accuracy gate isn't only about accuracy percentage — it's about resolving confidence:

• Process started YELLOW → can it progress to GREEN with sandbox data?
• Process started RED → must be resolved before agent goes live

Section 5 of the diagnostic mentions this implicitly through the Quality Gate marker. For deals where the IT director / Head of Data is the primary skeptic, surface this explicitly: "We use confidence tiers as the gate, not polish or committee."

See:

• 03-projects/86-strategic-shift-2026/PROJECT.md — overall strategic shift thesis
• 03-projects/86-strategic-shift-2026/03-working/1_enterprise-ontology-and-self-evolving-organisations.md — the ontology thesis
• 03-projects/86-strategic-shift-2026/03-working/2_enterprise-ontology-go-to-market.md — GTM motion (where this diagnostic fits)
• 03-projects/86-strategic-shift-2026/03-working/3_enterprise-ontology-product-engineering-priorities.md — product/engineering priorities (informs Section 5)

Related skills

• sales/business-case-creation — the priced blueprint that follows this diagnostic
• sales/ceo-pitch-creation — when going direct-to-CEO without a CFO gate
• sales/proposal-creation — generic proposal patterns
• 48-repeatable-packages — the underlying agent catalog this builds on
• 71-gtm-deck-builder — the upstream deck that gets the first meeting

Files in this skill

• SKILL.md (this file) — workflow, voice rules, content rules, structure
• HOW-TO-RENDER.md — end-to-end render walkthrough, dependencies, troubleshooting
• scripts/render_diagnostic.py — light-theme renderer (canonical from Saudi Paper)
• scripts/render_blueprint.py — dark-theme priced blueprint renderer (sequenced followup)
• scripts/check_overflow.py — Playwright-based silent-clip detector (MUST run before sending)
• templates/process-inventory.yaml — schema template, 29-process canonical
• templates/email-template.md — email body + subject + send mechanics
• templates/pre-send-checklist.md — 5-pass review checklist with grep commands
• templates/CUSTOMIZATION-CHEATSHEET.md — find-and-replace targets per new customer
• assets/logos/beam-logo-white.png — Beam logo for dark theme
• assets/logos/beam-logo.png — Beam logo for light theme (CSS inverts)
• assets/fonts/Satoshi-*.otf — full Satoshi family (auto-loaded by renderer)
• examples/saudi-paper-group-v1.0/ — canonical reference example + lessons-learned README

Loading

When the user says any of:

• "build an operating diagnostic for [customer]"
• "we need a Palantir-shape diagnostic"
• "process diagnostic", "back-office map"
• "first-document gate before pricing"

Load this skill, walk through the workflow with the customer's data, render the PDF, and run the pre-send checklist before delivery.