← Samaya Finance SkillsCONTENT HISTORY
WHAT CHANGED
Update to Samaya Finance Skills
Snapshot Nov 16, 2026 · 18:17 UTC · version 1.2.2
Collection source: downloaded plugin package.
First saved snapshot
No earlier snapshot is available to establish a change.
Save Samaya Finance Skills and check future changes in Following.
Up to 3 plugins free · no card required.
Compare saved observations
Download comparison JSONFull technical diff · 0 changed fields
Full snapshot data
{
"description": "\"KPI history\", \"pull four years of [metric] for [company]\", \"track a reported KPI\" — builds the full, primary-sourced history of a company-reported operating KPI (monthly, quarterly or annual; one company or a peer set) through Samaya, every period in the window present, a source on every figure, and gaps, definition breaks and revisions marked. Always delivered as a downloadable Excel file.",
"included_files": [
{
"relative_path": "references/retrieval-and-gaps.md",
"size_in_bytes": 5619
},
{
"relative_path": "references/samaya-conventions.md",
"size_in_bytes": 17837
},
{
"relative_path": "scripts/build_workbook.py",
"size_in_bytes": 5196
}
],
"name": "samaya-kpi-history",
"skill_md_contents": "---\nname: samaya-kpi-history\ndescription: >-\n \"KPI history\", \"pull four years of [metric] for [company]\", \"track a reported KPI\" — builds\n the full, primary-sourced history of a company-reported operating KPI (monthly, quarterly or\n annual; one company or a peer set) through Samaya, every period in the window present, a source\n on every figure, and gaps, definition breaks and revisions marked. Always delivered as a\n downloadable Excel file.\n---\n\nYou are building the history of a number a company reports, and the reason this is worth a skill\nis that the easy version fails quietly. Ask a model for \"four years of XPO tonnage\" and it returns\na dozen rows from press-release aggregators, assumes a reporting cadence the company never used,\nskips the periods it could not find, and presents the result as complete. The analyst then\nre-checks every figure by hand. This skill does the opposite: it establishes how the company\ndiscloses the metric, builds every period the window requires, fills each one from the filing or\ncall it came from, and shows the analyst exactly what is missing and why.\n\n> **The cardinal rule.** **Every period in the window has a row, and every row has a source or a\n> stated reason it has none.** A series that is shorter than the window without saying so is a\n> build failure. A figure with no document and date behind it does not go in the table.\n\n> **The delivery rule.** **The product is a downloadable Excel file in the chat.** Every run ends\n> with the `.xlsx` workbook sent to the analyst as a file attachment they can click and download.\n> A chat summary without the attached Excel is a failed run. A file path printed in chat, or a\n> file saved only on disk, is **not** delivery. Do not finish your reply until the Excel has been\n> sent.\n\n---\n\n## STEP 0 — SAMAYA CONNECTIVITY GATE (hard requirement, before anything else)\n\n**Do not begin until Samaya MCP is verified live.**\n\n1. **Check the tool list** for `Samaya:financial_qa` and `Samaya:financial_qa_result`. If absent:\n **STOP.** Tell the analyst the Samaya connector is not active in this session and ask them to\n enable it (connectors icon in the Claude sidebar, or Settings > Connectors in claude.ai), then\n wait. Do not proceed, do not substitute another source, do not build \"what you can\".\n2. **Call Samaya directly as your first action** — the disclosure-map query for the first company\n in scope — and confirm a substantive response. A tool that is listed but errors, times out or\n returns empty counts as NOT live.\n3. **Retry ladder on any mid-run failure:** retry same session_id → fresh session → record the\n period as unretrieved and continue. **Never silently fall back to web search.**\n4. **Non-Samaya sources require explicit analyst approval, per source**, with the true retrieval\n path stated.\n5. **Samaya mechanics.** `financial_qa` returns citations, not an answer: write every figure from\n the snippets. Poll `financial_qa_result` by job_id until done; never re-send the same question\n to get a result. Parallel calls each take a fresh, empty session_id.\n\n## EMPTY INVOCATION — say what this does, then ask\n\nIf the skill is invoked with no company, metric or thesis, do not guess. Reply with two lines on\nwhat it does and three example prompts, one per entry route, then ask for theirs:\n\n> I build the full history of a KPI a company reports — for one company or a peer set — with a\n> source on every figure, as a downloadable Excel file, plus a short read of the trend. You can\n> give me an exact metric, a rough one, or a thesis you want tested.\n>\n> - **Exact:** \"Barclays UK NIM, quarterly, Q1 2021 to Q2 2026\"\n> - **Rough:** \"Chipotle traffic over the last two years\"\n> - **Thesis:** \"I think Dutch Bros' food launch is driving a durable traffic lift — what data\n> would show it?\"\n>\n> Which company and what would you like to see?\n\n## KICKOFF — route the request, state the defaults, then build\n\nOnly the **company** blocks. Everything else has a default and the default runs.\n\n1. **Company or companies** *(blocking)* — one name, a list, or a peer set the analyst names.\n2. **Metric** — exact, rough, or absent with a thesis given. Routed below.\n3. **Window:** **the last 12 months, ending at the latest period the company has reported\n (default)**, or any period the analyst names.\n4. **Frequency:** **the finest cadence the company discloses for that metric (default)** —\n established by the disclosure map, never assumed. Twelve months of a monthly metric is twelve\n rows; of a quarterly metric, four; of a half-yearly metric, two.\n5. **Sources:** **company disclosures only (default)** — filings, releases, results\n presentations, earnings-call and conference transcripts. Broker research only on request,\n labelled as such and never mixed into a reported-actuals column.\n6. **Output:** **the attached Excel plus a chat summary — always** (the delivery rule). A table in\n chat, if asked for, is added on top and never replaces the workbook.\n\nState the plan in one line and build:\n`No period given — pulling the last 12 months. XPO discloses this monthly (8-K releases and\nearnings calls), so 12 monthly rows. You'll get a downloadable Excel at the end.`\n\n### Routing — three entry routes into one pipeline\n\n| Input | Route |\n| --- | --- |\n| **Exact** metric, company, period | Disclosure map → grid → retrieve → gap pass → Excel delivered. No questions. |\n| **Rough** metric (\"traffic\", \"churn\") | Disclosure map resolves it. One clear reported match: state the reading in one line and run. Several genuine candidates: show a 2–4 item menu with cadence and history depth, default pre-selected, and wait. None: say so and offer the closest disclosed proxy, labelled as a proxy. |\n| **Thesis** only | Thesis mode (below): propose KPIs → disclosure check → **analyst confirms** → pipeline → per-KPI evidence read → Excel delivered. |\n\n## THE DISCLOSURE MAP — always first, per company\n\nBefore any figure is retrieved, establish for each company and metric:\n\n- **The exact reported label** and the company's definition of it (e.g. \"tonnage per day, North\n American LTL, year-over-year %\", not \"tonnage\").\n- **Where it is disclosed**: monthly operating-data 8-K, quarterly release, results presentation,\n call transcript only, 10-Q/10-K, annual report.\n- **The cadence**, including figures that exist only on a call — monthly figures inside a quarter\n that the release reports only as a quarterly total.\n- **When disclosure starts** and whether it has stopped.\n- **Fiscal calendar**: year-end, quarter labels, 52/53-week years.\n- **Known breaks**: redefinitions, re-segmentations, restatements, accounting changes, M&A that\n changes the scope.\n\nWhere the analyst's premise does not match the disclosure, correct it in the plan line before\nbuilding — \"XPO does not publish daily tonnage; it reports tonnage per day, monthly, as a YoY %.\"\nCorrecting the premise is part of the product, not a caveat.\n\n**Combine the map with the most recent block.** One call asks for the label, definition,\nlocation, cadence and start date **and** the values for the most recent block of periods (the\nfirst chunk in `references/retrieval-and-gaps.md`). For the 12-month default this one call often completes the retrieval. Any\nvalues it returns go straight into the grid and are not fetched again.\n\n**Disclosure that starts or changes inside the window.** Periods before the finer cadence began\nstay in the grid at that cadence with status `Not disclosed`, and the coarser figure that does\nexist (the quarter) goes in the row's Note — never spread across the months.\n\n**Start-date guard — never trim on a guess.** Periods before the start date are skipped without a\nquery **only** when the map returns an explicit company statement of when the disclosure began\n(XPO, Q1 2023 call: \"we're going to be providing monthly tonnage data starting this quarter\").\nOtherwise the earliest document found is not proof of a start: send one **boundary probe** for the\nblock just before it, and trim only what that probe confirms is not disclosed. Figures are often\ngiven retrospectively — XPO's first monthly 8-K was for May 2023, but January–April 2023 were\ndisclosed on the calls.\n\n## THE GRID — every period exists before any value does\n\nBuild the full row set for the window at the disclosed cadence **before retrieval**. Every\nexpected period is a row from the start, so a period that cannot be found surfaces as a gap\nrather than disappearing. Where the cadence changed inside the window (quarterly, then monthly),\nthe grid follows the disclosure and the Notes tab records the change.\n\n## RETRIEVAL, GAP PASS AND RECONCILIATION\n\n**Read `references/retrieval-and-gaps.md` before the first retrieval call** and follow it in\nfull: chunking by cadence, document anchoring, parallel calls and polling, the slow-chunk and\nlarge-job rules, the two-step gap pass, and the reconciliation rules with the status vocabulary\nevery row carries (`Final`, `Preliminary`, `Derived`, `Comparative`, `Proxy`, `Not disclosed`,\n`Not retrieved`, `Not yet reported`).\n\n## MULTIPLE COMPANIES — the peer panel\n\n- **One disclosure map per company.** The same concept carries different labels and definitions\n across companies (\"NIM\", \"customer spread\", \"NII / average assets\"); each company's definition\n is shown beside its values.\n- **Calendar alignment.** Report each company's fiscal periods and map them to calendar quarters\n so a May year-end lines up against December peers.\n- **Comparability flags, not silent normalisation.** Cells that are not like-for-like — a\n different definition, currency or cadence — are marked.\n- **Plan check.** Above roughly 8 companies or 5 years, show the call plan and estimated time and\n confirm before running.\n\n## THESIS MODE — from a claim to the KPIs that test it\n\nUsed when the analyst has a view but not the metric.\n\n1. **Translate the thesis into 2–4 testable, reported KPIs**, with one line each on why it bears\n on the claim. **Include at least one KPI that could disprove it**, and mark which way each\n would cut. A list of only supporting metrics is a build failure.\n2. **Disclosure check before proposing.** Show, per KPI, whether the company reports it, at what\n cadence and since when. A metric that would be ideal but is not disclosed is shown as\n unavailable, not dropped silently.\n3. **Look for a natural comparison.** Where the company discloses a group the change did not reach\n — shops that cannot run the new program, regions not yet rolled out, franchise vs company\n units — propose it alongside the KPIs. A difference between the two groups tests a thesis\n far better than a single trend line.\n4. **Wait for confirmation.** This is the one route that blocks after kickoff, because the\n choice of metrics is the analyst's call. If the analyst says \"go\", run the first two.\n5. **Build the confirmed KPIs** through the standard pipeline, ending with the attached Excel.\n6. **Per-KPI evidence read**, in place of plain trend bullets: for each KPI, whether the series is\n `consistent with`, `inconsistent with`, or `not informative on` the thesis, with the numbers and\n periods that make it so. **No overall verdict.** Weighing the evidence into a call, or arguing\n both sides, is a separate request the analyst can make through `use-samaya`.\n\n## HARD RULES\n\n1. **Disclosure before retrieval.** No figure is fetched until the metric's label, definition,\n cadence and start date are established.\n2. **The grid is the window.** Every expected period has a row; the table is never silently\n shorter than the window.\n3. **Primary sources by default.** Aggregator sites, news rewrites and broker tables are not\n sources for reported actuals unless the analyst approves them, and then they are labelled.\n4. **No silent estimates.** Derived, comparative and proxy values carry their status and their\n working. Interpolation is never used.\n5. **Breaks are visible.** A redefinition, restatement or cadence change is marked in the series\n and explained on the Notes tab.\n6. **Describe, do not characterise.** Trend bullets state direction, magnitude, inflections and\n breaks with the numbers. No \"strong\", \"impressive\" or \"worrying\".\n7. **Only the company's own words count.** A figure an analyst states in a call question is not a\n disclosure, even when management does not correct it.\n8. **Name what is missing, individually.** Every `Not disclosed` and `Not retrieved` period is\n listed in the chat summary, not counted.\n9. **No Excel, no deliverable.** The delivery rule above, without exception.\n\n## OUTPUT\n\n### Step 1 — Build the Excel workbook\n\nOne workbook per run, named `<Company or Peer set> <Metric> <Window>.xlsx`. Build it with the\nbundled `scripts/build_workbook.py`: write the grid as the JSON spec documented at the top of that script and\nrun it (`python scripts/build_workbook.py spec.json out.xlsx`; it needs `openpyxl`, which most\nsandboxes have — otherwise `pip install openpyxl`). Save the output in the session's outputs\nfolder (e.g. `/mnt/user-data/outputs/`) when one exists. Do not write workbook code by hand; the\nscript fixes the layout, statuses, notes and gap shading so every run looks the same. The workbook\nholds:\n\n1. **Series** — one row per period (per company × period for a peer panel): the period label, one\n column per metric, status, a Source column per metric hyperlinked to the provenance link, and a\n Note. Put the unit and basis in the metric name (\"Tonnage/day YoY %\"). Each value cell carries\n a cell note with the document, date, the sentence or table row containing the figure, and the\n provenance link. Gap rows are shaded.\n2. **Pivot** — peer panels only: periods down, company × metric across.\n3. **Chart** — single-company runs: one line chart of the metrics.\n4. **Notes & breaks** — the disclosure map per company: definition, cadence, start date, breaks,\n proxies used and why, and anything deliberately excluded.\n5. **Scorecard** — the same figures as the chat scorecard.\n\nProvenance links are used exactly as the retrieval returns them (currently short links of the\nform `https://app.samaya.ai/u/…`). Never reconstruct, normalise or invent one. The citation rules in\n`references/samaya-conventions.md` apply on top of these.\n\n### Step 2 — Deliver the Excel as a downloadable file (mandatory)\n\nA file created by a script is **not** visible to the analyst until you send it. Right after the\nworkbook is built and checked:\n\n1. **Send the `.xlsx` into the chat as a file attachment** using the file-delivery tool (in Cowork:\n `SendUserFile` with the workbook path, `display: \"attach\"`). The analyst must see a download\n card for the Excel.\n2. **If a folder from the analyst's computer is connected**, also save the workbook there and say\n the folder and file name in plain words.\n3. **If sending fails**, say so plainly in the reply and retry once; never end the run silently\n without the file.\n4. **Never** say \"the workbook is attached\" unless the send step succeeded.\n\nSend the Excel **before** writing the final chat summary, so the summary can point to it.\n\n### Step 3 — Chat summary, in this order\n\n1. **Plan line** as stated at kickoff, including any premise correction.\n2. **Scorecard**:\n `Periods: 44/48 found · Not disclosed: 4 (Sep–Dec 2022, before monthly reporting began) ·\n Sources: 39 call transcripts, 5 filings, 0 web · Derived: 0 · Breaks: 0 · Time: 5 min 25 s`\n3. **Trend read** — 3–5 bullets (thesis mode: the per-KPI evidence read), each with the figures\n and periods behind it and a link to the source.\n4. **Gaps and breaks** — each missing period named with its reason; each break with its date.\n5. **The Excel** — one line pointing to the attached, downloadable workbook (\"The Excel is attached\n above — click to download\") and what its tabs hold.\n\nDo not repeat the series table in chat; the workbook carries it.\n\n## BOUNDARIES AGAINST NEIGHBOURING SKILLS\n\n- **One current figure** (\"what was Q2 backlog?\") — plain Samaya Q&A, not this skill.\n- **Guidance changes and management language** — `samaya-guidance-credibility`, or\n `samaya-guidance-sweep` and `samaya-management-narrative-drift` through `use-samaya`.\n- **Rolling a model forward** — `samaya-model-update`.\n- **Checking figures already in a document** — `samaya-fact-checker`.\n- **A verdict on a thesis or the argued cases** — plain Samaya Q&A through `use-samaya`.\n- **Consensus and forecasts** — out of scope; this skill builds reported history only.\n\n## VALIDATION GATES — before handing back\n\n- Samaya verified live before the first build step; no silent web fallback anywhere.\n- Disclosure map completed for every company before retrieval; any premise correction stated.\n- No period trimmed as `Not disclosed` without an explicit company statement or a boundary probe\n confirming it.\n- Window ends at the latest reported period unless the analyst named one; unreported periods\n carry `Not yet reported`.\n- Grid row count equals the window at the disclosed cadence, per company.\n- Every value has a document, date, excerpt and working provenance link; no fabricated link.\n- Every empty cell went through the two-step gap pass and carries a status and reason.\n- Derived, comparative and proxy values labelled with their working.\n- Breaks marked in the series and explained on the Notes tab.\n- Peer panel: definitions shown per company, calendars aligned, non-comparable cells flagged.\n- Thesis mode: at least one disconfirming KPI proposed; a natural comparison group proposed where\n one is disclosed; analyst confirmation recorded; no overall verdict given.\n- Workbook built with `scripts/build_workbook.py`, not hand-written code.\n- **The `.xlsx` was sent to the analyst as a downloadable attachment in the chat, and the send\n step returned success.** A path in text does not pass this gate.\n- Scorecard present in chat and workbook, with elapsed time.\n- One workbook delivered; no partial files except a labelled large-job preview.\n\n## SCOPE — what this does and does not do\n\n- **Builds reported history; it does not forecast.** Guidance, consensus and estimates are other\n skills' work.\n- **Completeness is bounded by disclosure.** Smaller names, private companies, metrics given only\n on calls and periods before transcript coverage are systematically harder; the scorecard and\n gap list say so rather than hiding it.\n- **Tests evidence for a thesis; does not decide it.**\n- **Most useful** when the analyst would otherwise pull the same metric period by period and\n stitch the answers together by hand.\n"
}SHA-256 of public snapshot: 94b57e58ef84dc93a0238237bc07d67da1422cbdebecc675fef4cab52ace7a0c