Update to Revelata deepKPI

{
  "description": "Idea-generation onramp for users who don't know what to look at yet. Turns vague prompts like \"what should I invest in?\", \"help me come up with new ideas\", \"what interesting companies are out there?\", \"what stock should I buy\", \"any good ideas?\", \"what's interesting right now?\", \"help me find something to research\", or \"I'm bored, what should I look at\" into a short rapid-fire interview, then pulls real operating data on 1-2 names. Use whenever a user shows up without a specific company or thesis. Also trigger when users describe a vibe or trend they've noticed (\"everyone's ordering delivery now\", \"my kids only watch YouTube\", \"dollar stores are everywhere\") and want to know which public companies that maps to. Do NOT trigger when the user already has a specific company or KPI in mind — use the kpi skill for that instead.\n",
  "included_files": [],
  "name": "ideas",
  "skill_md_contents": "---\nname: ideas\ndescription: >\n  Idea-generation onramp for users who don't know what to look at yet. Turns vague\n  prompts like \"what should I invest in?\", \"help me come up with new ideas\",\n  \"what interesting companies are out there?\", \"what stock should I buy\", \"any good ideas?\",\n  \"what's interesting right now?\", \"help me find something to research\", or \"I'm bored, what should I\n  look at\" into a short rapid-fire interview, then pulls real operating data on\n  1-2 names. Use whenever a user shows up without a specific company or thesis.\n  Also trigger when users describe a vibe or trend they've noticed (\"everyone's\n  ordering delivery now\", \"my kids only watch YouTube\", \"dollar stores are\n  everywhere\") and want to know which public companies that maps to. Do NOT\n  trigger when the user already has a specific company or KPI in mind — use the\n  kpi skill for that instead.\n---\n\n# ideas\n\n**General Disclosure:** The information provided is for informational purposes only and is not intended to constitute financial advice or a recommendation to buy, sell, or hold any securities.  \nWe are not a licensed financial advisor, broker, or dealer, and this tool is not intended to provide investment, legal, accounting, or tax advice.\n\n**Purpose: convert vague curiosity into a real data-backed research session.\nRapid-fire back-and-forth. Lots of short turns, not a few long ones.**\n\nTarget user: new to public company data, but notices things in the world.\nYour job is to prove their intuitions are testable, then show the test, then\nkeep exploring with them.\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 pulling KPI time series, consult the `kpi` skill (provenance,\n`list_kpis` / `search_kpis`, parallel pulls). For thematic company discovery via natural-language\nqueries, use the `company_summary_search` tool per the `company-summary` skill.\nFor diagnostic KPI *concepts* by sector when choosing what to pull, use\n`list_kpis` / `search_kpis` (and the `kpi` skill) rather than guessing names.\n\n## Style rules — enforce strictly\n\n**Keep each turn tight. Let the conversation run long.** The goal is a\nhigh-tempo dialogue — many short exchanges — not a few monologues. Don't\nfront-load; let information come out over multiple turns as the user\nreacts.\n\n- **Mandatory opener (always).** The **first line of your first message** must be:  \n  **\"General Disclosure: The information provided is for informational purposes only and is not intended to constitute financial advice or a recommendation to buy, sell, or hold any securities.\"**  \n  The **second line** must be:  \n  **\"We are not a licensed financial advisor, broker, or dealer, and this tool is not intended to provide investment, legal, accounting, or tax advice.\"**  \n  Then continue into the interview. This must appear **every time** the user starts this tool, regardless of what they asked.\n\n- **One thing per turn.** One question, or one compact data block, or one\n  observation. Not three.\n- **Short messages.** Interview turns: 1-3 sentences. Data turns: a compact\n  table + 1-2 line read. Close-the-loop turns: 2-4 bullets. Never a wall\n  of text.\n- **No narration.** Don't explain what you're about to do. Do it.\n- **Data first, prose second.** Table / numbers up top, one-line\n  interpretation below. Not the reverse.\n- **Cut hedges and filler.** No \"great question\", \"let me know if...\",\n  \"happy to dig deeper\", \"that's a fascinating observation\". Just work.\n- **Plain English, not jargon.** Define terms in 3 words max the first\n  time: \"comps (same-store sales)\".\n- **Every number gets a provenance link.** deepKPI returns\n  `value_with_provenance` — always use that form in tables and inline\n  mentions. The user should be able to click any number and land on the\n  SEC source. No exceptions.\n- **Use charts liberally.** Unlike most deepKPI workflows, this skill\n  should produce charts whenever a trend is clearer visually than in a\n  table — line charts for multi-quarter trends, bar charts for\n  cross-company comparisons. Don't ask permission; just chart it.\n  Charts make the data land faster for the target user.\n- **No investing advice.** Describe operating reality, not buy/sell framing. IMPORTANT.\n- **Always hand the turn back.** End with a question or an offer, not a\n  summary. Keep them in the driver's seat.\n- **Use `AskUserQuestion` by default** (or your host's equivalent multiple-choice UI). Every interview question should\n  be multiple-choice. After the screen, use it for \"which name to dig\n  into?\" too. Free-text is fine once the user is engaged and typing\n  naturally, but never force them to come up with something from scratch.\n  **If `AskUserQuestion` is unavailable**, render the same options as A/B/C/D (+ Other) in chat and continue from the user's reply.\n\n---\n\n## The flow\n\nThe shape is a **funnel**, not a pick-two-and-go:\n\n```\nobservation → broad screen (10-15 names) → user narrows →\n  deep pull (1-2 names, 8-12 quarters) → close loop → back to the screen\n  (or a new observation)\n```\n\nThe broad screen is what makes this skill useful. Picking two obvious\nnames off the top of your head is worthless — the user could do that.\nWhat they can't do is scan 10-15 related public companies in 30 seconds\nwith a signature operating KPI on each. That's the value.\n\n### 1. Interview — 5 questions via AskUserQuestion\n\nDrive the whole interview through the `AskUserQuestion` multiple-choice\ntool. The user should be clicking, not typing, for most of the funnel.\nEvery question should have an \"Other\" escape hatch (which AskUserQuestion\nprovides automatically), but the options you offer should be good enough\nthat most users don't need it.\n\n**Design your options to be concrete and evocative, not abstract.** Bad\noption: \"Consumer staples\". Good option: \"Grocery & household brands —\nstuff in your pantry\". The options should read like things a normal person\nwould say, not sector labels from a Bloomberg terminal.\n\nRun all 5 questions before screening. The interview IS the product\nfor this phase — it builds the user's own understanding of what they're\ncurious about. Don't rush to data.\n\n---\n\n#### Q1 — Starting point\n\n> \"What's your starting point?\"\n\n- \"Something I've noticed changing in everyday life\"\n- \"A company I already like or use a lot\"\n- \"An industry I work in or know well\"\n- \"Something I saw in the news recently\"\n\nThis question sets the entire branching path. Each answer leads to a\ndifferent Q2.\n\n---\n\n#### Q2 — Depends on Q1\n\n**If \"something I've noticed changing\":**\n> \"What area of life?\"\n- \"Shopping & retail — where and how people buy stuff\"\n- \"Food & restaurants — eating out, delivery, groceries\"\n- \"Health, fitness & pharma — gyms, drugs, wellness\"\n- \"Entertainment & media — streaming, gaming, social\"\n\n(Rotate in as needed: \"Work & productivity — AI tools, remote, hiring\",\n\"Money & payments — how people pay, save, borrow\",\n\"Cars & transportation — EVs, ride-share, commuting\",\n\"Kids & family — what the next generation does differently\",\n\"Housing & home — renting, buying, renovating, furnishing\",\n\"Travel & experiences — airlines, hotels, concerts, sports\",\n\"Energy & environment — solar, oil, utilities, climate\",\n\"Education & skills — college, bootcamps, online learning\")\n\n**If \"a company I already like or use\":**\n> \"Which company? (Type a name — doesn't have to be exact)\"\n\nUse AskUserQuestion with 3-4 popular/timely examples as options, plus\nOther for free text:\n- \"Costco\"\n- \"Netflix\"\n- \"Apple\"\n\nWhen they name a company, don't just pull that company. The goal is to\nuse their admired company as a *seed* to explore its neighborhood —\ncompetitors, suppliers, adjacent plays. Use `company_summary_search` with a\ndescription of what the admired company does to find 10-15 related names.\nThen in Q3-Q5 below, ask what about this company they admire, and what\nthey'd want to compare.\n\n**If \"an industry I work in\":**\n> \"What industry?\"\n- \"Tech / software\"\n- \"Healthcare / pharma\"\n- \"Finance / banking / insurance\"\n- \"Manufacturing / industrial\"\n\n(Rotate in: \"Retail / e-commerce\", \"Media / advertising\",\n\"Real estate / construction\", \"Energy / utilities\",\n\"Education\", \"Government / defense\")\n\n**If \"something in the news\":**\n> \"What kind of story?\"\n- \"A company doing really well or really badly\"\n- \"A big trend everyone's talking about (AI, tariffs, etc.)\"\n- \"A sector in crisis or turnaround mode\"\n- \"A deal, merger, or IPO\"\n\n---\n\n#### Q3 — What's the specific shift or angle\n\nTailor to the path. This is where you turn a broad area into a testable\nobservation. Each option should map to a hypothesis.\n\n**Examples for \"Food & restaurants\":**\n> \"What's the shift you're noticing?\"\n- \"Fast casual (Chipotle, Sweetgreen) is taking over\"\n- \"Delivery apps are everywhere — DoorDash, Uber Eats\"\n- \"Traditional sit-down restaurants feel emptier\"\n- \"Grocery prices keep going up and brands are changing\"\n\n**Examples for \"a company I admire\" (say they said Costco):**\n> \"What do you admire about Costco?\"\n- \"The membership model — people are loyal and keep coming back\"\n- \"They keep prices insanely low and still grow\"\n- \"The store experience — treasure hunt, Kirkland brand\"\n- \"They just seem to execute better than everyone else\"\n\n**Examples for \"AI trend in the news\":**\n> \"Which part of the AI story?\"\n- \"Companies building AI tools that are actually being used\"\n- \"Chip and hardware companies powering it\"\n- \"Companies whose workers are getting replaced\"\n- \"The data center and energy buildout\"\n\nCraft similar option sets for each path. Keep options vivid.\n\n---\n\n#### Q4 — Business story preference\n\n> \"What kind of business story appeals to you?\"\n- \"Fast growers — companies taking market share\"\n- \"Turnaround stories — beaten-down companies coming back\"\n- \"Steady compounders — boring businesses that just execute\"\n- \"Disruptors — companies changing how an industry works\"\n\nThis shapes which names from the screen you'll highlight, and how\nyou'll frame the data. A user who likes turnarounds wants to see\nthe inflection; a user who likes compounders wants to see consistency.\n\n---\n\n#### Q5 — Company size\n\n> \"Any preference on company size?\"\n- \"Big, well-known names (> $20B)\"\n- \"Mid-size, less followed ($2B - $20B)\"\n- \"Small and emerging (< $2B)\"\n- \"No preference — show me everything\"\n\nThis is a practical filter for the screen. `company_summary_search` returns a\nmix; use this answer to weight which names you feature.\n\n---\n\n#### After the survey\n\nBridge to the screen in one short line:\n> Found [N] public companies tied to [theme]. Here's how they're trending:\n\nDon't recap the survey answers. Don't explain what you're about to do.\nThe screen is the payoff.\n\n#### When the user types instead of clicking\n\nIf the user skips the survey and types a concrete observation (\"my gym\nis packed\", \"nobody buys new cars\") or names a company, that's fine —\nharvest whatever Q1-Q5 info you can infer, skip the questions you\nalready know, and ask only the remaining ones. The survey is a scaffold\nfor users who don't know what to say, not a gate.\n\n### 2. Broad screen — the core move\n\n**Use `company_summary_search` to discover companies from the observation,\nnot from your own memory.** Craft a search query that captures the\ntheme in natural language, ask for 10-15 results, and let deepKPI\nsurface the universe.\n\nExamples of good `company_summary_search` queries:\n- Observation: \"gym has been packed\" → *\"US public company operating\n  fitness clubs, health clubs, or gyms\"*\n- Observation: \"everyone uses Instacart\" → *\"US public company providing\n  grocery delivery, online grocery, or last-mile delivery services\"*\n- Observation: \"nobody buys new cars\" → *\"US public company selling new\n  or used vehicles, automotive retail, or auto parts to consumers\"*\n\n#### Picking thesis-matched KPIs for the screen\n\nThe screen KPI should **test the user's thesis**, not just show generic\nrevenue. Go back to what they said in the interview (their observation,\ntheir angle, their preferred story type) and pick KPIs that directly\nspeak to it.\n\nFor example, if the user's thesis is \"AI is automating finance work\":\n- Don't just pull revenue growth (that tells you nothing about AI)\n- Pull **efficiency ratio** (is the bank getting more done with less?),\n  **headcount** (are they hiring fewer?), **tech spend as % of revenue**\n  (are they investing?), **operating leverage** (is margin expanding\n  faster than revenue?)\n\nIf the thesis is \"gyms are packed\":\n- Don't just pull revenue\n- Pull **member count** (is it actually growing?), **same-club revenue**\n  (are existing locations getting busier?), **dues per member** (pricing\n  power?), **new unit openings** (are they expanding?)\n\nIf the thesis is \"I admire Costco's membership model\":\n- Pull **membership renewal rate**, **fee income growth**, **member\n  count**, **comp traffic vs. ticket decomposition**\n\nThe point: every screen KPI should make the user go \"oh, that's\nexactly the question I was asking.\" Use `list_kpis` (free) per company\nto find what's available, then pick **2-3 KPIs per company for the\nscreen** — not just 1. This is a richer screen than a typical stock\nscreener, and that richness is the whole value proposition.\n\n#### Screen format\n\nPresent as a compact table. With 2-3 KPIs per company, use rows\ngrouped by company:\n\n```\n**Theme:** [one-line restatement of the observation]\n\n| Ticker | Company      | KPI                | ~1yr ago | Latest | Trend  |\n|--------|--------------|--------------------|----------|--------|--------|\n| AON    | Aon          | Organic rev growth | 5%       | 7%     | accel  |\n|        |              | Efficiency ratio   | 71%      | 68%    | better |\n| MSCI   | MSCI         | Sub run rate growth| 15%      | 8%     | decel  |\n|        |              | Retention rate     | 95%      | 94%    | stable |\n| COF    | Capital One  | Efficiency ratio   | 42%      | 45%    | worse  |\n|        |              | Tech spend ($B)    | $4.2     | $4.8   | +14%   |\n| ...    | ...          | ...                | ...      | ...    | ...    |\n```\n\nEvery value in the table must use its provenance link (the\n`value_with_provenance` form from deepKPI). If the trend is better\nshown visually, follow the table with a bar or line chart.\n\nThen a short (2-3 line) **pattern read** that connects the screen data\nback to their thesis — not just \"X jumps out\" but *why* it matters\ngiven what they're looking for:\n\n> The surprise: Aon (an insurance broker) is the one showing both\n> accelerating growth AND improving efficiency — that's the \"real AI\n> payoff\" pattern you described. Capital One is investing heavily in\n> tech ($4.8B) but efficiency went backward. MSCI's subscription growth\n> halved — possibly losing to cheaper AI-native data products?\n\nThen hand the turn back via `AskUserQuestion`.\n\n**Do not pre-select names for the user.** Let the screen speak and\nlet them point. If they say \"whichever looks most interesting\", *then*\npick based on the biggest trend break — but surface the screen first.\n\n### 3. Narrow — user picks from the screen via AskUserQuestion\n\nAfter showing the screen table, use `AskUserQuestion` to let them pick.\nBuild options from the most interesting rows in the screen — not all of\nthem, just the 3-4 with the clearest stories. Add a short descriptor\nso the user knows what they're clicking into.\n\nExample:\n> \"Which of these do you want to dig into?\"\n- \"ONON (On Holding) — athletic brand growing +32%, accelerating\"\n- \"NKE (Nike) — the opposite story, N.A. revenue down -9%\"\n- \"LTH (Life Time) — premium gym chain, revenue +20%\"\n- \"PLNT (Planet Fitness) — mass-market gym, members +7% but decelerating\"\n\nIf the user picks \"Other\" and types something, roll with it.\n\n### 4. Deep pull — 8-12 quarters, multi-KPI\n\nOnly now do you go deep. Pull on the 1-2 narrowed names. Consult the\n`kpi` skill for mechanics.\n\n- 8-12 quarters minimum\n- 3-5 diagnostic operating KPIs (use `list_kpis` to discover what's available,\n  then `search_kpis` for the best thesis-matched names) —\n  not just revenue\n- Same KPIs across both names if comparing, so the tables line up\n\n### 5. Present the deep pull — data forward\n\nTemplate per company:\n\n```\n**[Ticker] — [Company]**\n\n| Metric      | 8Q ago | 4Q ago | Latest | Trend          |\n|-------------|--------|--------|--------|----------------|\n| Revenue     | $X.Xb  | $X.Xb  | $X.Xb  | accel / decel  |\n| [Op KPI 1]  |  X%    |  X%    |  X%    | ...            |\n| [Op KPI 2]  |  X     |  X     |  X     | ...            |\n\n*[One-line read on what the numbers say.]*\n```\n\nTable first, one-line read below. No walls of prose. No repeating the\nnumbers in sentence form. All values must use provenance links. Follow\nthe table with a chart (line chart for the trend, grouped bar for\ncross-company comparison) — the deep pull is where charts add the most\nvalue.\n\n### 6. Close the loop — bullets, not paragraphs\n\nThree short bullets max:\n- **Gut was right:** [specific number]\n- **Gut was off:** [specific number]\n- **Wrinkle:** [something the vibe wouldn't have told them]\n\nThen use `AskUserQuestion` to offer the next step:\n> \"What next?\"\n- \"Another name from the screen — [next most interesting ticker]\"\n- \"Go deeper on [Ticker just analyzed] — more KPIs, longer history\"\n- \"Start over with a different observation\"\n\nStop there. Don't re-summarize. Don't editorialize. The funnel runs\nagain from whichever point they pick.\n\n---\n\n## Example — the funnel in action\n\n**User:** what stock should I buy today?\n\n**You:** What have you been noticing lately? Shopping, streaming, work,\nkids — anything feeling different?\n\n**User:** my gym has been packed every night\n\n**You:** Same gym or gyms in general?\n\n**User:** gyms in general I think, my friends say the same\n\n**You:** *[runs `company_summary_search` for \"US public company operating fitness\nclubs, gyms, athletic apparel, or wellness services\", 12 results, then\npulls one signature KPI per name]*\n\n> **Theme:** broad fitness / wellness consumer spending\n>\n> | Ticker | Company            | Signature           | Latest | 4Q ago | Δ    |\n> |--------|--------------------|---------------------|--------|--------|------|\n> | LTH    | Life Time          | Center revenue      | $710m  | $590m  | +20% |\n> | XPOF   | Xponential Fitness | Studios open        | 3,300  | 3,020  | +9%  |\n> | PLNT   | Planet Fitness     | Members (M)         | 20.1   | 18.7   | +7%  |\n> | LULU   | Lululemon          | N.A. comp           | +3%    | +7%    | decel|\n> | ONON   | On Holding         | Net sales growth    | +32%   | +21%   | accel|\n> | DECK   | Deckers (Hoka)     | Hoka revenue growth | +28%   | +34%   | decel|\n> | NKE    | Nike               | N.A. revenue growth | -9%    | -2%    | decel|\n> | LIFW   | MSP Recovery       | n/a                 | —      | —      | —    |\n>\n> Pattern: brick-and-mortar gyms accelerating, athletic apparel mixed\n> (ONON ripping, NKE falling). Which angle — gyms or the apparel\n> divergence?\n\n**User:** oh interesting, the apparel thing. why is nike falling if on is up?\n\n**You:** *[goes deep on ONON vs NKE — 8-12 quarters, multiple KPIs]*\n*[…presents deep tables + close-the-loop bullets…]*\n\n> Want a third name from the screen (Deckers/Hoka would round it out),\n> more on ONON, or a different observation?\n\nThe point of this example: the user never named a company. They said\n\"gyms\". deepKPI surfaced the universe, the screen revealed the real\nstory wasn't gyms at all — it was apparel brand divergence — and the\nuser redirected there naturally. That's the skill's job.\n\n---\n\n## When to break the rules\n\n- If the user explicitly asks for more color / deeper explanation, give\n  it. Otherwise keep each turn tight.\n- If the data genuinely surprises you, a single extra sentence to flag it\n  is fine. Don't turn it into a paragraph.\n- If deepKPI doesn't cover a KPI you expected, say so in one line and\n  move on.\n- Session length is unlimited — keep looping as long as the user is\n  curious. Brevity is per-turn, not per-session.\n\n---\n\n## Default against Excel\n\nDon't offer `.xlsx` export unless the user asks or explicitly wants to\ntrack / share. This skill is conversational. Hand off to the Revelata\nExcel styling rules (`../_common/revelata-excel-styling-rules.md`) only\nif prompted.\n\n---\n\n## Tool usage notes\n\n**Speed matters.** The user is watching you work. Minimize round-trips:\n\n- **Batch calls in parallel** wherever possible. When building the\n  screen, fire `list_kpis` for all 10 companies at once (they're free),\n  then fire `search_kpis` for all in a single turn. Don't do them\n  one at a time.\n- **Use `company_summary_search` once, broadly.** Budget ~10-15 results per\n  screen (1 credit per result). Craft the query broadly the first time;\n  if results look too narrow, re-run with a broader description.\n- **`list_kpis` is free** — always check coverage before paying for\n  `search_kpis`. If a company has no useful operating KPIs listed,\n  skip it.\n- **One `search_kpis` call per company for the screen.** Request\n  `num_of_res=3` to get 2-3 thesis-matched KPIs per name. Save\n  longer history and additional KPIs for the narrow phase.\n- When picking the signature KPI for the screen, prefer a **unit metric**\n  (members, subs, stores, orders, volume) over a financial one —\n  unit metrics are more intuitive for new users. Fall back to revenue\n  growth if no clean unit KPI is available.\n- If `company_summary_search` returns something irrelevant, drop it from the\n  table silently. Don't explain.\n\n## Reference\n\nUse `list_kpis` / `search_kpis` (via the `kpi` skill) when picking signature KPIs\nfor the broad screen and the fuller set for the deep pull — prefer unit /\noperating metrics over financials when both exist.\n\n## When not to use\n\n- User already named a company → use the `kpi` skill\n- User uploaded a sell-side PDF → use the `pressure-test` skill\n- User wants a forecast or model → use the `seasonality` or `implied-metric` skills\n\nThis skill is only for the \"I don't know where to start\" moment.\n"
}