Update to Revelata deepKPI

{
  "description": "Computes a financial or operational metric that isn't directly reported, using the algebraic relationship between available quantities. Use whenever a needed data point is absent from deepKPI but can be computed — Q4 values, segment remainders, per-unit economics (ASP, ARPU, AUV, revenue per store), take rates, implied useful life, penetration rates, geographic mix percentages. Trigger for \"back into\", \"derive\", \"implied\", \"impute\", \"calculate from\", \"what's the Q4\", or any situation where the needed number isn't in the data but its ingredients are. Always pull inputs via the kpi skill; derived values inherit provenance from their deepKPI-sourced components. For `.xlsx`/CSV exports, follow ../_common/revelata-excel-styling-rules.md (plus the xlsx skill).\n",
  "included_files": [],
  "name": "implied-metric",
  "skill_md_contents": "---\nname: implied-metric\ndescription: >\n  Computes a financial or operational metric that isn't directly reported, using\n  the algebraic relationship between available quantities. Use whenever a needed\n  data point is absent from deepKPI but can be computed — Q4 values, segment\n  remainders, per-unit economics (ASP, ARPU, AUV, revenue per store), take rates,\n  implied useful life, penetration rates, geographic mix percentages. Trigger for\n  \"back into\", \"derive\", \"implied\", \"impute\", \"calculate from\", \"what's the Q4\",\n  or any situation where the needed number isn't in the data but its ingredients\n  are. Always pull inputs via the kpi skill; derived values inherit provenance\n  from their deepKPI-sourced components. For `.xlsx`/CSV exports, follow\n  ../_common/revelata-excel-styling-rules.md (plus the xlsx skill).\n---\n\n# implied-metric\n\nComputes metrics that aren't directly reported by identifying the algebraic\nrelationship between available quantities.\n\n**All inputs must come from deepKPI** (via the `kpi` skill). Use `list_kpis`\nfirst to discover exact KPI names, then `search_kpis` to pull the values. Never\nuse hardcoded or assumed figures as inputs to a derivation.\n\n## Data source\n\nSee `../_common/data-source-rules.md`. Inputs to derivations are pulled with\n`query_company_id` / `list_kpis` / `search_kpis` — same workflow as the `kpi` skill.\n\n## Hard stop if deepKPI access fails\n\nSee `../_common/connection-failure.md`. STOP and ask before falling back.\n\n## Critical: flow vs. stock\n\nBefore any derivation, determine whether the metric is a **flow** (accumulated\nover a period) or a **stock** (level at a point in time).\n\n**Flows** — income statement, cash flow, unit sales, deliveries, openings:\n`Q4 = FY − (Q1 + Q2 + Q3)`\n\n**Stocks** — balance sheet items, period-end subscriber/store/user counts:\n`Q4 = fiscal year-end value directly` — do not subtract.\n\nWhen in doubt: \"Is this a running total for the period, or a level at the end?\"\n\n## Derivation patterns\n\n### Q4 from annual + Q1–Q3 (flows only)\n```\nQ4 = FY − (Q1 + Q2 + Q3)\n```\n**Always attempt this derivation when quarterly granularity is needed.** If Q4\nis not directly in deepKPI, check whether FY is available and compute it — do\nnot present a partial quarterly series without first trying to fill Q4.\n\n**Where the imputed value goes:** Put Q4 **in the same row** as the quarterly\nseries, in the **Q4 period column** (in-chat wide tables) or the matching period\ncolumn in Excel—**not** a separate line labeled \"Q4 (derived)\" or \"Imputed Q4\".\nThe data stream should read as one continuous series; use **Notes** (or a footnote)\nto flag imputation. Same rule for other **gap-fills** in a single stream.\n\nApply to: revenue, COGS, gross profit, opex, net income, unit sales, deliveries,\nstore openings, SBC, D&A, capex, cash from operations.\n\nDo NOT apply to: balance sheet items, period-end subscriber/store/user counts.\n\n### Segment remainder\n```\nmissing_segment = total − sum(known_segments)\n```\nExamples: domestic = total − international; Maggiano's = consolidated − Chili's − Corporate.\n\n### Per-unit metrics\n\n| Derived metric | Formula |\n|---|---|\n| Average Selling Price (ASP) | Revenue ÷ Units sold |\n| ARPU | Revenue ÷ Paying users |\n| Average unit volume (AUV) | Revenue ÷ Restaurant count |\n| Revenue per store | Revenue ÷ Store count |\n| Cost per store | COGS ÷ Store count |\n| CAF income per vehicle financed | CAF income ÷ Vehicles financed |\n| CapEx per new/remodeled store | Capex ÷ Affected stores |\n| Revenue per square foot | Revenue ÷ Total sq ft |\n| Average net sales per case | Revenue ÷ Cases sold |\n\n### Implied useful life (depreciation)\n```\nimplied_useful_life    = net_PP&E / depreciation_expense\nnext_year_depreciation = current_net_PP&E / implied_useful_life\n```\nUse the average of the last three reported years as the forward assumption, held\nconstant (fewer than three available: the average of what exists).\n\n### Take rate\n```\ntake_rate = net_revenue / gross_bookings_or_GMV\n```\n\n### Geographic / segment mix\n```\nsegment_pct       = segment_value / total_value\nprojected_segment = projected_total × segment_pct\n```\n\n### Penetration rate\n```\npenetration_rate = units_captured / total_addressable_units\n```\n\n## Verify the derivation\n\n- Does the derived Q4 make the four quarters sum exactly to the annual?\n- Does the segment remainder produce a non-negative number? (Negative → period mismatch, unit mismatch, or wrong metric definition)\n- Does the per-unit figure fall in a plausible range for this business?\n- Does implied useful life match the depreciation policy in the 10-K notes?\n\n## Output format — show all work with clickable inputs\n\nTable structure rules (in-chat):\n- **Time flows left to right** — column headers are period labels\n  (`FY22-Q1` … `FY22-Q4`), earliest at left.\n- **One row per time series** — each **reported** deepKPI series is one row across\n  periods. Do not fragment into \"Revenue - Q1\" rows. **Imputed** points (e.g. Q4)\n  sit **in that same row** in the missing column—**not** an extra \"Q4 (derived)\" row.\n- **Operands for imputation** — FY and Q1–Q3 may appear on **additional** rows when\n  they are **separate** deepKPI pulls (e.g. annual revenue row + quarterly row); the\n  **imputed value still fills the gap inside the quarterly row**, not a third row\n  for \"Q4\".\n- **Truly distinct derived KPIs** (a metric that is *not* the same stream with a\n  hole—e.g. a computed ratio or remainder **as its own line item**) may use their\n  own row; show operands and formula as today.\n- **Links embed in cell values** — every directly reported input is a clickable\n  hyperlink: `[$41.8M](exact-deepkpi-url)`. No separate Source column.\n- **Notes is a bottom row** — populated in columns where something non-standard\n  occurred (derivation applied, stock item, unit conversion, MD&A gap-fill, etc.).\n\nShow all operands (with links) needed for imputation, and the filled-in cell in the\n**same stream** as the missing point. For a distinct derived KPI row, show operands\nand the result on that KPI's row. Never hide how a number was obtained.\n\n**Single derivation block:**\n```\n**[Metric] ([Ticker], [Period])** — *derived*\nFormula: FY − (Q1 + Q2 + Q3)\n= [FY: $X](<exact-deepkpi-url>) − ([Q1: $A](<url>) + [Q2: $B](<url>) + [Q3: $C](<url>))\n= **$D**\nCaveat: Q4 not directly reported in SEC filings; derived from 10-K annual figure.\n```\n\n**Multi-period table (preferred when deriving multiple periods):**\n\n```\n## [Metric] ([Ticker]) — Q4 imputed in-stream\nUnits: $M\n\n                   | FY22-Q1       | FY22-Q2       | FY22-Q3       | FY22-Q4        | FY23-Q1       | FY23-Q2       | FY23-Q3       | FY23-Q4        |\n-------------------|---------------|---------------|---------------|----------------|---------------|---------------|---------------|----------------|\nQuarterly Revenue  | [$41.8](url)  | [$55.3](url)  | [$65.1](url)  | **$47.9** (FY−Q1−Q2−Q3; link FY + Q1–Q3 operands) | [$43.9](url)  | [$59.8](url)  | [$69.7](url)  | **$53.2** (same) |\nAnnual Revenue     |               |               |               |[$210.1](url)   |               |               |               |[$226.6](url)   |\nNotes              |               |               |               | imputed Q4     |               |               |               | imputed Q4     |\n```\n\nUse the Notes row to flag anything non-standard: stock item used directly as Q4,\nunit conversion applied, anomaly year excluded, one input estimated from MD&A\nrather than deepKPI, etc.\n\n## Excel workbook (`.xlsx`)\n\nFollow `../_common/revelata-excel-styling-rules.md` for layout, styling, provenance\n**hyperlinks on the value cells** (not separate Source rows), date headers, freeze\npanes, column grouping, and checklist. Use the **xlsx** skill to build the file.\n\n**implied-metric addenda:**\n\n- **Q4 / gap imputation:** formula **`=FY_cell - Q1_cell - Q2_cell - Q3_cell`** in\n  the **quarterly series row**, **Q4 column**—not a separate \"Q4 Revenue\" row.\n- Structure ALL CAPS sections as needed. **Distinct** derived KPIs (not gap-fill)\n  get their own rows with formulas.\n- **Every derived cell** is a live `=` formula — no hardcoded computed numbers:\n  - **Q4 in-stream:** `=FY_cell - Q1_cell - Q2_cell - Q3_cell` in the **same row**\n    as Q1–Q3\n  - **Segment remainder:** `=Total_cell - Seg1_cell - Seg2_cell`\n  - **Per-unit:** `=Revenue_cell / Units_cell`\n  - **Implied useful life:** `=NetPPE_cell / Depreciation_cell`\n  - **Take rate:** `=NetRevenue_cell / GrossBookings_cell`\n  - **Segment mix %:** `=Segment_cell / Total_cell`\n- DeepKPI-sourced cells are **values** (with links per the Revelata Excel styling\n  rules), not formulas; derived cells are **black** formulas, not hardcoded.\n\n**CSV:** Per `../_common/revelata-excel-styling-rules.md` — `provenance_url` /\n`formula` columns as needed; recommend `.xlsx`.\n\n## Common pitfalls\n\n- **Separate row for imputed Q4**: imputation belongs in the **quarterly series row**,\n  not a second line item for the same stream (especially in Excel).\n- **Flow/stock confusion**: subscriber counts, store counts, balance sheet items\n  are stocks — year-end value is Q4, not derived by subtraction.\n- **Unit mismatch**: deepKPI may return some values in thousands, others in\n  millions. Check units before dividing.\n- **Non-December fiscal year**: ensure FY and Q1–Q3 are all from the same fiscal\n  year, not the calendar year (e.g., AAPL ends September, NVDA ends January).\n- **Negative remainder**: if FY − Q1 − Q2 − Q3 < 0, check that annual and\n  quarterly values use the same metric definition and filing series.\n- **Hardcoded inputs**: never use a revenue or count figure that wasn't just\n  pulled from deepKPI in this session — always show the search that sourced it.\n"
}