beam-ai-team/use-case-proposal

Use-Case Proposal Skill

Canonical example: Saudi Aramco Digital Finance v3 (examples/aramco-digital-finance-v3/). That document is the quality bar: portrait A4, 8 pages, dense, engineering-grade, closes on one decision.

The shape of the document (8 pages, portrait A4)

1. Cover: co-brand lockup, title, one summary diagram (use cases -> our layer -> their core), "in this document" index, meta grid.
2. The Situation: acknowledge their maturity FIRST ("you have already solved the commodity work"), then the opportunity (the exception/judgment tail), the three-overlap test, and a numbered index of the candidates.
3. Operating Graph (the centerpiece): full-page layered ontology SVG. Unstructured inputs -> N agentic applications (color-coded: hero, PoC, candidates) -> our layer (capability chips) -> their digital core, with "read/write via APIs" and a "how to read this graph" rail + 3 stat tiles (N apps / 1 connection / 0 changes to core).
4. and 5. The use cases as bands: left rail (number, name, italic outcome tagline, domain, badge, proven pattern, fit-dots for volume/unstructured/judgment) + right 2x2 grid (Description, Business challenge, Expected business impact, Potential value) + a bold Order of magnitude strip.
5. Recommendation: land/prove/expand timeline with checklists, week-by-week PoC calendar (W1 Connect, W2 Baseline, W3 Measure, W4 Decide, each with an "Out:" line), stat tiles, success metrics, guardrail chips, "why X first" strip.
6. Method & governance: ruled 3-column Q&A matrix (their actual question | our answer | bold takeaway). Use the questions THEIR team actually asked in calls.
7. Proof + the close: client-logo proof wall with strong claims, we deliver / we need, "after the PoC" strip, then a green close band: big statement, 1-2-3 next steps, named contact.

Workflow

Safety Contract

Require explicit user approval before sending a generated proposal or cover email to a client. Treat account research, examples, logos, and generated PDFs as confidential; write outputs only to the user-approved project/output folder.

Step 1: Research gate (never skip)

Spawn research on the account's REAL operational maturity before selecting anything. Required outputs:

• Maturity map: what is already solved by their stack (ERP, procurement, tax, in-house AI). NEVER pitch commodity automation to a sophisticated shop; it destroys credibility instantly (for Aramco: ZATCA e-invoicing and three-way match were solved, so they were cut).
• Account-specific pains: what their scale and business nature make uniquely painful (for Aramco: contractor claims on mega-projects, IKTVA supplier evidence, JV/affiliate consolidation).
• Forcing function: a real efficiency/cost catalyst, referenced only subtly and respectfully. Do NOT cite sensitive internals (dividends, net debt) to their face.
• Do-not-claim list: internal figures we cannot source (volumes, FTE, exception rates). Present those as discovery questions.

Step 2: Select and rank the use cases (5 to 7)

• Every candidate must pass the three-overlap test: high volume x unstructured content x exceptions/judgment. One or two is a reporting problem, not an agentic one.
• Rank by ACCOUNT-specific fit, not general value.
• Pick two special roles: the strategic hero (most differentiated, highest ceiling; petrol-blue) and the recommended PoC (fastest to bound and prove, lowest integration risk, runs on infrastructure they already operate; green).
• Frame everything as the layer on top of their stack, never a replacement. Explicitly co-exist with their in-house AI.

Step 3: Write the content (per use case)

• Name: capability, not category ("Capital-project claim & change-order verification", not "AP automation").
• Outcome tagline (italic, one line): "Protect capital spend before payment."
• The four fields, 1 to 3 tight sentences each: Description / Business challenge / Expected business impact / Potential value to [account].
• Order of magnitude (the exec line): qualitative scale logic only, e.g. "On capital programs measured in the tens of billions a year, a fraction of one percent of claim leakage is a nine-figure number." Public scale facts only; never invented internals.
• Proven pattern: one line mapping to the closest real customer analog.
• Fit-dots: rate volume/unstructured/judgment 1 to 3, honestly varied (not all 3s).

Step 4: Render

# copy the skill scripts into the account project (do not edit the skill copies)
cp skills/general/use-case-proposal/scripts/build.py        03-projects/NN-account/04-outputs/final/
cp skills/general/use-case-proposal/templates/_template.html 03-projects/NN-account/04-outputs/final/
# customize per templates/CUSTOMIZATION-CHEATSHEET.md, then:
cd 03-projects/NN-account/04-outputs/final && python3 build.py

build.py embeds Satoshi fonts (from operating-diagnostic assets), the blue square Beam mark + client logo as base64, renders the PDF via Playwright, and runs the overflow check.

Step 5: QC (all three, every time)

1. Overflow check must pass on every page, INCLUDING interior elements (.band-l, .band-r, .card). Page-level checks miss interior clipping; the interior check exists because a fit-dots block once clipped silently.
2. Eyeball every page: screenshot each .page element and actually look at each image. Hunt for: empty bands, stretched/sparse content, faint grey text, tiny logos, misaligned lockups. No page ships with a large empty band.
3. Guardrail scans: zero em dashes; no banned terms (per account guardrails + global comms rules); accuracy claims as upside only (">95%", ">99%").

Step 6: Cover email

Short, peer-to-peer, no em dashes. Structure: thanks for the brief -> what is attached (mirror their requested fields) -> two pointers (selection logic + recommended start) -> the next-day scoped-PoC promise -> offer a walkthrough. Example: examples/aramco-digital-finance-v3/cover-email-ahmed.md.

Design system (locked, do not regress)

• Logos: ONE lockup per page, header only: blue square Beam mark (assets/beam-mark-blue.png) + client color logo, same optical level, hairline separator, NO multiplication sign, no Beam wordmark image, no logos in footers. Client logos for the proof wall live in skills/general/proposal-creation/assets/logos/ and skills/general/prospect-brief/assets/logos/ (use americana_alt.png, not americana.png).
• Palette: light paper (#F7F8F4), near-black ink, client accent used with discipline (Aramco green #00843D / #005A2B), petrol-blue #0f3d6e reserved for the hero.
• Type: Satoshi. Every page needs an EXEC layer readable in seconds (headline, taglines, magnitude strips, takeaway column, close statement) above the dense layer. No labels under 6.4px; grey text on the cover diagram must be #3f4438+, not faint.
• Density: no large empty bands anywhere. Cards hug content or content grows to earn the card. If a section cannot fill its space with real content, restructure the page (that is how the week-by-week calendar and the Q&A matrix were born).
• Proof wall: real client logos at legible size (max-height 20 to 24px), strong claims only. Never weak phrasing ("expense validation" -> "9,450 policy decisions a month against 46 rules").
• The close: big statement with the next-day promise in accent color, "after the PoC" strip, 1-2-3 what-happens-next, named contact with email. The document must end asking for exactly ONE decision.

Files

• scripts/build.py — renderer: content dicts (UCS list), lockup/foot builders, fonts+logos base64, Playwright PDF, overflow check incl. interiors.
• templates/_template.html — 8-page portrait template with __PLACEHOLDERS__.
• templates/CUSTOMIZATION-CHEATSHEET.md — find-and-replace list for a new account.
• examples/aramco-digital-finance-v3/ — canonical PDF + cover email.
• assets/beam-mark-blue.png — the blue square Beam mark (the only Beam mark used).