equity-model-update

name	equity-model-update
description	Safely update public-company Excel model copies from source-to-model maps; emits XLSX as the hero artifact and CSV/log/manifest as support. Do not use for pure earnings notes or broad workbook audits.

Equity Model Update

Skill Configuration

User Context Preflight

Before searching connectors, retrieving evidence, or drafting output, run python3 skills/user-context/scripts/user_context_preflight.py with the shell working directory set to this plugin's root, and follow the returned saved_context, source_category_plan, and next_action. Set the working directory before the first attempt; do not probe alternate relative paths. Missing context must not block the requested workflow. Do not initialize state or run onboarding during ordinary workflow work.

If next_action.id = "offer_orientation" and the parent router has not already handled it, complete the requested work first and append its one-line optional setup offer once.

Source Resolution

Load ../../shared/workflow-source-resolution.md. Use source_category_plan lazily and attempt only the categories needed for this workflow: company_filings_ir, earnings_transcripts_presentations, internal_research, portfolio_models_trackers, and market_data_estimates.

Deliverable Intake

Apply the presentation-surface precedence in ../../shared/deliverable-intake-policy.md. This workflow's natural artifact is an XLSX equity model workbook. Do not choose chat-only output unless the user explicitly requests a lightweight response.

Before source gathering or analysis for a new standalone reader-facing hero deliverable, load ../../shared/deliverable-intake-policy.md and use its adaptive request_user_input preflight for materially unresolved format, depth, audience/use, or focus choices. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

Use this skill when the real job is updating a listed-equity model from reported actuals, guidance, consensus, transcript/KPI disclosures, or user assumptions, then translating the changed lines into estimate revisions, valuation support, target-price implications, and PM action.

Use When

Use this skill to refresh public-company model inputs as a controlled source-to-model process. It owns safe copied-workbook updates, source-to-model maps, change logs, stale/missing data flags, pre/post-print model update checklists, and support CSV artifacts.

When an Excel model is supplied, default to a copied updated workbook or workbook control pack as the primary human deliverable. CSV, run-log, JSON citations, and manifest outputs are support artifacts. The user-facing handoff should lead with the updated .xlsx package, model implication, estimate-revision path, valuation/target-price read-through, source posture, changed/blocked cells, and update dashboard; for substantial reusable update packages, render an HTML dashboard/report alongside the workbook or hand off to the relevant workbook builder so the workbook Cover carries the insight view.

For dashboard handoffs, use references/DASHBOARD_PACK.md. equity-model-update owns source-to-model mapping, changed-line interpretation, stale/missing flags, and model implication, valuation read-through, and PM action implication; dashboard-builder owns the shell/rendering/QA. Build a public_equity_investing_dashboard.v1 payload as an internal renderer input, and keep JSON/Markdown/CSV/run-log support files behind the HTML dashboard unless explicitly requested.

Do Not Use For

Use neighboring skills for pure earnings notes, post-print interpretation, formula audits, raw cleanup, trade pitches, and memo prose.

When To Invoke Support

Load shared/support-layer-routing-contract.md when support services are needed. Use financial-source-of-truth for reported actuals, guidance, consensus, source timestamps, and claim labels. Use financials-normalizer before building the source-to-model map from messy release tables, transcript KPI tables, segment schedules, share-count support, net debt, or capital allocation data. Use excel-data-cleaner before relying on malformed model-update exports. Use model-audit-tieout for formula integrity, recalc/cache state, external links, circularity, and final tie-out. Support artifacts stay secondary to the copied workbook/control pack and update dashboard.

Workflow

1. Identify company, period, event, user model status, and decision.
2. Use user files first, company primary sources next, connected consensus/market data when available, then public fallback.
3. Label numbers as reported actual, guidance, consensus, user estimate, agent estimate, market-implied, inferred, or judgment.
4. Map each source metric to a model line and assign mapping_treatment before calculating a delta: safe_update for true input updates, reference_only for facts that inform the review but cannot replace a model input, missing_model_architecture when the workbook lacks the required schedule, assumption_required when an investor judgment is needed, or rebuild_required when the model cannot express the update safely. Only safe_update rows may populate proposed model values or estimate-change deltas.
5. For EPS model lines, separate reported GAAP EPS, adjusted/operating EPS, recurring EPS drivers, tax/share-count effects, and below-the-line/non-recurring items before updating forward EPS.
6. If a workbook is supplied, run a preflight and write only to a copied workbook. Never mutate the original workbook. Update mapped non-formula input cells only when sheet/cell, prior value, new value, source ID, freshness, and confidence are sufficient.
7. If workbook editing is unsafe, under-mapped, protected, formula-targeted, stale, or ambiguous, create a workbook-based control pack with Update_Cover, Source_Map, Rebuild_Requirements, Change_Log, Tie_Out, and Stale_Data review tabs instead of editing model cells.
8. When the supplied workbook lacks the operating schedules required for an estimate refresh, state that refreshed estimates and valuation are unavailable, retain cached legacy valuation only as a stale reference, and identify the missing architecture or rebuild requirements. Do not present reported quarterly metrics or net-cash reference facts as changes to an annual DCF output formula.
9. Surface recalc/cache warnings: formula workbook versus cached values, stale workbook calculation state, external links, formula overwrite risk, source timestamp, and whether Excel/Sheets recalculation is still required. Require recalculation after copied input edits that affect formulas; do not require recalculation merely because an unchanged control-pack workbook contains cached formula values. Never imply formulas were recalculated if the runtime only inspected cached values or edited copied input cells.
10. Route formula integrity, external-link checks, circularity, final tie-out, and rebuilt model work to model-audit-tieout, DCF, three-statement, comps, or public-model builders as appropriate.
11. When a final presentation workbook is restyled, renamed, or exported after materialization, make that final .xlsx the only user-facing primary workbook. Update run_log.json, manifest.json, and model_update_citations.json to point to the final workbook and its final sheet names before handoff; do not lead with an unstyled intermediate control pack.

Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: new source extraction, estimate/guidance deltas, model input changes, source labels, and change-log QA. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.

Executable Contract

Safe copied-workbook helper:

python scripts/materialize_workbook_update.py input.csv --workbook uploaded_model.xlsx --out output

Default workbook modes:

• xlsx_update_copy: updates safe mapped input cells in updated_model.xlsx.
• xlsx_control_pack: preserves model cells, opens on the Update_Cover review tab, and adds review tabs in model_update_control_pack.xlsx.
• csv_update_map_export: mapping/log fallback when no workbook is supplied or the user explicitly asks for support artifacts only.

Support-only helper:

python scripts/materialize_model_update.py input.csv --out output

Workbook outputs: updated_model.xlsx or model_update_control_pack.xlsx, plus source_to_model.csv, change_log.csv, tieout_checklist.csv, model_update_citations.json, run_log.json, and manifest.json. The manifest marks the workbook as primary_human_deliverable; if a polished successor workbook is exported, promote that successor consistently across the manifest, run log, and model citations.

The workbook helper reports calc_chain_present, formula_cell_count, cached_formula_value_count, calc_mode, and recalc_required in the run log and cover tab. It separately labels artifact readiness and model readiness: a completed control pack may be ready for review while the model remains not updated and requires mapping or rebuild. If mapped inputs are changed and formulas exist, treat downstream formula outputs as stale until Excel/Sheets recalculation and model-audit-tieout are complete.

Support-only outputs: source_to_model.csv, change_log.csv, tieout_checklist.csv, run_log.json, and manifest.json. The run log includes status, model_status, source basis, warnings, hard failures, output paths, and output manifest. Hard failures: missing source_id, missing model_line, malformed/empty input. Stale data is flagged.

Output Standard

Lead with the workbook artifact when a model was supplied. Include model implication, changed cells, blocked cells, source/data-quality note, comparison table when available, KPI/model-driver dashboard, source map, change log, tie-out checklist, and post-print actions.

References: references/workflow.md, references/templates.md, references/sector-kpis.md, references/executable-contract.md.

Equity Valuation PM Standard

Load shared/equity-valuation-pm-standard.md and shared/pm-judgment-heuristics.md for substantial model, valuation, scenario, model-update, or audit work.

The output must state what the current stock price implies, the variant estimate path, whether upside is driven by fundamentals, multiple expansion, mix, capital return, sentiment, or event probability, what breaks first in downside, what changes target, rating, sizing, hedge, trim, exit, or watchlist status, and what evidence is missing.

Keep equity valuation as the center of gravity. Debt is allowed only as an input to common-equity value through net debt, cost of debt, leverage, liquidity, refinancing risk, or downside equity impairment. Use Credit Markets for bond comps, loan comps, CDS, spread/yield relative value, covenant-package analysis, debt-security valuation, recovery waterfall, restructuring valuation, creditworthiness, private-credit / public-credit instrument underwriting, or distressed claim valuation.