Update to Revelata deepKPI

{
  "description": "Operational peer / comp discovery for US public companies via deepKPI semantic search — not valuation multiples. Build KPI fingerprint from SEC data; company_summary_search (same-vertical first); align KPIs; diff gaps → segment sub-benchmarks. Outputs: tight chat 1-pager, optional Revelata HTML, optional Excel (.xlsx). Use when comparing to peers, finding comps or most-similar companies, benchmarking, comp sets, valuation peers, thematic \"what's like X?\", or segment pure-plays. Exclude unrelated verticals (e.g., gym vs car wash) except clear segment-to-segment, same customer + same need.\n",
  "included_files": [
    {
      "relative_path": "references/html-template.md",
      "size_in_bytes": 39108
    }
  ],
  "name": "benchmark",
  "skill_md_contents": "---\nname: benchmark\ndescription: >\n  Operational peer / comp discovery for US public companies via deepKPI semantic search — not\n  valuation multiples. Build KPI fingerprint from SEC data; company_summary_search (same-vertical\n  first); align KPIs; diff gaps → segment sub-benchmarks. Outputs: tight chat 1-pager, optional\n  Revelata HTML, optional Excel (.xlsx). Use when comparing to peers, finding comps or most-similar\n  companies, benchmarking, comp sets, valuation peers, thematic \"what's like X?\", or segment\n  pure-plays. Exclude unrelated verticals (e.g., gym vs car wash) except clear segment-to-segment,\n  same customer + same need.\n---\n\n# benchmark\n\nFind comparable public companies (\"benchmarks\") for a target company or segment using deepKPI.\nThe output is not a mechanical list of industry peers — it's a curated set where every benchmark\nadds a specific analytical lens, and where the gaps in coverage are as informative as the matches.\n\n**Do not pair companies that do wildly different work** — different end customers, different\nunderlying need, different operating model — just because semantic search surfaced them together\n(e.g. a gym chain and a car-wash operator). That is not a useful whole-company benchmark. The\nonly exception is when a **specific segment** of each business plausibly targets the **same\ncustomers** with products that serve the **same job-to-be-done**; in that case, treat the match as\n**segment-to-segment** (Step 3 sub-benchmarks, clearly labeled), not as \"these two conglomerates\nare comps.\"\n\n**Vertical first, then wider.** Build the core benchmark set from companies in the **same\nvertical** as the target's primary business (same industry, same customer job, same operating\nshape) before you add names from **outside** that vertical. Broader or cross-vertical searches are\nfor filling gaps after same-vertical peers are in place, for a user-requested \"outside the sector\"\nlens, or for Step 3 segment sub-benchmarks — not as the default first pass.\n\nThe workflow is explicitly iterative. Segment sub-benchmarks are not pre-assumed based on what\nsegments exist; they are discovered by diffing the target's KPI fingerprint against what the\nwhole-company benchmarks can actually explain. If something in the target's operations has no\ncounterpart in the whole-company set, that's the signal to go deeper.\n\n## Data source\n\nSee `../_common/data-source-rules.md` for the runtime routing table and the canonical\ninventory of deepKPI operations.\n\n## Hard stop if deepKPI access fails\n\nSee `../_common/connection-failure.md`. STOP and ask before falling back.\n\n## Dependencies\n\nBefore starting, consult:\n- The `kpi` skill — retrieval workflow, provenance rules, scaling artifact\n  handling, KPI search strategy. Required for all data pulls.\n- `../_common/revelata-excel-styling-rules.md` — only if user requests Excel output.\n- The `implied-metric` skill — when filling Q4 or segment gaps in candidate\n  alignment.\n\nEvery number displayed must have a `[value](provenance-url)` link. No exceptions.\n\n## Output mode — ask first\n\n**Before pulling any data**, ask the user which output format they want:\n\n> \"Would you like an **interactive HTML report** (opens in browser, clickable provenance links, Chart.js **time-series** charts) or **in-chat markdown** output? Or both?\"\n\n- If **HTML**: generate the full HTML report (dark Revelata branding, Chart.js line charts for KPI **trends over time**, fingerprint grid). Also produce the chat 1-pager as a compact summary.\n- If **in-chat**: produce only the chat 1-pager with full markdown provenance links (see rules below). Offer the HTML at the end.\n- If **both**: produce chat 1-pager first, then generate the HTML.\n\nOffer Excel at the end regardless of which mode is chosen, unless the user already requested it.\n\n## Outputs\n\n| Format | When | Description |\n|--------|------|-------------|\n| Chat 1-pager | Always | Fingerprint pill rows + master table + KPI alignment + ≤5 notes — **all values hyperlinked** |\n| HTML report | If user chose HTML or both | Dark Revelata-branded report with fingerprint grid, benchmark cards, and Chart.js **KPI trends over time** (line charts: target vs benchmarks on a shared period axis) |\n| Excel workbook | User requests .xlsx | KPI alignment table, periods as columns per `../_common/revelata-excel-styling-rules.md` |\n\n### In-chat provenance link rules (non-negotiable)\n\nEvery numeric value shown in chat **must** be a markdown hyperlink to its source filing passage. No bare numbers.\n\nFormat: `[+4.9%](https://www.revelata.com/docviewer?pvid=11240)` — the pvid comes from the deepKPI response.\n\nThis applies everywhere in the chat output: fingerprint bullets, the KPI alignment table, notes, and the diff insight. If a value has no pvid (e.g. an estimate or derived metric), label it explicitly as `~$X est.` or `implied` with no link. Never omit the link for a directly sourced value.\n\nExample of correct in-chat KPI alignment table row:\n```\n| TXRH | [+4.9%](https://www.revelata.com/docviewer?pvid=11240) | [$8.7M](https://www.revelata.com/docviewer?pvid=10061) | [714](https://www.revelata.com/docviewer?pvid=11537) |\n```\n\n---\n\n## Workflow\n\nThe four steps below run in sequence. Steps 1–3 are analytical; Step 4 is output generation.\nRun all deepKPI calls in parallel wherever possible to save time.\n\n---\n\n### Step 1: Build the target's KPI-enriched fingerprint\n\nThis is the foundation everything else builds on. Pull it from deepKPI — do not use general\nknowledge for specific metrics.\n\n**Calls:** `query_company_id` → `get_company_summary` → `get_company_segments` → `list_kpis`\n→ `search_kpis` (for each segment's signature metrics)\n\n**What to extract:**\n\n**A. Narrative** — 2-3 sentences: business model, revenue drivers, customer type, go-to-market,\ngeography. Ground it in numbers where possible (unit count, revenue scale, market share if stated).\n\n**B. Segment map** — For each reportable segment:\n- Name and revenue share %\n- One-sentence description of the economic model (how it makes money, who pays)\n- 3-5 signature KPIs with actual values from deepKPI, each with provenance link\n\nThe segment KPIs are what make this fingerprint useful for diffing. For an airline: ASMs, load\nfactor, CASM, TRASM. For a refinery: capacity bpd, utilization %, gross margin per barrel.\nFor a restaurant segment: unit count, comp sales %, AUV. Pull the real numbers.\n\n**C. KPI signature** — The 3-5 metrics that matter most for the consolidated company. These\nbecome the columns in the KPI alignment table in the output.\n\n**Output of Step 1:** An internal working document (not shown to user) with:\n```\nTarget: [TICKER] — [Company] (CIK: NNNNNN, FY: DATE)\nPrimary vertical (for comp search ordering): [e.g. full-service restaurant, regional bank, SaaS HCM]\nNarrative: ...\nSegments:\n  [Segment A] (XX% rev): [description] | KPIs: metric1=[val](url), metric2=[val](url), ...\n  [Segment B] (XX% rev): [description] | KPIs: metric1=[val](url), ...\nKPI signature: metric1, metric2, metric3 [, metric4, metric5]\n```\n\n---\n\n### Step 2: Find candidates and align their fingerprints\n\n**A. Search**\n\nRun `company_summary_search` with 3-5 queries. Each query should describe a *business model*,\nnot just a sector name. The goal is semantic richness — describe what the company does, for whom,\nhow it earns money, and what drives its unit economics.\n\n**Order matters — same vertical first.** At least **the first two queries** must stay tightly\ninside the target's **primary vertical** (from Step 1: summary, segments, and the \"Primary\nvertical\" line). Pull and KPI-align those results before you run looser or cross-vertical queries.\nUse additional queries to go **outside** the vertical only **after** you have a credible\nsame-vertical candidate set, or when the user explicitly wants analogies from other sectors, or\nwhen Step 3 needs a segment-specific search.\n\nExamples of the contrast:\n- Weak: `\"airline\"` → Strong: `\"hub-and-spoke network carrier international domestic routes premium cabin loyalty co-brand revenue per ASM\"`\n- Weak: `\"restaurant chain\"` → Strong: `\"multi-brand casual full-service dining operator franchised same-store sales average unit volume\"`\n- Weak: `\"software company\"` → Strong: `\"B2B SaaS subscription recurring revenue net revenue retention enterprise mid-market\"`\n\nUse `top_k_companies: 10-12` per query. Deduplicate across queries. Target 6-12 candidates.\n\n**B. KPI alignment**\n\nFor each candidate: call `list_kpis` (free), then `search_kpis` for the target's KPI signature\nmetrics (from Step 1C). This produces aligned rows — the target's metrics sitting next to each\ncandidate's equivalent metrics.\n\n**Recency rule (do this from the start):** when the user's question is about \"current\" / \"latest\"\ncomparability, prefer the **most recent quarterly periods** available (10-Q-derived) for each KPI\nover stopping at the last 10-K annual figure. Use annual series for long-cycle context, but do not\nship a benchmark set that effectively says \"data is old\" if newer 10-Q periods exist for the KPI.\n\nThe alignment reveals two things:\n1. How close each candidate is on the dimensions that matter (similar range = structurally comparable)\n2. Where candidates have no data or wildly different values (poor fit on that dimension)\n\nCoverage coding:\n- **Green**: metric present and plausible\n- **Yellow**: metric present but value seems off (scaling artifact, possible cross-contamination)\n- **Red**: no data\n\n**C. Tier the candidates**\n\nBased on the aligned KPI fingerprints (not just the description similarity), and only after\npassing the **structural fit gate** below:\n\n- **Tier 1**: Closest structural match — same business model and same customer/need, similar values on 3+ signature KPIs\n- **Tier 2**: Useful comparators — same overall job-to-be-done; good match on some KPIs, different on others; adds a specific lens\n- **Tier 3**: Same **kind** of business as the target, different scale, mix, or geography — still\n  a coherent comp (e.g. regional vs national airline). **Not** unrelated verticals \"for color.\"\n\n**D. Structural fit gate (drop before the output table)**\n\nBefore anything appears in the chat 1-pager or HTML as a whole-company benchmark, ask: *Would\nan investor reasonably describe this company as doing the **same job** for the **same type of\nbuyer** as the target?* If **no**, exclude it from Tier 1–3 for whole-company analysis — even if\na few metrics line up by coincidence. If there is a **real but narrow** overlap (same\nwallet, same purchase occasion, same enterprise buyer for a specific product line), keep the\ncandidate **only** as a **segment** sub-benchmark in Step 3 with an explicit \"Maps to: Segment …\"\nstory, not as a peer for the consolidated company.\n\n---\n\n### Step 3: Diff — find what the whole-company benchmarks don't explain\n\nThis is the step that surfaces the most analytically valuable insights.\n\n**The question:** After aligning KPI fingerprints in Step 2, which parts of the target's\noperations have *no good coverage* in the whole-company benchmark set?\n\nA \"coverage gap\" exists when:\n1. The target has a reportable segment whose signature KPIs appear nowhere in the Tier 1/2 benchmark set, OR\n2. The target reports KPIs that are structurally foreign to all benchmark candidates\n   (e.g., `refinery throughput bpd` when all candidates are airlines), OR\n3. A major segment has a fundamentally different economic model than what any whole-company\n   benchmark represents\n\n**For each gap identified:**\n\na. Build a **segment-specific fingerprint** using the segment's own KPIs from Step 1B\n   (\"this segment, if it were a standalone public company, would look like:\")\n\nb. Run a fresh `company_summary_search` describing that segment as a standalone business.\n   Sub-benchmarks must still satisfy **same customer + same need** for that segment; do not\n   pull unrelated verticals \"for coverage.\"\n   Use the segment's KPIs as the anchor — e.g., for a refinery segment:\n   `\"independent petroleum refiner crude oil throughput barrels per day capacity utilization refining margin per barrel crack spread\"`.\n   Not: `\"refinery\"`.\n\nc. Pull KPI alignment for sub-benchmark candidates using the *segment's* KPI signature\n   (not the parent company's consolidated metrics)\n\nd. Tag all matches as `Maps to: Segment: [name]` in the master table\n\n**Important framing:** The sub-benchmark tells you what that segment *would* look like as a\nstandalone profit-maximizing business. When the segment operates under a different economic logic\ninside its parent (cost-center, captive supplier, hedge), say so explicitly — the gap between\nthe sub-benchmark's economics and the segment's implied economics *is the analytical insight*.\n\n**Example of the diff in action:**\n- Target: Delta (airline + refinery)\n- Step 2 finds: UAL, AAL, LUV, ALK — all cover the airline KPIs (load factor, CASM, ASMs)\n- Diff: `refinery throughput bpd`, `utilization %`, `gross margin/bbl` appear in Delta's segment\n  map but in *none* of the airline benchmarks\n- Step 3 triggers: build refinery segment fingerprint → search → find PBF, CVI, DINO as\n  sub-benchmarks → align on throughput/utilization/margin\n- Insight that emerges: Monroe's 200K bpd capacity is closest to CVI (207K bpd combined);\n  PBF shares East Coast PADD 1 geography; but Monroe runs as a hedge, not a profit center —\n  the merchant refiner margins ($8–16/bbl) represent the *opportunity cost* Delta pays to own it\n\nThe segment sub-benchmark logic is not limited to named segments. If the target has any\noperational dimension that reads as structurally foreign to the whole-company comps —\na financial arm, a logistics network, a retail footprint embedded in a manufacturer —\nask whether a standalone pure-play exists in the S&P 1500 that illuminates it.\n\n---\n\n### Step 4: Build outputs\n\n#### Chat 1-pager\n\nTight. No prose sidebars. Everything fits on one screen. In the **benchmark table** and **KPI\nalignment** table, put **same-vertical** names first (clearest structural peers in the primary\nvertical), then cross-vertical or segment-mapped comps, with `Maps to` spelling out any segment\nstory.\n\n```\n# Benchmarks for [Company] ([TICKER])\n\n[TARGET FINGERPRINT — 2-3 sentences. Every sourced metric hyperlinked:\ne.g. [+2.0% blended comps](https://www.revelata.com/docviewer?pvid=578),\n[$12.1B revenue](https://www.revelata.com/docviewer?pvid=11442)]\nSegments: [Segment A] XX% rev | [Segment B] XX% rev\n\n## Benchmark table\n\n| Ticker | Maps to | Similar on | Different on | Scale vs [TARGET] |\n|--------|---------|------------|--------------|-------------------|\n\n## KPI alignment — latest available period(s)\n\n| Company | [metric1] | [metric2] | [metric3] | [segment metric] | Period |\n|---------|-----------|-----------|-----------|-----------------|--------|\n| [TARGET] | [val](pvid-url) | [val](pvid-url) | [val](pvid-url) | [val](pvid-url) | FY... or FY..-Q.. |\n| BENCH1   | [val](pvid-url) | [val](pvid-url) | — | — | FY... or FY..-Q.. |\n\nColumn headers are plain text. Only the value cells carry hyperlinks.\nEstimates/derived values: `~$X est.` with no link.\n\n## Notes\n- [≤5 bullets — only material caveats: scaling flags, cross-contamination, structural differences,\n  coverage gaps, economic logic mismatches (cost-center vs. profit-maximizer)]\n\n## Sources\n[Ticker (CIK) — Green/Yellow/Red — FY end — any corrections]\n```\n\nIf a section would be empty, omit it. If the KPI alignment table would exceed 10 rows, drop Tier 3\nfrom it (keep Tier 3 in the benchmark table only).\n\n#### HTML report\n\nRead `references/html-template.md`. Key structure:\n\n- **Hero fingerprint grid** (`table.fp-grid`): KPIs × benchmark columns only — **no prose inside the grid**\n  (no \"Why it matters\", thesis blurbs, or `fp-context`-style rows). Put narrative in benchmark cards\n  and diff insight. **`.legend-strip`** (color key) sits **below** the grid, not in the page header.\n- **Benchmark cards** (one per company): order **same-vertical** peers before cross-vertical or\n  segment-mapped names. Tier-colored top border, similar/different columns,\n  key KPI values hyperlinked. Segment sub-benchmarks use purple border + \"Segment:\" badge.\n- **KPI trends over time (charts + alignment table)**: This section is where deepKPI's edge shows up—**filing-resolved time series** most vendors do not reconstruct at this depth. For the **2–3 most important** signature KPIs, pull **multi-period** values for the target **and every benchmark** (prefer quarterly where coverage is solid; otherwise annual—follow the `kpi` skill for period selection, scaling, and provenance). Render **Chart.js line charts** (not single-period grouped bars): **x-axis = time** (ordered FY/FQ labels), **one line per company** so the reader compares **trajectory, inflection, and pace** across competitors on the **same** metric. Put the full **KPI alignment** table (with hyperlinked values) **below** the charts as today. If a KPI truly has fewer than three comparable periods across the set, you may show a sparse line chart **or** a one-line caption pointing readers to the table—do not imply a cross-sectional bar is equivalent to the time-series view.\n- **Chronology QA for every time-series chart (mandatory)**: Ensure the plotted points are in **chronological order** for every company series and the x-axis labels are in **ascending time**. **Do not rely on input order.** Sort by a real time key (prefer **period end date**; otherwise parse FY/FQ labels into a comparable key) before passing points to Chart.js. A zig-zagging line is almost always an ordering bug.\n- **Y-axis QA for every time-series chart (mandatory)**: **Double-check** each chart's **Y scale** before shipping HTML. The visible **min/max domain must include every non-null plotted point** across **all** series (target + benchmarks). **Do not** set fixed `min`/`max`, `suggestedMin`/`suggestedMax`, or `beginAtZero` unless those bounds are **recomputed from the union** of all series values—wrong bounds **clip lines off-canvas** so they look missing. Prefer automatic scaling plus **padding** (e.g. Chart.js `scales.y.grace` as a %) so tight clusters stay visible. For **log** scales, omit non-positive points or avoid log if that would drop the series; confirm lines still render. **Mentally verify each tab**: any ticker with data must show a **visible** polyline or points—not a legend entry with no trace.\n- **Diff insight box** (cyan glow, same as synthesis in pressure test): 2 paragraphs on what\n  the benchmark set reveals that whole-company analysis would miss.\n- **Notes** and **Sources** footer.\n\n#### Excel workbook\n\nFollow `../_common/revelata-excel-styling-rules.md`.\nOne sheet for whole-company benchmarks, one sheet per segment sub-benchmark group.\nAnnual periods as columns; green cells for target values; clickable provenance links.\n\n---\n\n## Failure modes\n\n- **Assuming segment sub-benchmarks without doing the diff**: Don't pre-decide \"this company\n  has a real estate arm so I'll find REITs.\" Let the KPI gap analysis surface it. The diff step\n  earns its keep precisely because the gaps are often surprising.\n- **Narrative-only fingerprint**: If Step 1 doesn't pull actual KPI values, the diff in Step 3\n  has nothing to work with. The fingerprint must have numbers.\n- **Prose inside the HTML hero grid**: Do not add \"Why it matters\", thesis blurbs, or other\n  commentary rows inside `table.fp-grid` — the grid is KPI labels and numbers only. Use benchmark\n  cards and diff insight for narrative (`references/html-template.md`).\n- **Skipping KPI alignment for candidates**: Checking description similarity is not enough.\n  Pull the actual metrics — two companies can describe themselves similarly but operate very\n  differently when you look at unit economics.\n- **Treating all segments equally**: Not every segment warrants a sub-benchmark search.\n  Focus on segments where: (a) the parent discloses separate KPIs, and (b) the KPIs are foreign\n  to the whole-company benchmark set.\n- **Time series plotted out of order**: If any chart line zig-zags \"backward,\" the points are not time-sorted. Sort each series by **period end date** (or FY/FQ key) before charting, and make sure the shared x-axis label list is in ascending order too.\n- **Y-axis clips time series in HTML**: Hard-coded or guessed Y bounds, or `beginAtZero` used without checking the data band, often **hides entire lines** outside the drawable range. Always derive bounds from **all** series (or use defaults + `grace`) and re-check before delivery.\n- **Too much prose in chat**: The 1-pager is a reference artifact. Cut until it hurts.\n- **Skipping list_kpis**: Free call that prevents wasted credits on metrics that don't exist.\n- **Unrelated verticals as comps**: A gym and a car wash are not whole-company benchmarks for\n  each other unless you have a defensible segment-level story (same customers, same need). If you\n  cannot write that one sentence without hand-waving, drop the name.\n- **Cross-vertical before in-vertical**: Do not foreground or prioritize outside-the-vertical\n  names until same-vertical peers are identified and KPI-aligned. If the first search pass drifts\n  cross-vertical, reset with tighter in-vertical queries before presenting the table.\n"
}