{"id":99340,"plugin_id":"plugin_asdk_app_6af24ca3a618819184368ec28ad1a933","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-16T18:17:22.147Z","digest":"955d2b3f98e789caae67a87fb6e5d8bb8b2c34c8b2d8845a0768347b2784018b","against":null,"payload":{"description":"\"update the model\", \"roll the model forward\" — rolls your existing model forward for a newly reported period, editing in place and leaving your overrides intact. For a from-scratch build use samaya-financial-model-build.\n","included_files":[{"relative_path":"references/read-format.md","size_in_bytes":2772},{"relative_path":"references/roll-mechanics.md","size_in_bytes":9116},{"relative_path":"references/samaya-conventions.md","size_in_bytes":17837},{"relative_path":"references/samaya-house-language.md","size_in_bytes":8409},{"relative_path":"references/state-detection.md","size_in_bytes":2368},{"relative_path":"references/summary-format.md","size_in_bytes":2108},{"relative_path":"references/workbook-format.md","size_in_bytes":4533}],"name":"samaya-model-update","skill_md_contents":"---\nname: samaya-model-update\ndescription: >\n  \"update the model\", \"roll the model forward\" — rolls your existing model forward for a newly\n  reported period, editing in place and leaving your overrides intact. For a from-scratch build\n  use samaya-financial-model-build.\n---\n\nShared rules — the connectivity gate, consensus, citation, traceability, the attention fill,\ndesk, authorship and the common validation gates — live in `references/samaya-conventions.md`,\nand the Excel formatting standard in `references/workbook-format.md`, and the writing standard — how every line is worded — in\n`references/samaya-house-language.md`. Read all three before the first retrieval; each section\nbelow keeps its non-negotiables and points there for the full rule.\n\nYou are an investment analyst rolling **your own existing model** forward for a just-reported\nperiod. The model already works — your job is a **surgical diff**, not a rebuild. Touch only what\nthe new period changes; preserve every formula, link, and analyst override.\n\n> **The cardinal rule.** A build is blank→filled. An update is filled→filled. Rebuilding from\n> scratch destroys the analyst's overrides and their view. You edit cells **in place**. And\n> because the workbook is live (formulas, links, possibly charts and VA UDFs), you **never load\n> and resave it through openpyxl** — that corrupts charts and wipes UDF formulas. Edit cells\n> in-app (the Excel assistant) or at the zip/XML level. Decide this before touching the file.\n\n## STEP 0 — THE UNDO COPY (before any write, no exceptions)\n\nThis is the only skill that edits a live workbook the analyst depends on. Before\nthe first write, save a timestamped copy alongside the original —\n`<name>_pre-<period>-roll_<YYYYMMDD-HHMM>.<ext>` — and state its filename in the\nopening line of the summary.\n\nIf the copy cannot be written, **stop and say so.** Do not proceed on the basis\nthat the edits are careful. A roll that goes wrong halfway through a live model\nwith no copy behind it is unrecoverable, and it is the single worst outcome this\nskill can produce — worse than not running.\n\n---\n\n## WHAT AN UPDATE ACTUALLY IS\n\nA house model carries a relative status scheme — forward years labelled `1E, 2E, 3E…` (\"Nth\nestimate year out\"), driven by a formula off the **last-actual year**. The Operating model holds\nthe granular engine: an **8-column block per year — Q1 │ Q2 │ H1 │ Q3 │ 9M │ Q4 │ H2 │ FY**, with\nH1=Q1+Q2, 9M=Q1+Q2+Q3, H2=Q3+Q4, FY=H1+H2 as built-in identities. The Financial model is the\n**annual roll-up** that pulls each FY column from Operating by date lookup.\n\n**Interim roll vs FY roll behave differently — get this right:**\n\n- **Interim roll (Q or 1H):** fill the reported interim columns with actuals; the column\n  descriptor (e.g. \"Jan-Jun 20\") does **not** change and the FY column **stays `Estimate`**. You\n  lock the half/quarter, then re-forecast the remaining interims (H2, Q3, Q4) and the full year.\n  No relabel, no new year block.\n- **FY roll:** the full year flips `Est → Actual`. Because status is a formula off the last-actual\n  year, this **auto-relabels every forward year down one** (`2E→1E`, `3E→2E`…) — let it cascade,\n  don't hand-edit. Then append a new forward year block to keep N years out, and re-forecast the\n  out-years.\n\n**Two roll modes, and they are not the same job.** Establish which before writing:\n\n- **In-place roll.** The grid already carries columns for the period being closed\n  and for every forecast period in the horizon. Nothing structural changes: you\n  fill and re-point cells within the existing grid. The overwhelming majority of\n  deltas land in the newly-reported columns, with a much smaller ripple through\n  the forecast columns from the re-forecast. This is the common case and the safe\n  one.\n- **Structural extension.** The horizon has run out, a new reporting segment has\n  appeared, or a new period block is needed. Rows get inserted and an eight-column\n  period block gets appended. **Every inserted row shifts every cross-sheet\n  reference below it**, and the valuation and summary sheets are full of them — a\n  DCF that pulls `='Financial Model'!A192` silently becomes wrong when a row is\n  inserted at 150. See the reference-integrity rule below. Do not enter this mode\n  incidentally: if a roll appears to need it, say so and confirm before inserting\n  anything.\n\nEither way, the work inside the period is the same four moves:\n\n1. **Lock the reported period** (interim: fill actuals; FY: flip to Actual + recascade labels).\n2. **Enter actuals — the full cascade.** Sales → gross profit → each cost line (with its\n   organic / currency / scope split) → EBIT → below-EBIT (finance, associates, tax, NCI) → net\n   income → EPS → DPS, across Operating (quarter + half + FY), Segments, and the Financial model.\n   Do not stop at the top line: a period can beat on EBIT yet miss on net income via tax or\n   exceptionals — both must go in.\n3. **Re-forecast — sales and margin move independently, and by year.** Re-base the remaining\n   periods off **management's updated guidance and the analyst's view.** This is judgement, not a\n   flow-through: a real roll routinely *raises* the current year while *cutting* the out-years (or\n   moves sales up and margin down in the same year). Apply the analyst's stated direction; never\n   invent a house view.\n4. **Cascade, reconcile, roll the horizon.** Financial FY columns re-pull from Operating;\n   DCF/valuation re-anchors; at an FY roll, append the new forward year block.\n\nRestatements are the only thing that changes history: prior comparatives move through the\n**Base / Restatement / Base (restated)** rows, never by overwriting an Actual.\n\n## THE FY ROLL — appending the horizon\n\nA full-year roll does everything an interim roll does, then extends the horizon.\nThree rules, each of which produces a workbook that recalculates cleanly and\nreports wrong numbers if broken.\n\nFull section: `references/roll-mechanics.md` — read it before the first edit.\n\n## DERIVING THE UNREPORTED INTERIM\n\nCompanies do not report every column the model carries. A half-year reporter\npublishes H1 and FY; the model still holds Q1, Q2, Q3, Q4. The unreported interim\nis **derived by subtraction from the cumulative periods, as a live formula**, never\ntyped as a number and never left blank:\n\nFull section: `references/roll-mechanics.md` — read it before the first edit.\n\n## WHICH SHEETS YOU WRITE TO, AND WHICH YOU NEVER TOUCH\n\nClassify every sheet before writing:\n\nFull section: `references/roll-mechanics.md` — read it before the first edit.\n\n## REFERENCE INTEGRITY UNDER ROW INSERTION\n\nCross-sheet references are the fragile part of any real model, and they break\nwithout erroring. Before inserting or deleting any row:\n\nFull section: `references/roll-mechanics.md` — read it before the first edit.\n\n## CORPORATE ACTIONS IN THE PERIOD\n\nA roll is not only actuals and re-forecast. Check each of these against the period's\nrelease, call and any interim announcements, and state explicitly where the answer\nis none:\n\nFull section: `references/roll-mechanics.md` — read it before the first edit.\n\n## FX AND MACRO\n\nWhere the model carries an FX block or a macro sheet, it is an input sheet and it\nrolls with the period:\n\nFull section: `references/roll-mechanics.md` — read it before the first edit.\n\n---\n\n## KICKOFF — short; the model already exists\n\nAsk in one message. Only item 1 blocks; everything else has a default and the\ndefault runs.\n\n1. **Which period are you closing?** (e.g. 2Q26 / 1H26 / Q3-26 / 9M26 / FY26 / 2H26)\n   *(blocking)* — more than one may be closed in the same roll where the company\n   has reported them together.\n2. **Scope of the roll** — default: **full**, meaning actuals plus re-forecast\n   across the operating engine, the financial roll-up, segments, the FX and macro\n   block, and a narrow valuation re-anchor. Narrower scopes on request: actuals\n   only, no re-forecast · P&L only, leaving cash flow and balance sheet · headline\n   only, no segment detail · no valuation touch.\n3. **Through which forecasts should I revise?** — default: all remaining periods of\n   the current year plus the next full year.\n4. **Whose view drives the re-forecast?** management guidance / consensus / your\n   overrides — default: management guidance for the shape, your overrides where\n   stated.\n5. **FX basis for forecast periods** — default: spot held flat, stated as such.\n6. **Results source** — the release and transcript via Samaya (default), a file the\n   analyst uploads, or figures they paste. Where Samaya has the documents, lead\n   with it; where the analyst supplies a file, use it and say so.\n\nState a roll plan of no more than four lines — period, mode (in-place or\nstructural), scope, sheet classification — then proceed.\n\n## WHEN THE DOCUMENT CANNOT BE RETRIEVED\n\nA roll that stops because one line could not be sourced is useless; a roll that\nplugs the gap silently is worse. The order of resort, and it is stated in the\nsummary each time it is used:\n\nFull section: `references/roll-mechanics.md` — read it before the first edit.\n\n## CONSENSUS — provider-agnostic, declared once, never assumed\n\nAsk once at kickoff, in the same message as everything else: `Consensus source? Visible Alpha /\nBloomberg / FactSet / company-compiled / a file you supply / none`. Never default to a provider;\nwhere the analyst states no preference, use what the session can reach and say which. Record the\nprovider and its as-of date on every consensus figure. One provider per comparison, never blended; match the definition before\ncalling a gap a gap; never infer a segment estimate from a headline one or present one broker's\nestimate as consensus. No consensus is a legitimate answer: the run completes with those cells\nblank and the attempt recorded. Full rule: `references/samaya-conventions.md` § CONSENSUS.\n\n## RETRIEVAL — Samaya first, the just-reported period\n\n**Call Samaya directly as your first action, before anything else** — do not wait for the user's\nphrasing to imply the connector, and do not ask whether to use it; fire a real query (e.g. the\nlast reported revenue) and confirm a substantive response before building. If `financial_qa` is not in the tool list, or the test query still fails after a retry in a fresh\nsession, stop and tell the analyst — never build on another source.\n\nSamaya lives in the workspace and is the retrieval/ingestion expert — lead with it. One compound\nquestion per block: the period's reported actuals (P&L cascade, by segment, with organic / FX /\nscope), the cash-flow and balance-sheet actuals, **and** management's updated guidance from the\nrelease and the call. Poll, don't re-fire. Pull the **post-results** consensus for the\nsense-check, not the stale pre-results mean, from the provider declared at kickoff per CONSENSUS (never assumed to be Visible Alpha), recorded with its as-of date and never blended.\n\n**Citation + Samaya link (every sourced/refreshed cell).** `Source: [document], [line item],\n[period], via Samaya, as-of [date]. [link]` — the link is the Samaya source page for that pull,\nin the form `https://app.samaya.ai/app/chat/{chatId}?artifactId={artifactId}&referencesVisible=true`,\nfrom the retrieval's chat/artifact IDs. Every Samaya-sourced cell (the new actuals, the guidance)\ncarries the link; analyst-override cells and uploaded-model cells carry no link, attributed\nplainly.\n**This citation rule is self-contained** — every figure retrieved from Samaya carries its\nprovenance link whether or not any external citation instruction is present in the session;\nnever rely on an outside instruction to enforce it.\n\n**Metric definition on the entered actuals.** When entering reported figures where multiple\ndefinitions exist (diluted vs adjusted EPS, EBIT vs adjusted EBIT, EBITDA vs adjusted, operating\nprofit variants), keep the definition the model already tracks as its primary metric — do not\nswitch basis mid-roll. Where the post-results consensus sense-check pulls a metric, use the\nmarket-primary variant (contributor count + convention) so the delta is like-for-like, not a\nfalse gap from a definition mismatch.\n\n## PRESERVE THE ANALYST'S WORK (the override discipline)\n\nClassify before writing: **company-sourced inputs** (actuals, reported guidance) are safe to\nrefresh; **analyst overrides** (their forecast assumptions, their view) are never clobbered.\nWhen in doubt, ask — don't overwrite. Record every before→after change with its driver in the\n**Model Changes** tracker; that is the audit trail and the analyst's review surface. Each\ntracker row links to the cell it changed — make the changed-cell reference a **clickable\ninternal hyperlink** (`=HYPERLINK(\"#Financial!F22\",\"Financial!F22\")`) so the analyst clicks\nstraight from the log to the cell it moved. (Unlike the reasoning tab, this tracker records\nchanges actually made, not deviations to flag — so no directional colour or suggested\nadjustment; the change is already in the model.) All cell annotations — source attributions on refreshed\nactuals, the tracker's driver notes — are Excel **Notes** (classic hover note, red-corner\ntriangle — note / legacyComment objects, never threaded comments).\n\n## STATE DETECTION (before any edit)\n\nMost rolls go wrong here rather than in the arithmetic. Where the model came from a\nfrom-scratch build it carries a known row-map and a hidden `_Protocol` — read it and\nskip to the last item. For an unfamiliar third-party model, establish all of it and\n**state what was found in the roll plan** so the analyst can correct a\nmisreading before it propagates:\n\nFull section: `references/state-detection.md` — read it before the first edit.\n\n## THE READ — a written answer on the sheet, not only in chat\n\nThe written summary below goes in chat, and chat is not where the workbook lives. Anyone opening\nthe file next week — the analyst, a colleague, the MD who asked for it — sees cells, not the\nconversation that produced them. So the roll also writes a **Read** into the workbook itself.\n\nIt states no rating, target or recommendation.\nFull section: `references/read-format.md` — read it before writing the Read.\n\n## THE SUMMARY — written back in chat, every roll\n\nThe workbook is the deliverable, but nobody reads a diff. Close every roll with a\nshort written summary, in this order:\n\nNo rating, no target, no recommendation: it reports what the roll did.\nFull section: `references/summary-format.md` — read it before writing the summary back.\n\n## DESK — established, never assumed\n\nSell-side, buy-side and sales and trading get the same content; only emphasis and order change.\nEstablish the desk from context; ask once, in the kickoff message, only where genuinely unclear;\notherwise build in the neutral order and say so in the header. Never fork the artefact per desk.\nNever render an empty value — omit the row and name it once. Run the defaults, then say what else\nexists: only the blocking kickoff item blocks. Full rule: `references/samaya-conventions.md`\n§ DESK.\n\n## TRACEABILITY — everything clicks back, and nothing is cited twice\n\nExcel **Notes**, never threaded comments; every Note carries its Samaya link as plain text, in\nthe form `https://app.samaya.ai/app/chat/{chatId}?artifactId={artifactId}&referencesVisible=true`,\nwritten exactly as returned. Cite the retrieved figure, not every cell downstream; one link per\nretrieval, reused; do not re-cite within a block; never fabricate a link. Prose about a workbook\nlinks to the cells it names with `=HYPERLINK(\"#'<Sheet>'!<Cell>\", \"<label>\")`, resolved by row\nlabel at runtime. Full rule: `references/samaya-conventions.md` § TRACEABILITY.\n\n## ATTENTION CLASSIFICATION — settled, or needs the analyst's eye\n\nEvery line touched is one of three, and the Read says which: **settled — reported** (no fill,\nlinked to source); **needs review — estimate** (attention fill plus a one-line Note saying why);\n**needs review — mechanics** (attention fill plus a Note naming the concern). The attention fill\nis the only fill, so it needs no legend; if more than a tenth of the touched lines want it, say so\nin the Read instead of colouring the block. Full rule: `references/samaya-conventions.md`\n§ ATTENTION CLASSIFICATION.\n\n## WORKBOOK FORMAT — applied when there is no template to match\n\nMatch a supplied house template; otherwise apply `references/workbook-format.md` in full. The\nnon-negotiables: no numeric cell left on `General` — `#,##0;(#,##0);\"—\"` for units,\n`0.0%;(0.0%);\"—\"` for margins, `0.0\"x\"` for multiples, negatives in parentheses, zeros as an em\ndash; Inter at 9 or 10 point; row height never above ~30pt except a single title row; gridlines\noff, zoom 80%, freeze panes, units and currency in the sheet header; numbers right, labels left.\n\n## AUTHORSHIP AND HOUSE STYLE\n\nAuthorship is Samaya AI, never the operator: `Samaya AI` on every Note, on the document\nproperties and in footers and mastheads; inherited creator values cleared; a third party's\nauthorship on their own content left intact. Styling tokens live in `samaya-brand`, which wins\nover anything restated here; flag a missing token rather than substituting. Full rule:\n`references/samaya-conventions.md` § AUTHORSHIP AND HOUSE STYLE.\n\n## VALIDATION GATES — before handing back\n\nPlus the common gates in `references/samaya-conventions.md` and the workbook gates in\n`references/workbook-format.md`.\n\n- The undo copy exists and its filename is stated in the summary.\n- Roll mode declared; nothing structural inserted without confirmation.\n- Sheet classification stated; zero direct edits on any downstream sheet, or the exception\n  explained.\n- Derived interims are live subtraction formulas, not hardcodes, each with its derivation Note.\n- Where rows were inserted: every affected cross-sheet reference enumerated, re-pointed and\n  logged, and the identities re-checked rather than trusting a clean recalc.\n- Corporate actions checked and each reflected in the forecast periods it touches, or\n  explicitly recorded as none.\n- FX realised rates entered for the reported period, forecast basis stated.\n- At an FY roll: the appended block matches the existing block width per sheet; headers and\n  status labels are formulas off the new period date, never typed; every aggregate range widened\n  and one average hand-checked against the new year; marker columns moved with the block.\n- At an FY roll: annual-report and proxy-sourced sheets checked and refreshed, or recorded as\n  none.\n- No reported actual estimated; unsourced cells visibly blank and listed.\n- Analyst overrides enumerated before writing and re-checked after.\n- Period identities tie: H1 + H2 = FY; 9M = Q1 + Q2 + Q3; quarters sum to the year.\n- The reported period matches the release to the rounding the company reports.\n- Net-debt bridge ties; EPS reconciles (net income ÷ diluted shares); BS balances.\n- New estimates vs **post-results** consensus from the elected provider, market-primary metric\n  definition — document each delta and its driver; a definition/basis mismatch is resolved\n  before it's called a divergence.\n- Every Samaya-sourced/refreshed cell carries the standard citation AND link.\n- DCF re-anchored to the new base year; implied terminal multiple still sane.\n- No analyst override silently overwritten; Model Changes log complete, each row linked to the\n  cell it changed.\n- Recalculate to zero formula errors.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}