skills/equity-model-update/references/DASHBOARD_PACK.md

# Equity Model Update Dashboard Pack

Use this when a public-company model refresh, source-to-model update, post-print change log, KPI dashboard, or model-input QA package needs an HTML dashboard/report.

## Producer Role

`equity-model-update` owns safe copied-workbook update status, source-to-model mapping, changed input identification, stale/missing data labels, model implication, and handoff to workbook/model owners. `dashboard-builder` owns the shared HTML shell, module rendering, responsive layout, citation behavior, and validation.

## Recommended Payload

- `mode`: `equity_model_update`
- `layout`: `single_page` for reusable model-update packages unless the user explicitly requests tabs
- `hero.callout`: the most important model implication or unresolved update risk
- `snapshot`: primary workbook artifact, separate artifact and model readiness, changed driver count, applied/blocked/reference-only cell count, KPI/source posture, biggest valid estimate impact, stale/missing data count, recalc/cache warning, formula cell count, external-link status, next action
- `model_citations_path`: point this to `model_update_citations.json` so workbook/sheet/cell provenance generated by `materialize_workbook_update.py` renders in the source ledger
- `sources`: release/filing/deck/transcript first, model/user files next, consensus/market data next, and assumptions clearly labeled
- Raw JSON, Markdown notes, CSV exports, run logs, and manifests are support/audit material unless the user explicitly asks for them.

## Tabs And Modules

1. `model-read`
   - `decision_box`: model implication, readiness, primary workbook artifact, key update, blocked fields, and next handoff
   - `metric_tiles`: changed drivers, applied cells, blocked cells, reference-only facts, stale fields, source confidence, tie-out status, formula cells, cached values, calc-chain status, recalc required, external links, and separate model/workbook status
2. `changed-lines`
   - `table`: model line, workbook sheet/cell, prior value, new value, applied/blocked status, source, basis, period, change driver, and PM read
3. `kpi-driver-dashboard`
   - `key_metrics`: company-specific KPIs, driver changes, source basis, and model relevance
   - `growth_trajectory`: driver acceleration/deceleration when source-backed and comparable
4. `source-map`
   - `table`: source-to-model mapping, source confidence, stale/missing flags, and unsupported assumptions
5. `actions`
   - `timeline`: post-print/model-update tasks, workbook handoff, audit checks, and review triggers
   - `missing_evidence`: missing sources, stale data, unsupported line items, and unavailable workbook/model files

The source tab is normally generated from top-level `sources`.

## Required Evidence

- Production dashboard payloads must include `metadata.payload_stage: "production"`, `mode`, `layout`, `hero`, non-empty `snapshot`, `sources`, `metadata.freeze_time`, `metadata.source_posture`, `metadata.readiness_label`, `metadata.readiness_posture`, `metadata.decision_context`, and `metadata.citation_policy: "strict"`.
- Use `metadata.payload_stage: "draft"` or `"support"` with `metadata.citation_policy: "warn"` only for internal support payloads; final HTML/XLSX/chat handoffs must keep gaps visible and must not claim PM-ready, client-ready, committee-ready, external, or publication-ready status.
- Cite every changed model line, KPI, estimate, source timestamp, and model implication.
- Cite workbook-derived claims to `model_update_citations.json` so chips can show workbook, sheet, cell, prior value, new value, source ID, and block status.
- Label source-reported, model-derived, user-provided, assumption, stale, and unsupported fields.
- Label formula workbook versus cached values. Never imply formula outputs were recalculated if the runtime only inspected cached formula values or edited copied inputs; show Excel/Sheets recalculation required only after copied inputs were changed, and keep an unchanged control pack labeled as not a refreshed valuation.
- Use `metadata.citation_policy: "strict"` for production dashboards.

## Do Not

- Do not make the dashboard look like the original workbook was mutated; only copied workbook artifacts can be represented as edited.
- Do not present a blocked control pack as if model cells were updated.
- Do not hide stale or missing source fields behind a clean model implication.
- Do not make raw JSON, Markdown notes, CSV sidecars, run logs, or manifests the lead user-facing artifact unless explicitly requested.

## QA Checks

- Validate with `skills/public-equity-investing/internal-support/dashboard-builder/scripts/validate_payload.py`.
- Confirm model implication, primary workbook artifact, changed lines, applied/blocked cells, source map, stale/missing data, and workbook handoff are visible.
- Confirm workbook citations point to changed or blocked cells rather than only CSV rows.
- Confirm workbook/formula integrity, recalc/cache, external-link, formula-overwrite, and stale calculation-state issues route to the appropriate model/audit skill.