Public Equity Investing

View saved version →

---
name: catalyst-calendar
description: Use when building public-equity-investing catalyst calendars. Do not use for full event underwriting; use event-driven-analyzer.
---

# Catalyst Calendar

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Earnings Transcripts & Events`
- `Company Filings & IR`
- `Market Data & Estimates`
- `Internal Research`

## Internal Support

When this workflow needs rendering, evidence/data preparation, style, or sector context, route support through the visible `public-equity-investing` router and its bundled internal playbooks. Route workbook or model QA through the visible `model-audit-tieout` workflow.

## Deliverable Intake

Before source gathering or analysis for a new substantive hero deliverable, load `../../shared/deliverable-intake-policy.md` and use its adaptive `request_user_input` preflight for materially unresolved choices. For a substantive single-company 60/90-day catalyst calendar, the workflow default resolves the presentation surface to a polished HTML catalyst calendar unless the user asks for another format, a quick/no-file answer, or a workbook/tracker. In that case, do not block on a format question; ask only for unresolved 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.

## Purpose
Build or refresh source-backed Public Equity Investing catalyst calendars. The output should show timing, confidence, thesis relevance, prep work, owner/status, and likely PM decision, not just dates.

## Use / Do Not Use
Use for single-name, portfolio, sector, earnings, regulatory, clinical, technical, capital-markets, and special-situation catalyst tracking. Use the script for tracker workbooks, CSV/JSON intake, refresh logs, blank templates, or optional ICS export.

Do not use for merger-arb/spin/tender probability math; route to `event-driven-analyzer`. Do not use for pure pre-print notes, post-event analysis, model refreshes, thesis updates, risk sizing, or hedge design; route to `earnings-preview`, `earnings-deep-dive`, `equity-model-update`, `thesis-tracker`, or `portfolio-risk-management`.

## Reference Router
- `../../shared/html-artifact-standard.md`: shared principles for polished, legible, evidence-aware HTML artifacts.
- `source-and-data-protocol.md`: source hierarchy, stale-date checks, confidence labels, refresh rules.
- `catalyst-taxonomy-and-fields.md`: event fields, categories, scoring labels.
- `event-scoring-framework.md`: impact, confidence, controversy, urgency.
- `pm-action-playbook.md` / `portfolio-pm-playbook.md`: prep actions, thesis checkpoints, clustering, position context.
- `sector-and-asset-overlays.md`: sector-specific catalyst logic.
- `output-templates.md` / `pm-review-checklist.md`: delivery formats and QA.

## Workflow
1. Classify mode: no-context template, partial-context build, refresh, single-company map, portfolio dashboard, single-event brief, or sector sweep.
2. Set scope: default to next 30/60/90 days plus thesis-critical longer-dated items. Ask only for destructive or blocking choices.
3. Build rows with exact date or window, source, confidence, status, thesis link, model/KPI line, prep action, owner, and decision implication.
4. Rank by impact, confidence, controversy, actionability, portfolio relevance, and same-day clustering.
5. Convert high-priority events into work items, model updates, questions, risk/sizing reviews, hedge prompts, or post-event follow-up.
6. Refresh non-destructively: preserve prior rows, append evidence, mark stale/superseded items, and produce a change log.
7. For a named issuer plus a substantive 60/90-day calendar, default to a polished standalone HTML catalyst calendar when local artifact creation is available unless the user requests another format, a quick/no-file answer, or a workbook/tracker. In interactive runs, ask only for unresolved depth, audience/use, or focus choices; mention that another format is available as an opt-out without making it a blocking question. In non-interactive runs, apply the HTML catalyst calendar plus full working analysis defaults and disclose those assumptions in the delivery message or accompanying chat summary, not as visible artifact metadata.
8. For other multi-category calendars, PM monitoring calendars, or requests that ask for earnings plus macro/regulatory/company-specific catalysts, treat polished standalone HTML as the recommended presentation path and use `../../shared/deliverable-intake-policy.md` for materially unresolved format or depth choices.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: event/date verification, source freshness, catalyst impact, probability/timing, and follow-up monitoring. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Guardrails
- Never imply a date is confirmed without reliable evidence.
- Use windows for guided, estimated, inferred, or street timing; do not turn soft windows into one-day ICS events.
- Separate facts, assumptions, rumors, restricted/internal notes, and PM judgments.
- Do not invent earnings dates, trial readouts, approvals, lockups, merger deadlines, conferences, or policy dates.
- Surface conflicts and prefer company/regulator/exchange sources over aggregators.

## Default Output
Recommend the full catalyst package: PM summary, top-catalysts table, full catalyst register or clearly scoped subset, prep plan, source/freshness notes, refresh change log when relevant, decision implications, and recommended adjacent work.

For substantive single-company 60/90-day catalyst calendars, default to a concise chat summary plus a polished standalone HTML catalyst calendar when local artifact creation is available. This workflow default resolves presentation format unless the user requests another format, a quick/no-file answer, or a workbook/tracker. In interactive runs, ask for unresolved analysis depth and any consequential audience/use or focus choice, but do not require the user to confirm HTML before proceeding. In non-interactive runs, default to the HTML catalyst calendar and `Full working analysis`, and state the assumed format and depth in the delivery message or accompanying chat summary rather than in the visible HTML artifact.

If the user explicitly asks for a standardized dashboard, reusable dashboard template, or structured payload-driven render, route that optional rendering path through `dashboard-builder` and follow its payload and validation contract. `catalyst-calendar` continues to own event selection, timing, confidence, impact, and PM monitoring judgment. Keep JSON/Markdown/CSV/ICS support files behind the HTML artifact unless explicitly requested.

Use a single-event brief or compressed watchlist only when the user explicitly asks for a summary, quick read, one-pager, brief, TL;DR, or one specific event.

## HTML Guidance

For substantive HTML output, load `../../shared/html-artifact-standard.md` and apply these calendar-specific priorities:

- Use a title that identifies the requested artifact, such as `<Company> (<Ticker>): 90-Day Catalyst Calendar`; do not substitute a generic label such as `Decision Map` for a calendar request.
- Structure the first read as an investor brief: concise thesis checkpoint, add/hold/trim triggers, then the catalyst schedule. Put the detailed register, preparation queue, and source ledger below that scan layer.
- Make the catalyst schedule the primary visual object; the reader should reach upcoming dates and timing windows quickly.
- Before a detailed register table, include a compact month-by-month or time-horizon visual summary of the highest-decision-pressure confirmed dates and inferred windows. Keep it concise: the detailed register should own full explanations, implications, and sourcing.
- Show confirmed dates distinctly from inferred windows and unscheduled monitoring items.
- Surface the highest-decision-pressure events prominently, while retaining lower-priority confirmed issuer events in the calendar when they fall inside scope.
- Include preparation actions and add/hold/trim implications when the user supplies portfolio context.
- Keep sourcing unobtrusive but auditable, with visible timing confidence and material evidence gaps.
- A full catalyst register is appropriate for substantive calendars, but do not repeat the same event across overview, register, thesis tests, and prep sections unless each view answers a distinct investment question.
- Do not surface internal support-contract fields in the HTML artifact; convert relevant evidence gaps and readiness limitations into polished PM-facing prose.
- Do not show format-selection, intake, or generation-process notes such as `Format assumption` in the HTML artifact; keep any required default disclosure in the delivery message.

## Script Contract

```bash
python scripts/create_catalyst_calendar_workbook.py --input events.csv --output catalyst_calendar.xlsx --ics catalyst_calendar.ics
python scripts/create_catalyst_calendar_workbook.py --prior prior_events.csv --input refreshed_events.csv --output refreshed_calendar.xlsx
```

The script is a materializer, not a live data provider. It preserves source/confidence fields, keeps undated/windowed items in review tables, writes refresh changes, and exports ICS entries only for confirmed exact dates.

Workbook outputs start with a `Cover` tab that serves as the PM dashboard: as-of date, event counts, 30/60/90 day pressure, red/amber urgency, high-impact events, low-confidence events, overdue/missing-owner prep, top catalysts, source posture, and workbook map.

## Public Equity PM Judgment Layer

For substantial catalyst work, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

PM catalyst discipline: a catalyst only matters if it can alter estimate path, narrative, multiple, position size, downside, liquidity, or event probability.

Required PM judgment:
- Rank by `decision_pressure`, not date proximity alone.
- Add index/ETF and technical catalysts when relevant: index additions/deletions, Russell/S&P/MSCI rebalance, ETF reconstitutions, lockups, secondary offerings, buyback windows, blackout windows, passive ownership shifts, and float changes.
- Separate confirmed dates from inferred windows. Do not export inferred windows as exact calendar events.
- Group low-impact dates as hygiene unless they are tied to a decision.

Referenced files: 11

View saved version →

---
name: company-tearsheet
description: Use when creating source-backed public issuer tearsheets. Do not use for private diligence, fund diligence, vendors, or market maps.
---

# Company Tearsheet

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the catalogued source categories needed for the current tearsheet. Prefer a user-named source first, then one available app, connector, file, export, or pasted input that satisfies the category. Attempt the smallest useful native read only when the workflow needs that source. If a route needs auth, connection, or setup, state the practical limitation and continue from prompt context, active artifacts, pasted or exported material, and public sources when the tearsheet can still be useful. Do not inspect unrelated source categories, run broad source setup, write connector readiness, or create, read, migrate, or update `category-state.json`.

The runtime source categories below cover the catalogued Public Equity Investing sources. Use `references/source-and-evidence.md` for the broader evidence hierarchy and freshness rules.

### Workflow Sources

When this skill uses a source category, use it for the following information. These are semantic source categories, not fixed connector names.

- `company_filings_ir`: filings, IR materials, reported financials, and issuer disclosures needed for the factual baseline.
- `earnings_transcripts_presentations`: transcripts, presentations, events, and recent management commentary when they materially change the issuer read.
- `internal_research`: internal notes, expert context, prior research, and team discussions when they materially improve the baseline.
- `portfolio_models_trackers`: portfolio context, watchlists, models, and thesis trackers only when they materially change the investor lens or downstream route.
- `market_data_estimates`: market data, consensus, estimates, ownership, positioning, and provider exports needed for valuation context and freshness checks.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Market Data & Estimates`
- `Company Filings & IR`

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. When the user explicitly requests HTML for a tearsheet, that resolves the presentation surface to a polished standalone HTML tearsheet; ask only remaining material choices and do not treat HTML as a request for a standardized dashboard. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

## Purpose

Create a source-backed baseline profile for a public issuer so downstream Public Equity Investing workflows start from the same factual view. The default artifact is an issuer baseline by design, not a memo, model, pitch, or recommendation.

Use this before or inside comps, DCF, 3-statement, earnings, model update, long/short pitch, memo, meeting-prep, thesis tracker, risk/sizing, hedge, event, catalyst, equity-risk credit-signal, and deck/report workflows when a fast public profile is needed.

Use chat for quick issuer baselines. When the user explicitly requests HTML or selects HTML during intake, produce a compact polished standalone HTML tearsheet following `../../shared/html-artifact-standard.md`; let the issuer's business model and requested review lens determine the hierarchy. If the work expands into detailed thesis construction, scenarios, underwriting, or a full investment view, route the baseline into `initiating-coverage`, `memo-builder`, or the relevant owning workflow. Use `dashboard-builder` only when the user explicitly asks for a standardized dashboard, reusable dashboard template, or structured payload-driven render.

## Do Not Use

- Private company, sponsor-owned asset, private fund, LP/GP diligence target, vendor, customer, or commercial counterparty.
- Fund/asset-manager diligence profiles.
- Market maps, buyer lists, private-company sourcing screens, or diligence workplans.
- Full memos, valuation models, trade pitches, or investment recommendations.
- Do not compress a broader investment, earnings, comps, credit, or pitch request into a tearsheet; route to the owning full-analysis skill.

## Non-Negotiables

- Preserve source materials and user work.
- Prefer user-provided context/files, callable runtime apps/connectors when actually available, primary sources, user-provided provider exports, credible secondary sources, then labeled assumptions.
- Use `financial-source-of-truth` for source hierarchy, stale-data checks, citations, conflicts, and fact/assumption discipline.
- Use `financials-normalizer` or `excel-data-cleaner` first when source financials/tables are messy.
- Never invent missing facts, metrics, ratings, debt, valuation, ownership, customers, or KPIs.
- Label facts, calculations, estimates, management claims, user adjustments, assumptions, missing fields, and confidence.
- In a reader-facing artifact, translate internal evidence labels into plain investor language such as `Reported`, `Company-defined`, `Derived`, or `Not yet sourced`; retain exact evidence labels only in support data or when specifically requested.

## Workflow

1. **Classify profile.** Choose `public_company`, `equity_issuer_profile`, or `public_sector_peer`; identify downstream use case.
2. **Build source inventory.** Track `source_id`, source name/type, owner/provider, as-of date, retrieved-at date, period, location, freshness, and notes.
3. **Extract profile-critical facts.** Use only source-supported business, segment, geography, leadership, metrics, valuation, capital structure, KPI, recent event, risk, and evidence-gap fields relevant to the use case.
4. **Label evidence and confidence.** Use labels from `references/source-and-evidence.md` and confidence values `high`, `medium`, or `low`.
5. **Compose tearsheet.** For an HTML tearsheet, build a compact issuer baseline with an investor read, four or five decision-useful metrics, core business and earnings drivers, valuation context, concise catalysts/risks, material evidence gaps, source notes, and recommended next analytical route.
6. **Keep scope at baseline.** Do not allow a live event, long missing-data register, extensive diligence questions, or scenario work to overwhelm the issuer baseline. Escalate to an owning full-analysis workflow when that additional work becomes central.
7. **Run QC.** Confirm identity, periods, units, currency, sources, confidence, stale/conflicting data, derived-calculation support, and reader-facing legibility.

## Deterministic Helpers

```bash
python scripts/validate_tearsheet_json.py path/to/tearsheet.json
python scripts/build_tearsheet_markdown.py path/to/tearsheet.json output.md
```

The helpers validate/render structured inputs. They do not fetch data or replace source review. Raw JSON and generated Markdown are support or renderer-input artifacts unless the user explicitly asks for those formats.

For standardized dashboard handoffs only, use `references/DASHBOARD_PACK.md`. `company-tearsheet` owns the issuer baseline and source confidence; `dashboard-builder` owns the shared shell/rendering/QA. Build a `public_equity_investing_dashboard.v1` payload as an internal renderer input, and keep JSON/Markdown support files behind the HTML artifact unless explicitly requested.

## When To Invoke Support

Load `shared/support-layer-routing-contract.md` when support services are needed. Use `financial-source-of-truth` for source hierarchy, stale data, conflicts, and fact/assumption labels; use `financials-normalizer` or `excel-data-cleaner` before using messy financials, ownership tables, market/security data, or KPI exports. Support artifacts stay secondary to the tearsheet, dashboard/report, or downstream owning workflow.

## Output Contract

User-facing response:

1. Tearsheet created: entity, profile type, scope, sources, as-of date.
2. Key takeaways: 3-5 bullets with estimates/assumptions marked.
3. Metric table: decision-useful metrics with period, units, source, confidence.
4. Risks/gaps: stale data, conflicts, missing facts, evidence flags.
5. Recommended next step or downstream handoff.

For a standalone HTML tearsheet, keep the first-read structure compact:

1. Investor read and four or five high-signal metrics.
2. Earnings-driver table or compact driver cards.
3. Use the visible heading `Valuation Context` or `Trailing Valuation Snapshot` when only historical or derived multiples are supported. Do not include `Debate` in the heading unless forward estimates, peer comparisons, target-price evidence, or explicit market expectations are sourced.
4. Concise catalyst-and-risk matrix.
5. Material evidence gaps, source ledger, and next analytical route.

Do not expand the tearsheet into a full initiation report, long diligence-question set, scenario package, or recommendation merely because HTML space is available.

## HTML Guidance

When HTML is requested or selected, load `../../shared/html-artifact-standard.md` and apply these workflow-specific rules:

- Lead with the factual investor read and the core earnings-driver question; the issuer baseline and earnings drivers are the primary objects.
- Prefer four or five distinct metric tiles, one earnings-driver comparison object, one compact valuation-context object, and one catalyst/risk object over repeated dashboard panels.
- When a current transaction, rumor, regulatory item, or other live event is material but not the requested focus, feature it in the investor read and catalyst/risk section and identify missing primary evidence in the evidence-gaps block. Do not thread it through earnings drivers, valuation, and multiple summary panels unless it directly changes those analyses.
- Keep missing ownership, positioning, factor, or consensus fields visible through a compact evidence-gaps block; do not render a long table of unsourced fields unless those fields are the requested diligence focus.
- Render visible evidence posture in plain language rather than internal labels such as `fact_source_reported` or `missing_required_source`.
- Keep citations traceable but readable: do not fragment tickers, years, dates, numeric ranges, metric names, or product labels into separately linked tokens.
- Visually inspect local HTML via local headless-browser screenshots, not the in-app Browser plugin, and iterate on hierarchy, density, clipping, citation rendering, and whitespace before delivery.

## Reference Map

- `references/source-and-evidence.md`: source hierarchy, citations, stale-data, labels, conflicts.
- `references/profile-templates.md`: one-page and profile-specific templates.
- `references/metric-library.md`: metric categories, `sector-context-overlay` guidance, KPI guidance.
- `references/quality-checks.md`: profile QC checks.
- `references/integration-guide.md`: Public Equity Investing handoffs.

## Public Equity PM Judgment Layer

For substantial tearsheets, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

Use-case modes: `long_only_baseline`, `hf_baseline`, `sell_side_coverage_starter`, `etf_index_constituent_profile`, `public_diligence_baseline`.

Required PM judgment:
- Keep the tearsheet factual, but make the next analytical route obvious.
- Include investor-useful fields when available: market cap, enterprise value, float, ADV/liquidity, index membership, ETF/passive ownership and flow relevance, top holders, short interest, borrow/crowding, factor exposure, ownership concentration, governance, capital allocation, sell-side coverage, consensus setup, balance-sheet risk, and key operating KPIs.
- Always identify unavailable or stale ownership, positioning, borrow, liquidity, factor, and consensus fields with an as-of/source requirement rather than silently omitting them. In reader-facing HTML, consolidate non-central missing fields into a compact evidence-gaps block instead of displaying a long low-information register.
- Do not turn a tearsheet into a recommendation; route investment decisions to initiating coverage, memo-builder, long-short-pitch, or thesis-tracker.

Referenced files: 11

View saved version →

---
name: comps-valuation
description: Produce Public Equity Investing comparable-company valuation in report or workbook mode. Use for peer selection, multiple analysis, valuation read-throughs, implied prices, comps dashboards, Excel or Sheets comps, refreshable peer tables, model updates, and comps workbook QA. Do not use for DCF-only, credit-security, or generic market commentary requests.
---

# Comps Valuation

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `market_data_estimates`, and `portfolio_models_trackers`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Market Data & Estimates`
- `Company Filings & IR`
- `Portfolio Models & Trackers`

## Deliverable Intake And Judgment Standard

Before source gathering or analysis for a new substantive 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 downstream. For substantive investment judgment, apply `../../shared/final-deliverable-framework.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, the valuation posture and next underwriting step, and what evidence is missing. State what changes target, rating, sizing, hedge, trim, exit, or watchlist status only when the user requests portfolio action or provides the relevant holding, benchmark, mandate, and liquidity context.

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 or public-credit instrument underwriting, or distressed claim valuation.

## Mode Selection

Select the mode from the request and available context; do not ask merely because both modes exist.

- `report` mode: peer framing, multiple interpretation, implied valuation or price read-through, peer-set review, PM-facing comps argument, or a standalone HTML report or explicitly requested standardized dashboard without an editable model.
- `workbook` mode: Excel, Sheets, CSV/XLSX export, refreshable data, formulas, EV bridges, peer-table templates, workbook/model updates, structured sensitivities, or auditing an existing comps workbook.
- If an existing workbook is supplied and the requested output changes or validates it, choose `workbook`.
- Ask one focused question only when either mode is equally plausible and choosing incorrectly would materially change the user's intended artifact or decision workflow. Prefer proceeding with a stated inferred default when reliance is not impaired.

## Common Workflow

1. Establish security, issuer or target, audience mode, valuation date, fiscal basis, currency, and thesis question.
2. Source and label price, shares, EV bridge, reported/adjusted/consensus denominators, forward estimates, and peer rationale.
3. Build Core, Secondary, Excluded, and optional Watchlist peer roles.
4. Test metric comparability, stale data, outliers, valuation range, premium/discount logic, and PM action implications.
5. State what is priced in, what would change the thesis, and what evidence is missing.
6. Render or materialize the selected mode.

## Report Mode

Read `references/peer-selection.md`, `references/module-rules.md`, `references/source-and-staleness-rules.md`, `references/valuation-readthrough.md`, `references/output-templates.md`, and `references/p0-integrations.md` only when relevant. For a substantial reusable or HTML comps report, produce a polished standalone HTML comps report following `../../shared/html-artifact-standard.md`; let the valuation question and supported evidence determine the hierarchy. Use `dashboard-builder` only when the user explicitly asks for a standardized dashboard, reusable dashboard template, PM cockpit, or structured payload-driven render; in that case, load `references/DASHBOARD_PACK.md` and hand over a `public_equity_investing_dashboard.v1` payload.

For a standalone HTML comps report, keep the first read compact:

1. Valuation read: whether the premium or discount is supported and the key unresolved proof point.
2. Four or five high-signal metrics: current price, primary trading multiple, premium or discount to core peers, implied value range only when supportable, and the key operating proof point.
3. Peer-set rationale: Core, Secondary, and Excluded peers with concise inclusion or exclusion reasons.
4. Core trading-comps table.
5. Premium or discount bridge grounded in growth, margin, business-model fit, and data quality.
6. Valuation posture, material evidence gaps, and concise source ledger.

Express a valuation posture such as `premium partly supported`, `screening-only`, or `not sufficiently supported for a new-money decision`. Do not issue add, trim, hedge, sizing, or exit instructions unless the user requests portfolio action or supplies relevant holding and mandate context.

When HTML is delivered, keep citations traceable but readable: do not fragment tickers, prices, multiples, percentages, dates, numeric ranges, metric names, or peer labels into separately linked tokens. Visually inspect local HTML via local headless-browser screenshots, not the in-app Browser plugin, and iterate on hierarchy, density, clipping, citation rendering, and whitespace before delivery.

## Workbook Mode

Read `references/workbook/comps-framework.md`, `references/workbook/data-sourcing-and-connectors.md`, `references/workbook/model-workbook-spec.md`, `references/workbook/qa-and-pressure-testing.md`, `references/workbook/review-memo-template.md`, and `references/workbook/dashboard-map.md` only when relevant. Use `scripts/create_comps_template.py`, `scripts/materialize_screening_comps.py`, and `scripts/audit_comps_workbook.py` as appropriate. Preserve an existing workbook before rebuilding it.

## When To Invoke Support

Load `../../shared/support-layer-routing-contract.md` when source/data/QC support is needed. Use `financials-normalizer` for messy issuer or peer inputs, `model-audit-tieout` for standalone workbook audit, and `deck-report-qc` before circulation. Route credit-first conclusions to Credit Markets.

Referenced files: 19

View saved version →

---
name: dcf-model-builder
description: Use when building public-equity DCF valuation workbooks. Default to the banker formula workbook path for new model builds; use deterministic exports only for controlled support calculations or explicit lightweight runs. Do not use for standalone workbook audits; use model-audit-tieout.
---

# DCF Model Builder

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Company Filings & IR`
- `Market Data & Estimates`
- `Portfolio Models & Trackers`

## Deliverable Intake

Before source gathering or analysis for a new substantive 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.

Own DCF-specific valuation builds: FCFF/FCFE method choice, WACC or cost of equity, terminal value, EV-to-equity bridge, per-share value, valuation sensitivities, QA checks, and a formula-first XLSX workbook.

## Hard Contract

- Default model-build artifact level is `banker_formula_workbook`; use the formula workbook path for normal public-equity DCF build, refresh, valuation, and model-package requests.
- Formula mode is executed through `scripts/build_banker_formula_workbook.py` and must be labeled `banker_formula_workbook` only when its run log, workbook inspection, and `model_citations.json` prove the formula builder ran successfully.
- Deterministic scripts remain available for controlled computed values, smoke tests, or explicit lightweight support exports. They produce `output/model.xlsx`, `output/plan.json`, `output/run_log.json`, optional support note `output/support_note.md`, and `output/manifest.json`. Legacy `output/report.md` is written only with `--write-report-md`.
- Formula scripts produce `banker_formula_workbook.xlsx`, `banker_formula_workbook_run_log.json`, `model_citations.json`, and `manifest.json` in the selected output directory. The workbook is the hero deliverable; citation JSON, run logs, and manifests are support artifacts.
- Formula and deterministic workbooks must start with a `Cover` tab that functions as an investment landing page: issuer, current price versus implied value, valuation range, case outputs, DCF bridge, WACC/terminal assumptions, sensitivity drivers, source posture, warnings/hard failures, and workbook map.
- `run_log.json` and `manifest.json` are required reliability artifacts; hard failures force `not-decision-ready`.
- Never delete, overwrite, or mutate source data unless explicitly requested. Write new outputs under `output/` or a clearly named copy.
- Keep material inputs source-labeled: `reported`, `company_guidance`, `consensus`, `management_case`, `user_provided`, `connected_app`, `web_research`, `analyst_estimate`, `placeholder`, or `derived`.
- If placeholders, stale data, unsupported WACC, missing share count/net debt, or weak analyst estimates drive value, mark the output no higher than `screen-grade`.

## Routing

Use this skill when the deliverable is a DCF build, refresh, rerun, valuation sensitivity, reverse DCF, or DCF model package. Route away when the primary ask is workbook audit/debug (`model-audit-tieout`), source hierarchy (`financial-source-of-truth`), raw financial normalization (`financials-normalizer`), raw spreadsheet cleanup (`excel-data-cleaner`), expanded stress architecture (`scenario-sensitivity-generator`), trading comps (`comps-valuation`), or memo/deck polish.

For complex tasks, split the work into source-of-truth, accounting normalization, operating forecast, cost of capital, terminal value/ROIC, scenario valuation, and audit workstreams. If sub-agents are unavailable, emulate those workstreams explicitly before running the pipeline.

## When To Invoke Support

Load `shared/support-layer-routing-contract.md` when source/data/QC/style support is needed. Use `financial-source-of-truth` before relying on load-bearing market data, filings, guidance, consensus, share count, net debt, WACC, or terminal assumptions. Use `financials-normalizer` before plan creation when historical financials, KPI schedules, segment data, guidance, consensus/provider exports, share count, net debt, or capital allocation inputs are messy. Use `excel-data-cleaner` before importing malformed tables. Use `model-audit-tieout` for formula integrity, external links, recalc/cache posture, and final tie-out; use `deck-report-qc` only for circulation packs. Support artifacts stay secondary to the formula workbook or HTML report.

## Input Handling

- Preferred input is a `plan.json` matching the schema.
- No context: run `assets/plan_template.json` only as illustrative and label placeholders.
- Named company with no data: gather connected/public data when allowed; otherwise ask targeted questions or build a caveated screen-grade plan.
- Partial context: preserve user assumptions, fill only non-economic structure when obvious, and label gaps.
- Full plan: validate first; do not silently change conclusion-driving assumptions.
- When the investment question turns on an operating KPI such as bookings, GBV, take rate, volumes, users, units, or retention, load `references/industry-playbooks.md` and build from the sector-relevant driver where the workbook supports it. If formula mode cannot represent that driver schedule, disclose the proxy prominently on the Cover or Executive Summary and in Source Notes, and keep the model no higher than `screen-grade`; do not silently substitute a generic revenue CAGR.

## Required Workflow

1. Create or identify a valid `plan.json`.
2. Validate with `python3 scripts/validate_plan.py path/to/plan.json`.
3. Default path: execute `python3 scripts/build_banker_formula_workbook.py path/to/plan.json --output-dir output` and inspect `banker_formula_workbook_run_log.json`.
4. Use `python3 scripts/run_pipeline.py path/to/plan.json` only for controlled computed values, smoke tests, explicit lightweight support exports, or when formula mode fails and the fallback is clearly labeled `deterministic_export`.
5. Review the relevant run log for hard failures, warnings, checks, source basis, workbook inspection, and P0/model handoff.
6. Render and visually inspect the generated workbook before delivery. Confirm that template example data is absent from a named-company model, actual/estimate periods align across tabs, core outputs and sources are legible, and checks disclose any unsupported driver or roll-forward.
7. Deliver the workbook as the hero artifact and link the normalized plan, run log, manifest, citation ledger, and optional support note as audit files.

Smoke test:

```bash
python3 scripts/validate_plan.py assets/plan_template.json
python3 scripts/build_banker_formula_workbook.py assets/plan_template.json --output-dir /tmp/public-equity-investing-dcf-formula
python3 scripts/run_pipeline.py assets/plan_template.json
```

## Formula Mode Guardrail

Load `references/banker-formula-workbook-contract.md` before using formula mode. If the formula builder fails, the template is missing, required tabs/formulas/styles are not present, external links appear, or `model_citations.json` is absent, do not describe any fallback artifact as a banker formula workbook.

## Status Labels

Use exactly: `decision-grade`, `senior-review-ready`, `screen-grade`, `not-decision-ready`, `blocked`. Use `blocked` only before a run log exists; after execution, hard failures mean `not-decision-ready`.

## Deferred Reference Router

Load `references/reference-router.md` only when deeper schema, math, QA, integration, sector, or senior valuation judgment guidance is needed. The router preserves the detailed reference map without loading every reference during invocation.

## 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.

Referenced files: 27

View saved version →

---
name: deck-report-qc
description: Use when running first-pass QC on Public Equity Investing decks or reports. Do not use as external-circulation certification.
---

# Deck & Report QC

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Portfolio Models & Trackers`
- `Internal Research`
- `Company Filings & IR`
- `Market Data & Estimates`

## Deliverable Intake

When invoked as support for an owning workflow, inherit its resolved deliverable preferences and do not re-prompt. Only when this skill independently owns a new substantive standalone QC deliverable should it, before source gathering, analysis, or rendering, load `../../shared/deliverable-intake-policy.md` and perform its adaptive `request_user_input` preflight for materially unresolved preferences. For a substantive standalone QC review of an existing deck or report with supporting materials, resolve the presentation surface to a polished standalone HTML senior-review QC report unless the user requests another surface, a quick/no-file answer, or a standardized dashboard. In interactive runs, ask only remaining material questions such as depth, circulation stage, audience, or review focus; in non-interactive runs, default to the HTML QC report and `Full working analysis` while disclosing those assumptions outside the artifact.

## Purpose

Load `shared/equity-research-support-standard.md` and `shared/support-layer-routing-contract.md` before substantial source, data, QA, or style work.


Use this skill as the P0 first-pass quality-control gate for Public Equity Investing deliverables. The default job is to identify issues, prioritize fixes, and produce a senior-review QA pack. Do not imply a deliverable is externally circulable from the heuristic script alone, and do not rewrite, rebuild, or redesign the deliverable unless the user explicitly asks for remediation.

For a substantial standalone HTML QC report, load `../../shared/html-artifact-standard.md`. Let the evidence, circulation question, and highest-impact findings determine the hierarchy rather than forcing the review into a fixed dashboard module inventory.

## Embedded Support Routing

This is an embedded service under the owning workflow unless the user explicitly asks for standalone deck/report QC. Preserve the `owning_workflow` internally, such as `memo-builder`, `long-short-pitch`, `initiating-coverage`, `earnings-preview`, `earnings-deep-dive`, `economic-impact-report`, `equity-model-update`, `dcf-model-builder`, `three-statement-model-builder`, `comps-valuation`, `thesis-tracker`, `meeting-prep`, or `dashboard-builder`.

For substantial embedded work, preserve `decision_impact`, `readiness_effect`, `artifact_role`, and `hidden_unless_requested` in internal context or support artifacts. Do not print those internal field names in the owning workflow's user-facing artifact. Do not own the recommendation or rewrite the thesis; state in natural language how QC issues change valuation, EPS, target/rating support, benchmark weight, catalyst read, source support, model confidence, client trust, or circulation readiness. A polished standalone HTML senior-review QC report is the default human deliverable for substantive explicit QC-only work; CSV, JSON, Markdown, issue logs, extraction logs, payloads, and manifests remain secondary/support artifacts unless requested.

## Operating principles

1. Treat every number, unit, footnote, chart, and conclusion as something that must tie to an identified source or model output.
2. Separate deterministic findings from judgment calls. Mark uncertain items as `needs_review` rather than overclaiming.
3. Prioritize issues by decision impact. A mismatched EBITDA value, leverage multiple, share price, EPS, revenue/KPI, price target, rating, benchmark weight, catalyst, market-data, or valuation range is more important than minor formatting polish.
4. Preserve the original artifact. QC should create an issue log and suggested fixes first; edit only when asked.
5. Apply `financial-source-of-truth` standards for source hierarchy, stale-data checks, citation format, source conflicts, and fact/assumption labels.
6. Route model-level issues to `model-audit-tieout` and data-shaping issues to `excel-data-cleaner` instead of trying to solve them inside this skill.

## Workflow

### 1. Classify the deliverable

Identify the file type and purpose:
- investor presentation, research deck, senior-style research deck, valuation deck, sell-side initiation, PM pitch deck, ETF/index diligence note, or circulation draft
- public-equity IC memo, investment memo, earnings note, macro note, research report, client note, or tearsheet
- model output deck or report linked to DCF, comps, three-statement, equity-model-update, event-driven, ETF/index, or macro analysis
- mixed pack with PPTX/PDF/DOCX/XLSX support files

If the user provides multiple files, identify the controlling artifact and the source artifacts. Example: deck is controlling output; model, evidence ledger, filing, release, transcript, and source tables are supporting materials.

### 2. Extract first-pass text, numbers, and sources

For PPTX, DOCX, XLSX, CSV, TXT, or markdown files, run the bundled first-pass scan script when available:

```bash
python scripts/inspect_deck_report.py <file1> <file2> --outdir qc_out
```

Use the script output as a first-pass map only. It is not a substitute for visual review, chart inspection, model tie-out, source-of-truth review, or PDF rendering.

For PDFs, screenshots, image-heavy slides, or scanned materials, use PDF/rendering tools to inspect pages visually before finalizing QC. If charts are embedded as images, state that the underlying chart data could not be extracted unless the model/source file is provided.

For each `critical` or `high` finding that relies on visible content, render and inspect the cited source pages or slides. Keep a plain-language record of what pages, workbook tabs, and support files were inspected, and of what could not be independently verified.

### 3. Build the QC map

Create or infer:
- page/slide/section list
- main title and thesis by page
- all repeated metrics and key claims
- source footnotes and citation coverage
- chart titles, axes, units, legends, and cited data source
- model-output tables and valuation/returns ranges
- section-level narrative conclusions

Consult `references/qc-playbook.md` for QC categories and `references/extraction-and-tieout.md` for extraction and tie-out guidance.

### 4. Run issue checks

Check at minimum:
- repeated numbers: same metric, company, period, and unit should match unless there is a disclosed reason
- units: millions/billions, dollars/local currency, percentages/bps, turns, multiples, per-share, nominal/real, annualized/LTM/NTM should be explicit and consistent
- source footnotes: each data-heavy page should identify source, as-of date, period, and whether data is company-reported, regulator-filed, market/vendor, broker/consensus, management-provided, model-derived, or internal estimate
- charts: chart title, axis units, legends, series labels, chart numbers, and narrative takeaway should agree
- narrative consistency: executive summary, page titles, subtitles, bullets, charts, and conclusion should not contradict each other
- formatting: titles, subtitles, page numbers, fonts, alignment, table formatting, footnote style, decimal precision, capitalization, and repeated labels should be consistent
- caveats: preliminary, unaudited, company-provided, non-filed, promotional, model-derived, and assumption-led items should be labeled
- compliance hygiene: do not add legal disclaimers unless requested, but flag missing caveats/disclosures where the analysis relies on uncertain or restricted inputs

Consult `references/issue-taxonomy.md` for severity and issue-type definitions.

### 5. Assign evidence confidence

Classify each consequential issue using one of these reader-facing confidence descriptions:
- `confirmed internal mismatch`: proved by contradictory values, labels, calculations, or statements within the supplied artifacts
- `externally verified error`: proved against a controlling primary or trusted dated external source
- `needs review`: suspected issue or unresolved conflict that requires a source, model, data export, or user confirmation

Do not state that an identifier, market fact, source claim, or company fact is confirmed wrong merely because supplied materials conflict or appear unlikely. Without a controlling source, state the internal conflict and route it for confirmation.

### 6. Decide the review posture

Assign one of these postures:
- `first-pass-clear`: no heuristic blockers were identified, but visual/source/model review may still be required
- `senior-review-ready`: mostly ready, with limited open questions or judgement calls
- `needs-targeted-fixes`: specific corrections are required before circulation
- `not-circulable`: material numerical, source, chart, or narrative issues remain
- `blocked`: necessary source/model files are missing

Medium source gaps, repeated-number mismatches, and unit/period ambiguity usually mean `needs-targeted-fixes`, not `senior-review-ready`.

### 7. Produce the QC output

Default output should be a senior-review QC readout. Use chat for narrow reviews. For substantial standalone QC-only work, produce a polished standalone HTML senior-review QC report following `../../shared/html-artifact-standard.md`. When the script is used, the reader-facing artifact should be `public_equity_investing_deck_qc_report.html`; CSV, JSON, manifests, payloads, and support notes are audit/import support unless the user asks for them.

Use `dashboard-builder`, `references/DASHBOARD_PACK.md`, and `references/dashboard-map.md` only when the user explicitly asks for a standardized dashboard, reusable dashboard template, issue cockpit, remediation tracker, or structured payload-driven render. On that optional path, `deck-report-qc` owns issue identification, severity, tie-out judgment, circulation posture, and remediation sequence; `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 support files behind the HTML dashboard unless explicitly requested.

The QC readout should include:
1. Executive QC verdict
2. Circulation posture
3. Review scope and evidence limitations: what was inspected, tied out, externally verified, and not independently verified
4. Decision-critical tie-out or recommendation support, when applicable
5. Top issues by severity and remediation sequence
6. Issue log table with confidence descriptions
7. Repeated metric / number tie-out table
8. Source and footnote coverage table
9. Chart and narrative tie-out findings
10. Formatting/presentation polish findings
11. Open questions / missing support files

Use `references/output-templates.md` for default templates.

For standalone HTML, keep the first screen focused on the verdict, circulation posture, evidence scope, and the few findings that change senior reliance. When a valuation, target-price, recommendation, rating, benchmark-weight, or other decision-critical tie-out exists, place the `Decision-Critical Tie-Out` section before `Top Issues`, `Must Fix Before Circulation`, or the full issue log; do not make the reader pass through the broader findings register before seeing the central control failure. Place comprehensive registers, source-coverage tables, and presentation-polish findings lower in the report.

Visually inspect local HTML via local headless-browser screenshots, not the in-app Browser plugin, at both desktop and narrow/mobile widths. Tables may scroll horizontally inside a clearly bounded table wrapper on narrow screens, but they must not widen the entire page. In mobile QA, verify that the document viewport itself has no horizontal overflow, for example `document.documentElement.scrollWidth <= document.documentElement.clientWidth`; use constrained grid/section children and `max-width: 100%; overflow-x: auto` table wrappers where needed. Iterate on hierarchy, table density, clipping, contrast, and whitespace before delivery.

When `scripts/inspect_deck_report.py` was used before a substantive standalone HTML review, write a small JSON review record identifying `completed_reviews` and remaining `missing_inputs`, then finalize the existing output path after HTML visual inspection:

```bash
python scripts/inspect_deck_report.py --finalize \
  --outdir <final-output-dir> \
  --scan-dir <first-pass-output-dir> \
  --primary-report <final-output-dir>/public_equity_investing_deck_qc_report.html \
  --review-record <final-output-dir>/qc_review_record.json
```

Finalization must make the polished HTML the sole primary human deliverable, reconcile manifest status to the work actually performed, and remove the provisional dashboard contract for ordinary standalone HTML reviews. Add `--keep-dashboard-contract` only when the user explicitly selected the standardized-dashboard path.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: source and number tie-out, chart/visual review, narrative consistency, formatting/circulation posture, and issue log. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.

When embedded in a broader workflow, "lead" means lead for QC only; the owning workflow remains the investment-artifact owner.


## Severity rules

Use these severities:
- `critical`: could change investment decision, valuation, rating, price target, sizing, market read, or client trust
- `high`: material inconsistency or missing support that must be fixed before circulation
- `medium`: localized inconsistency, unclear caveat, formatting issue, or missing source detail that should be fixed
- `low`: polish item that does not affect substance
- `needs_review`: possible issue that requires visual, model, source, or user confirmation

Never hide uncertainty. If a number may be wrong but cannot be proven wrong from available files, label it `needs_review` and ask for the model/source support.

## P0 skill routing

Use `references/p0-integrations.md` when deciding whether an issue belongs in this skill or should be routed to another P0 skill.

Common routes:
- source hierarchy, stale data, citation standard, source conflict, fact/assumption labeling -> `financial-source-of-truth`
- workbook formula, model logic, sensitivity, scenario, source tie-out -> `model-audit-tieout`
- messy tabular data, duplicated rows, bad date/number formats -> `excel-data-cleaner`
- valuation model construction or repair -> `dcf-model-builder`, `comps-valuation`, or `three-statement-model-builder`
- public issuer, equity event, or thesis support -> `event-driven-analyzer`, `earnings-preview`, `earnings-deep-dive`, `equity-model-update`, or `long-short-pitch`; credit-first packs, public-credit memos, bond/loan/CDS decks, covenant/recovery packs, and debt-security materials route to Credit Markets
- final IC synthesis -> `memo-builder`

## Final checks before responding

Before final output, verify:
- every critical/high issue has location, evidence, why it matters, and suggested fix
- every consequential issue identifies whether it is a `confirmed internal mismatch`, an `externally verified error`, or `needs review`
- every repeated metric table distinguishes exact mismatch from possible period/unit mismatch
- source gaps are not presented as factual errors unless a controlling source proves the issue
- formatting findings are separated from investment-substance findings
- the final posture matches the severity of remaining issues
- the response does not imply the deck/report is fully verified if charts, screenshots, PDFs, or source models were not inspectable
- the HTML report and any support manifest or review note agree on what was visually inspected, tied out, and still unverified
- standalone HTML keeps any decision-critical tie-out above the broader issue register and does not introduce page-level horizontal overflow at narrow/mobile widths

Referenced files: 10

View saved version →

---
name: earnings-deep-dive
description: Use when analyzing public-company earnings after results, guidance, transcript, or call commentary. Do not use for pre-print previews.
---

# Earnings Deep Dive

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Earnings Transcripts & Events`
- `Company Filings & IR`
- `Market Data & Estimates`
- `Portfolio Models & Trackers`
- `Internal Research`

## Internal Support

When this workflow needs rendering, evidence/data preparation, style, or sector context, route support through the visible `public-equity-investing` router and its bundled internal playbooks. Route workbook or model QA through the visible `model-audit-tieout` workflow.

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For an explicit `deep dive`, `full report`, or reusable/source-heavy post-print package, resolve presentation to a polished standalone HTML post-earnings report unless the user requests another format, a quick/no-file answer, or workbook/model-update output. In interactive runs, ask only remaining material questions such as depth, audience/use, or focus; narrower post-result questions continue to use normal intake. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

Produce a decision-grade, audit-ready post-print package after results are available.

Default to the full post-print package. Chat can be the surface for narrow or explicitly no-file asks, but an explicit deep dive, full report, or source-heavy reusable post-print package should be a polished standalone HTML post-earnings report following `../../shared/html-artifact-standard.md`. Use `dashboard-builder` only for the optional standardized-dashboard route below. Use deterministic file mode only when the user supplies `plan.json`, normalized CSVs, model-update inputs, or explicitly asks for files.

## Route

- `full deep dive`: default analytical route for post-earnings deep dives, earnings-print analysis, and investor-facing post-print questions. An explicit deep dive, full report, or reusable/source-heavy package defaults to polished standalone HTML.
- `one-page tear sheet`: use only when the user explicitly asks for a summary, one-pager, quick read, brief, or TL;DR.
- `audit-ready model update`: use only when the user supplies or references a model/workbook, driver registry, output registry, normalized CSVs, model-update inputs, or explicit data to update a model.
- `quote and debate map`: standalone only when the user asks only for transcript quotes/debate; otherwise include it inside the full deep dive.
- `standardized dashboard`: only when the user explicitly asks for a standardized dashboard, reusable dashboard template, PM cockpit, tabbed dashboard, or structured payload-driven render, keep this skill as the analysis owner and hand the resulting `public_equity_investing_dashboard.v1` payload to `dashboard-builder`. Use `references/DASHBOARD_PACK.md` for module mapping.
- `deterministic file mode`: validate inputs, run shipped scripts, fail QA on unresolved user-facing placeholders, and disclose packet versus workbook-apply path.

Load `references/REFERENCE_ROUTER.md` first, then only the route-specific reference needed for the selected artifact.

## Non-Negotiables

- Never invent numbers, quotes, guidance, definitions, accounting facts, estimate timestamps, source tags, or catalyst dates.
- Use official filings/releases before decks and transcripts; transcripts support narrative and call-only guidance, not primary GAAP numbers.
- Every reported number and every quote needs a source tag; analyst-derived numbers need formula/assumption and confidence.
- Full deep dives must include transcript evidence and a debate-map treatment when transcript evidence is available. If no transcript is available, show a concise visible limitation labelled `transcript not provided` or `transcript source not found` and list the exact missing artifact; do not render an empty Q&A table.
- For transcript Q&A, capture questioner name, firm if available, answering executive, topic, section, source tag, why it matters, bull/bear implication, and falsifier/next check.
- Keep GAAP/non-GAAP, reported/constant-currency, company-guided/analyst-derived, units/scale, and unavailable-data labels explicit.
- Always run an EPS quality screen: ask whether headline EPS could misstate recurring operating performance. Include a full EPS quality / ex-gain bridge when GAAP EPS surprise is distorted by below-the-line, tax, mark-to-market, equity-investment, FX, restructuring, litigation, asset-sale, impairment, share-count, or other non-recurring items; otherwise state that no material EPS-quality trigger was identified from available sources.
- Full deep dives must include quarterly key metrics and growth trajectory using the issuer's actual business drivers, not only generic revenue/EPS/margin. Use sector-context-overlay when the company-specific KPI set is not obvious.
- For HTML reports or standardized dashboard handoffs, include earnings visualizations when source-backed data exists: quarterly revenue, gross profit, net income, and the best source-backed profitability margin history; estimated EPS versus actual EPS for the past five quarters on a consistent basis; and equity-price history annotated with material market events. Omit any chart whose required series is missing, stale, or not comparable, and surface that gap clearly.
- Treat margin selection as an analytical decision, not a template default. Default to net margin only when net income is a fair recurring-profitability proxy. Prefer operating margin when net income is distorted by below-the-line, tax, mark-to-market, equity-investment, FX, restructuring, litigation, asset-sale, impairment, or other non-recurring items. Prefer adjusted operating margin, EBITDA margin, contribution margin, or FCF margin when that is the issuer's source-backed investor KPI. For dashboard payloads, set `financial_trend_chart.data.margin_metric`, `margin_label`, and `margin_rationale` whenever the line is not plain net margin.
- Rank highlight/snapshot metrics by investor salience. A growth rate, acceleration, surprise %, guide delta, backlog growth, margin inflection, or clean/normalized metric should be the tile value when it better explains the stock-moving point than the absolute reported amount; put the absolute amount in the detail.
- Full deep dives must include read-throughs when the print, filing, transcript, or management interviews mention customers, suppliers, peers, competitors, platforms, channels, commodities, regions, or adjacent industries.
- Full deep dives must include major news coverage and market events when recent or upcoming events change the interpretation of the print, guidance, estimate revisions, multiple, risk, positioning, or read-throughs. Scan the last quarter, last twelve months, and forward-looking anticipated events; cite every event and label uncertain windows.
- Capture catalysts learned from the release, filing, transcript, Q&A, and management interviews. Separate dated catalysts from inferred monitoring windows.
- Use precise absence labels: `not guided`, `not disclosed`, `not provided`, `source not provided`, or `MISSING: <dependency>` only where appropriate.
- Generated Markdown support notes must not contain unresolved bracket tokens, `TODO`, or authoring placeholders.

## Chat Contract

Default sections for full deep dive: setup/source posture, dense executive summary, PM bottom line, granular beat/miss or guide-versus-bar, EPS quality screen, quarterly key metrics, growth trajectory, guidance delta/deep dive, what changed, revision/stock setup, load-bearing drivers, transcript quote/Q&A and debate map, read-throughs, major news and market events, model/thesis impact, catalysts/watch list/falsifiers, source limitations, and open questions. For investor-facing prompts add thesis change, likely estimate revision, stock/valuation skew, and next catalyst.

Use the evidence pack that supports the selected artifact without shrinking the user-facing analysis:

- Full deep dive: release/filing, deck/prepared remarks, transcript, estimates, and prior-quarter/prior-guide sources where available.
- Explicit summary or one-page tear sheet: release or 8-K, deck if available, estimate source, and transcript only for high-signal quotes.
- Audit-ready model update: release/filing/deck, estimate set, prior guide, and model/workbook or normalized driver inputs supplied or referenced by the user.
- Standalone quote/debate: transcript plus release/deck to cross-check numeric claims.

## HTML Guidance

For a substantive HTML deep dive, load `../../shared/html-artifact-standard.md` and let the company-specific investment debate determine the layout.

- Title the artifact as a post-earnings deep dive identifying the company, ticker, and reported period.
- Start with a direct verdict answering the investor's question, 4-6 high-signal metric tiles, one compact decision box, and a quality-of-print bridge separating headline results from recurring operating evidence.
- Use only distinct decision-relevant tiles. Prefer 4-5 tiles when additional metrics repeat the same analytical point; combine related buyback, leverage, interest-expense, or cash-flow signals into one capital-allocation-quality tile when that improves readability.
- Put supporting analysis below that first read: beat/miss and guidance, EPS quality, company-specific growth drivers, capital allocation, valuation/stock setup, catalysts, falsifiers, source limitations, and evidence ledger as relevant.
- Give each first-read element a distinct job: the verdict answers the investment question and explains why; the decision box states thesis change, estimate direction, valuation/stock skew, action discipline, and next proof point; metric tiles show evidence rather than restating the verdict; the quality-of-print bridge reconciles headline results to recurring equity value. Do not repeat the same conclusion across these elements.
- Describe evidence posture in reader-facing terms by naming sources obtained and important confirmations still missing, for example `Company release reviewed; filing and transcript confirmation pending`. Avoid internal-sounding quality labels such as `research-grade` in the visible artifact.
- Include transcript Q&A, read-throughs, market-events tables, scenario sections, and charts only when substantive and evidence-supported. A missing transcript should be a concise limitation callout, not an empty table.
- Do not render blank scenario cards, placeholder modules, or visible source cells marked unsourced when the claim has a cited source.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: release and filing numbers, transcript/Q&A, estimates and guidance, model/thesis impact, and source QA. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Deterministic Contract

Use only when requested or file/model inputs are supplied:

- `scripts/validate_plan.py`
- `scripts/validate_normalized_inputs.py`
- `scripts/run_plan.py`
- `scripts/apply_model_updates.py`
- `scripts/model_diff.py`
- `scripts/verify_tearsheet.py`

If workbook apply fails or is unsafe, deliver a driver update packet and explain the limitation. The bundled plan defaults to packet/dry-run mode and writes outside the skill tree.

## Standardized Dashboard Handoff

Use `dashboard-builder` only when the user explicitly selects the standardized dashboard, reusable dashboard-template, or structured payload-driven rendering path. This skill still owns the analysis and maps it into `references/DASHBOARD_PACK.md`; prefer `layout: "single_page"` with sticky contents for full PM diligence dashboards unless the user explicitly asks for tabs. Ordinary standalone HTML deep dives use the flexible HTML guidance above rather than a fixed module inventory.

## Public Equity PM Judgment Layer

For substantial post-print work, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

Default PM question: did the quarter change the thesis, estimates, valuation support, or sizing?

Required PM judgment:
- Lead with thesis change, estimate revision direction, valuation support, and position action.
- Bridge headline versus clean result, guide delta, quality of beat/miss, transcript evidence, management credibility, and next falsifier.
- Separate reported facts, management claims, consensus, market data, model output, assumptions, and PM judgment.
- For sell-side mode, add rating/target implications and risk-to-rating. For hedge fund mode, add add/trim/cover triggers.

Referenced files: 41

View saved version →

---
name: earnings-preview
description: Use when preparing full pre-earnings preview reports with executive summary, expectation bar, guidance credibility, KPI dashboard, scenarios, and call questions. Do not use after results or for short summaries unless the user explicitly asks for a summary/short version.
---

# Earnings Preview

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Earnings Transcripts & Events`
- `Company Filings & IR`
- `Market Data & Estimates`
- `Internal Research`

## Internal Support

When this workflow needs rendering, evidence/data preparation, style, or sector context, route support through the visible `public-equity-investing` router and its bundled internal playbooks. Route workbook or model QA through the visible `model-audit-tieout` workflow.

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For an explicit pre-earnings preview, full preview report, or reusable/source-heavy pre-print package, the default resolves the presentation surface to a polished standalone HTML pre-earnings report unless the user requests an alternate surface, a quick/no-file answer, or workbook/model output. In interactive runs, ask only remaining material choices such as depth, audience/use, or focus; in non-interactive runs, default to the HTML pre-earnings report and `Full working analysis` while disclosing those assumptions outside the artifact. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

Produce a full, decision-grade pre-print report by default: executive summary first, then what the market expects, what can move the stock, what must be answered on the call, and what evidence is missing.

## Route

- `full preview report`: default route for any pre-earnings preview request. For an explicit pre-earnings preview, full preview report, or reusable/source-heavy pre-print package, produce a polished standalone HTML pre-earnings report following `../../shared/html-artifact-standard.md`; let the named investor question determine the hierarchy. Always surface the expectation bar, stock-reaction drivers, key evidence, call watch items, source posture, and missing evidence. Add KPI trajectories, guidance credibility, peer/sector read-throughs, macro context, market events, reaction/options context, bull/base/bear cases, and extended call questions only when relevant and source-supported.
- `explicit short summary`: use only when the user explicitly asks for `summary`, `short`, `quick read`, `one-pager`, `top things to watch`, or similar compression. Do not maintain this as a separate tear-sheet artifact; pare back the full preview report while preserving freeze time, source posture, key bar numbers, top debates, call questions, and missing evidence.
- `standardized dashboard`: use only when the user explicitly asks for a standardized dashboard, reusable dashboard template, PM cockpit, tabbed dashboard, or structured payload-driven render. Keep this skill as the analysis owner and hand the resulting `public_equity_investing_dashboard.v1` payload to `dashboard-builder`. Use `references/DASHBOARD_PACK.md` for module mapping.
- `deterministic export pack`: only when requested or plan-driven; validate local inputs, run packaged scripts, and write support artifacts such as `preview_note.md`, `exports.xlsx`, `exports/*.csv`, `qa_report.*`, and `run_manifest.json`. The workbook or rendered dashboard/report is the hero artifact; CSV/JSON/Markdown sidecars are support/audit files unless explicitly requested.

Load `references/REFERENCE_ROUTER.md` first, then only the smallest reference needed for the chosen route.

## Non-Negotiables

- State freeze time and source timestamps for consensus, whisper, options, price/reaction, and other time-sensitive inputs.
- Never fabricate numbers, dates, guidance, option data, peer read-throughs, or whisper color.
- Separate company/SEC/IR facts, consensus, whisper, analyst inference, user assumptions, and web fallback.
- Keep GAAP/non-GAAP labels, units, scale, period mapping, and KPI definitions explicit.
- Identify EPS-quality landmines before the print: tax rate, share count, equity-investment marks, FX, asset sales, impairments, restructuring, litigation, non-operating income/expense, and any mismatch between GAAP EPS, adjusted EPS, and consensus basis.
- Include the last reported baseline and the consensus/guide bar where sourced. Include quarterly key metrics and growth trajectory when they sharpen the investor question or the stock-reaction setup rather than as mandatory display inventory.
- For dashboard handoffs, include the earnings visualization pack only when source-backed data exists: quarterly revenue, gross profit, net income, and the best source-backed profitability margin history; estimated EPS versus actual EPS for the past five quarters; and equity-price history annotated with material market events. Omit any chart whose required series is missing, stale, or not comparable, and surface that gap in `missing_evidence`.
- Treat the margin line in financial trend charts as part of the pre-print risk setup. Default to net margin only when net income is a fair recurring-profitability proxy. Prefer operating margin or another issuer-specific source-backed margin when net income has been distorted by tax, equity-investment marks, FX, asset sales, impairments, restructuring, litigation, or other non-operating items. State the selected `margin_metric`, `margin_label`, and `margin_rationale` in dashboard payloads when using a line other than net margin.
- Rank dashboard highlights by investor salience rather than mechanical size. If a growth rate, acceleration, surprise %, guide delta, backlog, or normalized metric is what matters for the stock, use that as the highlighted value and put the absolute value in the supporting detail.
- Include major news coverage and market events when they can affect the earnings setup, guide credibility, estimate bar, multiple, positioning, or call questions. Scan the last quarter, the last twelve months, and forward-looking anticipated events; cite every event and label uncertain windows.
- Use primary company/SEC/IR and connected sources before general web; label fallback sources.
- Do not imply MNPI or confidential whisper data; weak whisper support becomes qualitative setup language.
- Without sourced implied move, relevant positioning/context, and adequate consensus or whisper evidence for the stated question, provide an earnings setup and reaction framework rather than a trade-ready position instruction. Use `Wait for proof`, `Monitor`, or similarly evidence-calibrated language where appropriate.
- Treat an options-implied move as an earnings reaction bar only when the contract tenor reasonably isolates the earnings event. If the available expiry includes substantial pre-event trading time or another material catalyst window, label the metric as `expiry-tenor volatility context`, explain the limitation, and do not feature it as a first-read earnings-move tile unless the limitation is immediately prominent.
- Do not create optional exports or support files unless requested or plan-driven. The workflow-resolved standalone HTML pre-earnings report is the planned hero artifact for an explicit full preview request.
- Do not shorten the default preview just because some inputs are missing; keep full analysis of the investment question and label unavailable optional modules or inputs explicitly.

## Workflow

1. Classify route. Default to `full preview report` unless the user explicitly asks for a summary/short format.
2. Anchor the preview quarter; map `t`, `t-1`, `t-4`, and `t-8`.
3. Freeze sources/timestamps and normalize units, GAAP/non-GAAP basis, KPI definitions, and source posture.
4. Identify 3-6 stock-moving KPIs and build the expectation bar: consensus, guide, whisper if sourced, prior setup, key-metric baseline, growth trajectory, EPS-quality watch items, and base framing.
5. Add guidance credibility, peer read-throughs, reaction/options, macro/sector context, and major news/market events when relevant and sourced. Separate company-specific events from peer, macro, regulatory, legal, FX/rates, commodity, industry, and upcoming catalyst events.
6. Build supportable bull/base/bear framing and write only decision-relevant call questions with listen-fors and falsifiers. Convert material news/event items into call questions when they create a contradiction or open diligence item.
7. Run QA for executive-summary coverage, freeze time, period consistency, source labels, units/scale, chart/display unit agreement, readable citation placement, cited event claims, missing evidence, and unresolved placeholders.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: source and consensus freeze, KPI/guide bar, peer/macro/reaction context, scenarios, call questions, and QA. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Deterministic Contract

Scripts are local materializers; they do not fetch data or replace analyst judgment.

- Required inputs: `company_master.csv`, `fiscal_period_index.csv`, `reported_financials.csv`, `kpi_timeseries.csv`, `consensus_estimates.csv`.
- Required for full scripted pack: `guidance_history.csv` and canonical event file `event_calendar.csv` can be empty but must exist with headers.
- Optional inputs: `whisper_estimates.csv`, `price_returns.csv`, `options_snapshot.csv`, `qual_notes.csv`, `scenario_assumptions.csv`.
- Schema source: `references/SCHEMAS.md` plus `assets/plan_schema.json`.
- Generated Markdown support notes must not contain unresolved bracket tokens, `TODO`, or unfinished placeholders.
- `exports.xlsx` starts with `Cover`, a dashboard sheet summarizing company/ticker, preview period, freeze time, workbook mode, warnings, consensus bar, bull/base/bear revenue and EPS, KPI dashboard row counts, call watch item, input file count, and workbook map.

## Handoffs

Use `financial-source-of-truth` for evidence conflicts, `financials-normalizer` for messy tables, `scenario-sensitivity-generator` for deeper cases, `dashboard-builder` for responsive pre-earnings dashboard rendering, `earnings-deep-dive` after the print, `equity-model-update` for model refreshes, `long-short-pitch` for trade expression, and `memo-builder` for formal memos.

## HTML Guidance

For a substantive HTML full preview report, load `../../shared/html-artifact-standard.md` and apply these preview-specific requirements:

- Lead with the expectation bar and the stock-reaction debate. If the user names a specific issue, such as AI memory demand, put that issue and its reaction drivers ahead of broad KPI archives or general diligence sections.
- Use four to six first-read tiles only when each has a distinct decision job, such as event timing, guide/consensus bar, operating proof point, market setup, an event-isolating implied move when available, or most important evidence gap.
- Make visible what is known, what the market likely requires, what could surprise, and what evidence is missing before taking incremental event risk.
- Include detailed KPI dashboards, peer/macro context, historical reactions, options/implied-move analysis, scenario maps, and extended call-question lists only when relevant and source-backed. Do not force a fixed dashboard module inventory into a flexible report.
- Match chart axes and labels to the units stated in the adjacent headings or tables. Omit a misleading chart rather than mixing units or scales.
- Keep citations traceable but readable; do not fragment dates, times, ticker symbols, product names, or product specifications into separately linked characters or tokens.
- Visually inspect the HTML according to the shared artifact standard before delivery and iterate on hierarchy, legibility, clipping, crowding, citation noise, and whether the requested investment question is immediately visible.

## Public Equity PM Judgment Layer

For substantial previews, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

Default PM question: is the bar beatable, does it matter for the stock, and what would change sizing into or after the print?

Required PM judgment:
- State the expectation bar, consensus dispersion, guidance setup, implied move or reaction risk when available, and the estimate-revision path.
- Separate company fundamentals from stock setup: what is priced in, what the market may be ignoring, and what would make a bad print buyable or a good print fadeable.
- Include call-question falsifiers, listen-for items, and position actions: `add`, `press`, `hold`, `trim`, `exit`, `hedge`, `watchlist`, or `wait for proof`.
- For ETF/index diligence, include constituent weight, passive ownership/flow relevance, liquidity, benchmark exposure, and rebalance/event risk when relevant.

Referenced files: 28

View saved version →

---
name: economic-impact-report
description: Use when translating a specific event, policy change, macro shock, or industry development into public-equity issuer, sector, earnings, valuation, positioning, and portfolio implications. Do not use for standalone macro strategy, rates, FX, credit, futures, or generic market commentary.
---

# Economic Impact Report

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Market Data & Estimates`
- `Company Filings & IR`
- `Internal Research`

## Internal Support

When this workflow needs rendering, evidence/data preparation, style, or sector context, route support through the visible `public-equity-investing` router and its bundled internal playbooks. Route workbook or model QA through the visible `model-audit-tieout` workflow.

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For a substantive reusable economic-impact report or explicit HTML public-equity shock analysis, the default resolves the presentation surface to a polished standalone HTML economic-impact report unless the user requests an alternate surface, a quick/no-file answer, or a standardized dashboard. In interactive runs, ask only remaining material choices such as depth, audience/use, or focus; in non-interactive runs, default to the HTML economic-impact report and `Full working analysis` while disclosing those assumptions outside the artifact. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

## Goal

Produce a decision-grade public-equity economic impact report. This is not a news summary and not a generic cross-asset macro note; it should tell a senior public-equity investor what changed, why it matters for listed equities, what reprices first, what is still uncertain, and which issuers, sectors, estimates, valuation debates, positioning risks, and portfolio actions matter most.

Default to a full decision-grade economic impact report unless the user explicitly asks for a summary, quick read, one-pager, brief, TL;DR, or another compressed format. For a substantial reusable report or explicit HTML public-equity shock analysis, produce a polished standalone HTML economic-impact report following `../../shared/html-artifact-standard.md`; chat-only is appropriate for narrow or explicitly quick reads.

## Use When

Use this skill when the user asks for:

- economic or market impact of a specific event
- first-, second-, third-, or fourth-order implications
- transmission map from shock to consequence
- winners and losers with mechanisms
- public-equity implications from rates, FX, options, futures, commodities, credit, policy, geopolitics, labor, supply-chain, demand, or regulatory shocks
- scenario analysis, catalysts, monitoring signals, or "what would change the view"
- a senior public-equity investor memo on policy, macro, regulatory, geopolitical, supply, credit-signal, commodity, industry, or earnings shocks

Do not use for:

- pure article summaries with no impact question
- generic macro explainers with no event or catalyst
- narrow workflows that need another local skill first, such as DCF, earnings deep dive, catalyst calendar, or spreadsheet cleanup
- one-line market color where a causal map is overkill
- standalone macro, rates, FX, futures, options, commodities, or credit strategy without a listed-equity issuer/sector/portfolio decision; route out
- standalone macro strategy, rates strategy, FX strategy, futures curve work, options-volatility trade construction, credit-security relative value, or debt-security selection; route those to the appropriate plugin, with Credit Markets owning credit instruments

## Non-Negotiables

- Bottom line first.
- Separate fact, inference, assumption, and scenario.
- Separate direct effects from higher-order effects.
- Separate immediate listed-equity implications, medium-term earnings/estimate implications, valuation/multiple implications, positioning/flow implications, and structural consequences.
- Every major claim must tie to a transmission channel.
- Every named issuer, sector, country, commodity, rate, currency, credit signal, or asset-class input must connect to a public-equity mechanism.
- Quantify whenever a reasonable range is possible.
- Distinguish what is genuinely new from stale reporting or prior expectations.
- Distinguish what is likely priced from what may still be mispriced.
- Address the strongest counterargument.
- End with scenarios, monitoring signals, falsifiers, and the public-equity action posture: `add`, `press`, `hold`, `trim`, `exit`, `hedge`, `watchlist`, `pass`, `wait for proof`, or `re-underwrite`.
- If current facts matter, verify dates, timestamps, and latest state before analyzing. Distinguish reported events from confirmed facts, and distinguish spot, futures, closing, and intraday commodity or market observations.

## Causal Spine

Use this full sequence:

1. Event and baseline.
2. What is new.
3. Transmission channels.
4. First variables likely to reprice.
5. Direct winners/losers.
6. Higher-order consequences.
7. Scenarios, catalysts, public-equity expression, and portfolio action.

If you cannot name the channel, do more source work before writing. Load `references/impact-framework.md` for timing, directness, confidence, domain, and quantification rules.

## Workflow

1. Define the event precisely, state its evidence status and market-data cut-off, and name the public-equity decision it could change.
2. Identify what changed versus consensus/baseline and what listed equities already appear to discount.
3. Draft the transmission map before broad research, ending every channel in issuer, sector, earnings, valuation, positioning, or portfolio implications.
4. Write the key hypotheses, confirmers, and falsifiers.
5. Gather evidence, prioritizing primary sources and recency.
6. Rank impacts by sign, magnitude, timing, confidence, and directness. Group representative issuer or sector candidates only when they share the same transmission channel, first affected line item, and directional read-through; split rows when the economics differ.
7. Identify what is priced and what may still be mispriced in the affected equities, peer group, sector, index, or factor exposure. Ground priced-in conclusions primarily in affected issuer/sector price action, revisions or valuation movement, or the relevant transmission market; use broad-index performance as context only.
8. Build base/upside/downside scenarios.
9. Write the strongest counterargument.
10. End with monitoring, falsifiers, and what would change portfolio action.

Use `references/workflow.md` for full-form reports.

## No Portfolio / Watchlist Fallback

If the user does not provide a portfolio, position list, thesis, benchmark, or watchlist, do not stall and do not invent holdings. Build a general public-equity exposure map:

- industries and sub-industries most exposed;
- countries, currencies, and geographic revenue/cost exposures;
- public companies and relevant private companies with public-equity read-throughs;
- commodities, rates, FX, credit-spread, volatility, or demand variables that transmit into equity estimates or multiples;
- likely beneficiaries, losers, second-order peers, suppliers, customers, and crowded expressions;
- a research queue using `watchlist`, `wait for proof`, `pass`, or `re-underwrite` rather than portfolio-specific add/trim/exit language.

Portfolio-specific action should be labeled `not available without holdings / active weights / mandate`. The report must still terminate in issuer impact, sector/peer impact, earnings or estimate path, valuation/multiple impact, positioning/flow impact, and next Public Equity Investing workflow.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: event verification, issuer/sector exposure, earnings and valuation read-through, positioning/flow impact, scenarios, and counterarguments. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.

## Output Modes

- **Full economic-impact report:** default analytical route for broad or substantial reusable public-equity impact requests, especially those with many issuers, scenarios, sources, or monitoring items. For a substantive reusable economic-impact report or explicit HTML public-equity shock analysis, produce a polished standalone HTML economic-impact report following `../../shared/html-artifact-standard.md`; let the event and equity transmission channels determine the report structure.
- **Standardized dashboard:** use only when the user explicitly asks for a standardized dashboard, reusable dashboard template, or structured payload-driven render. For that path, use `references/DASHBOARD_PACK.md`: `economic-impact-report` owns the public-equity transmission logic, scenario analysis, issuer/sector exposure map, earnings and valuation read-through, positioning implications, and portfolio watch items; `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 support files behind the HTML dashboard unless explicitly requested.
- **Explicit quick PM read:** use only when the user explicitly asks for quick, short, summary, one-page, brief, or TL;DR. Include event status, public-equity bottom line, primary transmission channel, most affected listed exposures, what is priced, what needs proof, and next monitor.


## Output Contract

Unless the user explicitly asks for a shorter or narrower format, produce the full report. The first 150 to 250 words should stand alone as an executive summary, but the rest of the report should still include the full causal map and investment implications.

Minimum sections:

- `Executive Call`
- `Event Status And Market Baseline`
- `Source And Freshness`
- `What Is New Vs. Expected`
- `Event-To-Equity Transmission Map`
- `Public Equity Framing`
- `Ranked Equity Impact Map` / `Issuer And Sector Impact` with issuer and sector exposure candidates
- `What Is Priced In Vs. What Requires Proof`
- `Earnings, Valuation, And Positioning Read-Through`
- `Scenario Matrix`
- `Monitoring Triggers And Research Queue`
- `Bottom-Line Judgment`

Use `references/report-template.md` for the full structure, `references/domain-checklists.md` for domain-specific checks, and `references/quality-bar.md` before final delivery.

For Markdown draft/support outputs explicitly requested by the user or used as renderer input, run `scripts/check_economic_impact_report.py <support_note.md>` when practical. The checker validates required sections, source/freshness posture, and unresolved placeholders; it is a QA guardrail, not a replacement for source work. Markdown files should not be the lead user-facing artifact when an HTML report is expected.

Use draft mode while iterating and delivery mode before circulating or sending a final file:

```bash
python scripts/check_economic_impact_report.py --mode draft path/to/support_note.md
python scripts/check_economic_impact_report.py --mode delivery path/to/support_note.md
```

`--mode delivery` is the default and must fail if the report is missing a dedicated `Source And Freshness` section, lacks a data cut-off/as-of date, lacks sources used, omits the stale/missing-data assessment, or discloses stale, missing, unknown, unsupported, or weak evidence for load-bearing claims. `--mode draft` surfaces the same source/freshness issues as warnings so the report can remain a work in progress.

## HTML Guidance

For a substantive standalone HTML economic-impact report, load `../../shared/html-artifact-standard.md` and use these workflow-specific requirements:

- Front-load an investor conclusion and an `Event Status And Market Baseline` block stating what is verified, what is reported or assumed, the as-of timestamp, relevant market benchmark, and material gaps. When material intraday observations inform the view, state an exact research cut-off time and time zone. For commodity shocks, distinguish benchmark, spot versus futures, contract/month when relevant, intraday versus close, and source timestamp.
- Make the `Event-To-Equity Transmission Map` the primary analytical object: event or shock -> channel -> first variable -> issuer/sector driver -> financial line item -> public-equity action or monitoring implication.
- Follow it with a `Ranked Equity Impact Map` that separates direct beneficiaries/losers from conditional and higher-order expressions. Combine exposures in one row only when their transmission channel, first affected line item, and directional read-through match; otherwise split them even if they are thematically adjacent. When company-specific work has not been completed, label named issuers as representative exposure candidates or a research queue, not investment conclusions.
- Include `What Is Priced In Vs. What Requires Proof` before the detailed scenario and monitoring material. Ground priced-in claims primarily in evidence from affected equities or sectors, estimate revisions, valuation movement, or transmission-market indicators such as commodity curves, product spreads, or freight; broad-index performance is supporting context, not primary proof. Keep immediate market impact separate from estimate revisions, multiple effects, positioning/flow risk, and structural implications.
- Use visible fact/inference/scenario distinctions where a reader could otherwise confuse a reported event, an assumed shock, a market observation, and PM judgment.
- Cite load-bearing figures, dated facts, and consequential disputed claims near use; use compact section-level source notes when several adjacent claims share sources. Do not repeat citation chips through every cell, monitoring row, or conclusion when they compete with the analysis.
- If no portfolio was supplied, keep the visible action posture to `watchlist`, `wait for proof`, `pass`, or `re-underwrite` and state what evidence would convert the screen into portfolio action.
- Visually inspect the HTML according to the shared artifact standard before delivery and iterate on hierarchy, legibility, clipping, table density, citation noise, and whether the transmission decision is immediately visible.

## Edge Cases

- If the event is underspecified but analyzable, state your interpretation and proceed.
- If the user provides only an article/headline, extract the surprise, baseline, and causal map.
- If a domain is not materially affected, say `not material`.
- If current facts or market moves are uncertain, verify before claiming a view.
- If the event looks dramatic but economically minor, say so clearly.
- If the effect is mostly expected or priced, say so clearly.
- If the cleanest expression is not equities, say so, but do not turn this skill into the non-equity trade-construction owner.

## Reference Map

- `references/impact-framework.md`: timing, directness, confidence, transmission channels, quantification, and domain checks.
- `references/workflow.md`: full workflow and failure modes.
- `references/report-template.md`: full report template.
- `references/domain-checklists.md`: public companies, industries, countries, rates, options, futures, and cross-asset checks.
- `references/quality-bar.md`: final quality bar.

Referenced files: 8

View saved version →

---
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

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Portfolio Models & Trackers`
- `Company Filings & IR`
- `Market Data & Estimates`
- `Earnings Transcripts & Events`

## Deliverable Intake

Before source gathering or analysis for a new substantive 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:

```bash
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:

```bash
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.

Referenced files: 17

View saved version →

---
name: event-driven-analyzer
description: Use when analyzing dated public-equity event paths, probabilities, payoffs, and expected returns. Do not use for generic catalyst lists, risk sizing, hedges, capital structure, covenants, or credit recovery.
---

# Event Driven Analyzer

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Market Data & Estimates`
- `Company Filings & IR`
- `Earnings Transcripts & Events`
- `Internal Research`

## Internal Support

When this workflow needs rendering, evidence/data preparation, style, or sector context, route support through the visible `public-equity-investing` router and its bundled internal playbooks. Route workbook or model QA through the visible `model-audit-tieout` workflow.

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For an explicit full event analysis, full report, or reusable/source-heavy special-situations package, the default resolves the presentation surface to a polished standalone HTML event report unless the user requests an alternate surface, a quick/no-file answer, or model/math output. In interactive runs, ask only remaining material choices such as depth, audience/use, or focus; in non-interactive runs, default to the HTML event report and `Full working analysis` while disclosing those assumptions outside the artifact. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

## Purpose

Convert a public-equity catalyst into a path-dependent underwriting view:

`event -> conditions -> timing -> scenarios -> payoffs -> probabilities -> expected return -> trade expression -> monitoring plan`

This skill owns event-driven analysis for mergers, spins, split-offs, activism, regulatory/litigation events, tenders, index events, rights offerings, lockups, de-SPACs, stubs, warrants, preferreds, and other dated public special situations.

Ownership boundary: this skill owns dated public-equity event paths, probability trees, payoff math, expected value, timing, trade expression, and monitoring. Use Credit Markets for credit instruments, creditworthiness, restructuring, distressed, recovery, spreads, yields, covenants, and debt security analysis. If a distressed or restructuring event needs both, this skill can own the equity event path while Credit Markets supplies capital-structure, covenant, and recovery inputs.

## Do Not Use

- General long/short thesis without a controlling event: use `long-short-pitch`.
- Calendar/watchlist without underwriting: use `catalyst-calendar`.
- Credit instruments, creditworthiness, restructuring, distressed, recovery, spreads, yields, covenants, debt security selection, capital structure, priority, liquidity, fulcrum, or recovery waterfall work: use Credit Markets.
- Portfolio exposure, hedge, or sizing work: use `portfolio-risk-management`.
- Macro/rates/FX/commodity transmission map: use `economic-impact-report`.
- Ongoing thesis monitoring after underwriting: use `thesis-tracker`.

## Required Posture

- Do not invent an event. If no company/security/event is supplied and no active event is found, return an intake request or event-scan framing.
- Timestamp market-sensitive facts: price, spread, borrow, bond/loan level, option price, regulatory status, and court date.
- Prioritize primary documents over press commentary: merger agreements, 8-Ks, S-4/F-4, proxies, Schedule TO/14D-9, Form 10s, 13D/Gs, indentures, court/regulator records, and company releases.
- Separate `Fact`, `Assumption`, and `Judgment` for important inputs.
- Scenario probabilities must sum to 100% before presenting probability-weighted conclusions.
- Calibrate recommendation language to evidence stage. Without timestamped pricing and execution inputs required for the proposed expression, such as price/volume, spread, borrow, liquidity, when-issued trading, index treatment, or hedge inputs, present an underwriting framework or entry screen and use `Wait`, `Monitor`, or `Diligence to initiate` rather than an executable `Buy`, `Own`, or `Initiate` headline.
- If possible MNPI is supplied, do not recommend a trade from it; flag compliance/legal review.

## Workflow

1. **Classify the event and security.** Identify event type, sub-type, right security or spread expression, and whether a playbook reference is needed.
2. **Build the fact pack.** Capture parties, terms, current price, unaffected price, timing, outside date, approvals, conditions, litigation/regulatory posture, borrow/liquidity, and sources.
3. **Build the timeline.** Separate known dates from estimated windows and highlight the next real catalyst.
4. **Compute market pricing when supportable.** Use gross spread, annualized spread, market-implied probability, downside/break price, borrow/financing/dividend adjustments, hedge ratio, and expected return only where source-backed inputs exist. Otherwise state the missing trade-ready inputs and build an entry screen or gating-items view.
5. **Define terminal cases.** Use unaffected, peer-adjusted unaffected, standalone value, litigation/regulatory outcomes, SOTP, or Credit Markets-supplied recovery values only when the final question is a listed-equity event view.
6. **Build a supported event path.** Use a scenario tree with probability, timing, terminal value, return, rationale, and signposts only when the necessary inputs are supportable. Otherwise show mechanics, valuation screens, gating evidence, and the inputs needed for trade readiness without false precision.
7. **Identify gating items.** Name the controller, evidence, next signpost, and action threshold.
8. **Recommend expression and monitoring.** State buy/avoid/watch, implementation, sizing caveats, review thresholds, and monitoring plan.
9. **Red-team.** Explain how the trade loses money, what the market may know, what is stale/missing, and what changes the recommendation.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: fact timeline, market pricing, regulatory/legal conditions, probability/payoff math, trade expression, and red-team review. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Output Modes

- **Full event report:** default analytical route for broad or substantial reusable event-driven requests, especially those with many dates, sources, or tables. For an explicit full event analysis, full report, or reusable/source-heavy special-situations package, produce a polished standalone HTML event report following `../../shared/html-artifact-standard.md`; let the event type determine the report structure. Include event mechanics, evidence-backed valuation or pricing where available, trade or entry posture, monitoring, red team, open questions, and sources.
- **Standardized dashboard:** use only when the user explicitly asks for a standardized dashboard, reusable dashboard template, or structured payload-driven render. For that path, use `references/DASHBOARD_PACK.md`: `event-driven-analyzer` owns the event facts, supported scenario math, timing, probability/payoff view, trade construction, and monitoring judgment; `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 support files behind the HTML dashboard unless explicitly requested.
- **Explicit quick PM read:** use only when the user explicitly asks for quick, short, summary, one-page, brief, or TL;DR. Include recommendation, setup, pricing, implied probability, gating item, downside, expected return, next catalyst, and kill criteria.
- **Model/math mode:** deterministic spread, annualized return, implied probability, hedge ratio, CVR/spin/scenario EV, dated event probability, and payoff math. Use `scripts/event_math.py` with `references/event-math-schema.md`; use Credit Markets for capital structure, covenant, debt-security, and recovery math.
- **Red-team mode:** attack downside, probabilities, gate risk, source quality, timing, crowding, liquidity, borrow, and sizing.
- **Monitoring/update mode:** state what changed and whether probability, sizing, or recommendation changes.

Do not use quick mode just because context is sparse. Sparse context should produce a full screen-grade event report with source gaps, assumptions, and missing inputs.

## HTML Guidance

For a substantive HTML full event report, load `../../shared/html-artifact-standard.md` and use these event-specific requirements:

- Lead with a recommendation headline calibrated to the evidence stage, a decision/action-posture box, three to five event-specific evidence tiles, and the event type's primary analytical object.
- If required pricing or execution inputs are missing, make visible that the report is an underwriting framework or entry screen, name the evidence needed for an actionable recommendation, and do not make the title more actionable than the evidence.
- For a spin-off or split-off, lead with distribution mechanics and hard dates; a value-allocation bridge that keeps distributed stake, retained stake, and cash/debt transfer separate; SpinCo and RemainCo starting points; confirmed evidence versus the technical-supply thesis; and the entry screen, expression, monitoring, and red-team case.
- For merger arbitrage or tender work, lead with spread, downside, implied probability, and scenario tree only when sourced inputs support them. For litigation or regulatory work, lead with procedural path, remedy risk, and payoff implications. For flow or technical events, lead with confirmed flow mechanics, liquidity, execution evidence, and exit path.
- Keep `Fact`, `Assumption`, `Derived Calculation`, and `PM Judgment` visibly distinct.
- Include probability-weighted scenarios, expected-return math, and trade-execution modules only when inputs are sourced and supportable; otherwise replace them with event mechanics, valuation screens, evidence gaps, and gating inputs.
- Visually inspect the HTML according to the shared artifact standard before delivery and iterate on hierarchy, legibility, clipping, crowding, and decision clarity.

## Deterministic Helper

Run event math when the user provides structured inputs:

```bash
python scripts/event_math.py --mode cash_merger --input path/to/input.json --pretty
python scripts/event_math.py --mode scenario_ev --input path/to/input.json --pretty
python scripts/event_math.py --mode scenario_ev --input path/to/input.json --allow-probability-sum-mismatch --pretty
```

The helper performs repeatable math only. It does not fetch prices, verify terms, assign legal/regulatory probabilities, or replace PM judgment.
For `scenario_ev`, probabilities must sum to 1.0 by default. A mismatch hard-fails unless `--allow-probability-sum-mismatch` is passed for diagnostic, non-memo-ready output.

## Reference Map

- `references/event_taxonomy.md`: event labels and routing.
- `references/source_hierarchy.md`: source hierarchy by event type.
- `references/scenario_math.md`: spread, probability, annualization, EV, and hedge math.
- `references/event-math-schema.md`: deterministic helper input contract.
- `references/merger_arb_playbook.md`: mergers, tenders, collars, CVRs, deal breaks.
- `references/spins_activism_playbook.md`: spins, split-offs, activism, proxy fights.
- `references/litigation_regulatory_playbook.md`: court, agency, antitrust, CFIUS, IP, settlement.
- `references/restructuring_special_situations_playbook.md`: distressed, exchange offers, bankruptcy, technical events.
- `references/output_templates.md`: memo and dashboard templates.
- `references/quality_checks.md`: final QA.

## Final QA

Before finalizing, confirm event/security clarity, timestamped market data or caveat, fact/assumption/judgment split, primary-source priority, probabilities summing to 100%, explicit downside methodology, specific gating item, actionable monitoring plan, and a red-team section.

## Public Equity PM Judgment Layer

For substantial event work, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

Index / ETF / Passive Flow Event analysis is an explicit event-driven equity path.

Required PM judgment:
- State whether the edge is underwriting, timing, flow, legal/process, or mispriced optionality.
- Include base-rate awareness: what usually happens in this event class and what makes this case different.
- Include trade expression menu: common equity, pair, spread, options, stub, when-issued, rights, warrants, basket hedge, or avoid.
- Require path risk: mark-to-market pain, liquidity, borrow, crowding, event delay, financing cost, and exit liquidity.
- For flow events, include flow-vs-ADV, price/volume timestamp, float, market cap, borrow, ETF/index AUM assumptions, and exit plan.

Referenced files: 15

View saved version →

---
name: financials-normalizer
description: Use when normalizing public-company financials from source materials. Do not use for private data rooms or non-financial cleanup.
---

# Financials Normalizer

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Company Filings & IR`
- `Portfolio Models & Trackers`
- `Market Data & Estimates`

## Deliverable Intake

When invoked as support for an owning workflow, inherit its resolved deliverable preferences and do not re-prompt. Only when this skill independently owns a new substantive standalone normalization deliverable should it, before source gathering, analysis, or rendering, load `../../shared/deliverable-intake-policy.md` and perform its adaptive `request_user_input` preflight for materially unresolved preferences.

## Purpose

Load `shared/equity-research-support-standard.md` and `shared/support-layer-routing-contract.md` before substantial source, data, QA, or style work.


Turn messy public-company source financials into auditable, model-ready normalized statements, KPI schedules, consensus/guidance inputs, segment schedules, share-count support, net-debt and capital-allocation support, source citations, assumptions, conflicts, and QA flags for downstream Public Equity Investing workflows.

Boundary: shipped scripts create `Source_Index.csv`, `Normalized_Financials_Long.csv`, and `Normalization_Issues.csv`. Wide statements, KPI schedules, adjustment logs, conflict logs, assumption registers, and workbook/deck-ready tabs are instruction-led unless explicitly built from staging data.

For a standalone request for **model-ready normalized financials**, do not treat a long-form staging CSV alone as the analyst deliverable. Create a model-loading package from the staged rows: full-scope wide schedules relevant to the supplied financials, a disclosure/comparability bridge when definitions or presentation changed, material QA flags, and logged validation checks. Use XLSX when the user requests a workbook or will load/review the output in a workbook; otherwise a clearly organized CSV package plus a concise review summary is appropriate. This is a data-first skill; do not force an HTML artifact unless the user requests one.

## Embedded Support Routing

This is an embedded service under the owning workflow unless the user explicitly asks for standalone normalization. Preserve the `owning_workflow` internally, such as `equity-model-update`, `dcf-model-builder`, `three-statement-model-builder`, `comps-valuation`, `earnings-preview`, `earnings-deep-dive`, `memo-builder`, `thesis-tracker`, `scenario-sensitivity-generator`, `portfolio-risk-management`, or `dashboard-builder`.

For substantial embedded work, preserve `decision_impact`, `readiness_effect`, `artifact_role`, and `hidden_unless_requested` in internal context or support artifacts. Do not print those internal field names in the owning workflow's user-facing artifact. Do not own the valuation, memo, earnings, or recommendation; state in natural language how normalization issues change estimate confidence, valuation support, target support, sizing, model readiness, or circulation readiness. `Source_Index.csv`, `Normalized_Financials_Long.csv`, `Normalization_Issues.csv`, run logs, manifests, and support notes are secondary/support artifacts when invoked by an owning workflow.

## Non-Negotiables

- Preserve raw/source materials.
- Prefer user files/context, callable runtime apps/connectors when actually available, primary public sources, user-provided provider exports, then labeled assumptions. Never imply live provider access when it is unavailable.
- Never invent missing financials; mark unavailable values as `missing_required_source`.
- Keep normalized values traceable to source ID, source name/location, retrieved-at date, period, units, currency, and evidence label.
- Missing `source_id` must remain visible as `SRC-UNSPECIFIED`, produce a QA flag, and block decision-grade handoff.
- Retain conflicts rather than silently choosing values.
- Flag stale, preliminary, unaudited, OCR-derived, or low-confidence data.
- Do not infer fiscal period-end dates from quarter labels alone; use an explicit source date or mark the date missing and flag it.
- Keep issuer outlook or guidance in `kpi_schedule` with `issuer_management_claim`; reserve `consensus_estimate` with `estimate_consensus` for externally sourced consensus estimates.
- When a segment, KPI, non-GAAP definition, or balance-sheet presentation changes, preserve both bases and create a comparability bridge before calling any series model-loadable.
- Apply comparability status at the affected series or line-item level. A changed cash presentation does not recast unrelated balance-sheet rows.
- Use `comparable_rounded` when an unchanged reported series is comparable across periods but only available in rounded narrative units; disclose that it is unsuitable for exact tie-out.
- Do not backsolve an undisclosed comparable value from rounded amounts or percentage growth for model loading. A labeled directional calculation may appear separately only when useful.
- Material open exceptions must be surfaced in `QA_Flags` and in the readiness summary; an empty technical `Normalization_Issues` file does not mean the financials are clear for downstream use.

## Workflow

1. **Classify job.** Public-equity issuer financials, earnings/model update, consensus/provider export, ETF/index constituent support, portfolio/market-data support, or equity-risk debt/liquidity context.
2. **Build source index.** Capture source ID, name/type, owner/provider, period, as-of date, retrieved-at date, location, source rank, freshness, and notes.
3. **Extract long-form staging.** Use `Normalized_Financials_Long` before wide statements; preserve original line labels beside canonical labels.
4. **Normalize periods, scale, currency, signs, and labels.** Keep reported, adjusted, pro forma, provider-standardized, estimated, and analyst-adjusted values separate.
5. **Reconcile disclosure changes.** Identify renamed, regrouped, newly introduced, discontinued, recast, or definition-changed segments/KPIs/non-GAAP lines; preserve legacy and new bases; create a disclosure/comparability bridge with model treatment.
6. **Reconcile and QA.** Check subtotals, roll-forwards, balance sheet balance, cash flow bridge, units/currency, duplicate periods, missing sources, stale/conflicting values, signs, unsupported KPIs, and completeness of the intended model-loading scope. Log performed checks and results; do not claim a check count that is not preserved in an output.
7. **Produce package.** For standalone model-ready work, produce loadable wide schedules plus `QA_Flags` and `Validation_Checks` from the audited staging layer; include a disclosure/comparability bridge whenever presentation changed. For narrower extraction/support work, return only the deterministic CSV outputs or instruction-led tabs actually created.
8. **Hand off.** State what is loadable, what is audit-only, and what remains partial or blocked before routing to models, earnings, comps, memo, thesis, scenario, risk, ETF/index, or deck/report skills. Route covenant/recovery/debt-security normalization to Credit Markets.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: source inventory, line-item mapping, period/unit normalization, conflict log, and QA. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.

When embedded in a broader workflow, "lead" means lead for normalization only; the owning workflow remains the investment-artifact owner.


## Evidence Labels

Use exact labels from `references/normalization-schema.md`, including `fact_source_reported`, `fact_provider_standardized`, `derived_calculation`, `issuer_management_claim`, `management_adjusted`, `analyst_adjusted`, `analyst_interpretation`, `assumption_user_provided`, `assumption_inferred`, `estimate_consensus`, `stale_source`, `contradicted_source`, `missing_required_source`, and `unknown`.

Confidence labels are `high`, `medium`, or `low`.

## Scripts

```bash
python scripts/normalize_extracted_financials.py path/to/input.csv --output-dir output
python scripts/validate_normalized_financials.py output/Normalized_Financials_Long.csv
```

For workbook inputs, first extract the relevant tab/range with spreadsheet tools into a table/CSV; scripts must not destructively modify workbooks.

## Final Response

Return:

1. what was normalized: entity, sources, periods, units, currency, scope;
2. outputs created;
3. what can be loaded into a model and what remains audit-only, partial, or blocked;
4. material QA findings and disclosure/comparability breaks;
5. fact versus assumption summary and validation checks actually performed;
6. recommended next step or missing source.

## Reference Map

- `references/source-protocol.md`: hierarchy, stale data, citations, conflicts.
- `references/normalization-schema.md`: output schema, signs, scales, labels.
- `references/line-item-taxonomy.md`: statement/KPI mappings.
- `references/qa-rules.md`: reconciliation tests and red flags.
- `references/integration-guide.md`: downstream Public Equity Investing handoffs.

Referenced files: 11

View saved version →

---
name: idea-generation
description: Use when triaging public-equity idea candidates. Do not use for final trade recommendations, pitches, memos, or models.
---

# Idea Generation For Public Equity Investing

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Market Data & Estimates`
- `Company Filings & IR`
- `Internal Research`

## Internal Support

When this workflow needs rendering, evidence/data preparation, style, or sector context, route support through the visible `public-equity-investing` router and its bundled internal playbooks. Route workbook or model QA through the visible `model-audit-tieout` workflow.

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For a substantive idea screen, market map, watchlist review, or reusable/source-heavy candidate set, the default resolves the presentation surface to a polished standalone HTML idea-triage report unless the user requests another surface, a quick/no-file answer, or workbook/tracker output. In interactive runs, ask only remaining material choices such as depth, audience/use, or focus; in non-interactive runs, default to the HTML idea-triage report and `Full working analysis` and disclose those assumptions outside the artifact. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

## Purpose

Triage public-equity idea candidates and screen outputs into research-worthy longs, shorts, pairs, catalysts, relative-value ideas, watchlist items, and rejected false positives. This is a PM-style research-prioritization skill, not a final recommendation engine.

A strong output explains why a security surfaced now, possible variant perception, what is priced in, what would make it investable, first rejection risk, and the next workflow.

Use chat for quick triage. For a substantial reusable screen, market map, watchlist review, or source-heavy candidate set, produce a polished standalone HTML idea-triage report following `../../shared/html-artifact-standard.md`; let the mandate and screening question determine the structure. Use `dashboard-builder` only when the user explicitly asks for a standardized dashboard, reusable dashboard template, or structured payload-driven render.

## Operating Rules

- Never present a screen result as a final recommendation.
- Label outputs as idea candidates, watchlist items, deeper-research candidates, or rejected false positives.
- Preserve user portfolios, watchlists, models, notes, and spreadsheets; add outputs rather than overwriting source work.
- Use prompt/connected/user files first, primary sources next, market/consensus data next, and web fallback only when current public data is needed.
- Do not fabricate unavailable market data or metrics.
- Use `crowded` only when supported by positioning, ownership, flow, short-interest, or comparably direct evidence. If the evidence is limited to price appreciation, narrative visibility, or simple valuation, use `expectations-heavy`, `valuation-gated`, or `crowding-risk candidate`.
- Do not advance a candidate solely because the stock rallied after a thematic catalyst or management mentioned the theme. For an advanced name, show a source-backed link from the driver to orders, backlog, revenue, margins, or estimate revisions; otherwise label it `needs exposure attribution`.

## Workflow

1. **Assess context.** With no context, use liquid public-equity defaults and state assumptions. With partial context, infer mandate/style and label assumptions. With rich context, treat provided portfolios, screens, notes, files, or connected data as primary evidence.
2. **Set mandate and universe.** Identify long-only, long/short, market-neutral, event, credit, region, sector, cap size, liquidity, benchmark, horizon, and allowed instruments.
3. **Normalize candidates.** Resolve tickers, ADRs, share classes, currencies, fiscal calendars, sectors, liquidity, benchmark membership, and portfolio/watchlist overlap.
4. **Screen by archetype and beneficiary pathway.** Use long, short, pair, relative value, catalyst, and watchlist archetypes rather than one generic rank. For thematic screens, map candidates by beneficiary pathway before ranking, such as electrical/power distribution, construction, networking, cooling, grid/generation, or colocation/real estate.
5. **Score if structured data exists.** Use `scripts/score_ideas.py` only for user-provided candidate rows and scoring fields.
6. **Apply PM triage.** Test denominator quality, estimate credibility, catalyst path, valuation support, risk compensation, verified positioning versus inferred expectations risk, liquidity, and false-positive risk.
7. **Output priorities and routing.** Lead with a candidate funnel and route candidates to model update, earnings, pitch, thesis tracker, hedge, event, credit, macro, scenario, memo, or QC workflows as appropriate.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: screen construction, source QC, variant view, catalyst path, risk flags, and prioritization. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Deterministic Scoring Helper

```bash
python scripts/score_ideas.py candidates.csv --output-dir output
```

The helper materializes supplied scores into ranked support outputs and warnings. It does not create proprietary market data or replace PM judgment. If no numeric score fields are supplied, treat output as qualitative triage.

For standardized dashboard handoffs only, use `references/DASHBOARD_PACK.md`. `idea-generation` owns candidate triage, screen interpretation, and workflow routing; `dashboard-builder` owns the shared shell/rendering/QA. Build a `public_equity_investing_dashboard.v1` payload as an internal renderer input, and keep JSON/Markdown/CSV support files behind the HTML artifact unless explicitly requested.

## Output Contract

Default output:

- scope and assumptions;
- methodology and data/source caveats;
- headline research-priority conclusion and candidate funnel;
- beneficiary-pathway map when relevant to a thematic screen;
- ranked idea table with exposure proof and expectations risk;
- PM-style idea cards for highest-priority names;
- rejected/deprioritized false positives;
- cross-idea themes and risk observations;
- next research step for each important candidate;
- downstream routing.

Ranking buckets: `A - immediate research candidate`, `B - watchlist / needs trigger`, `C - screen flag only`, and `Reject`.

For thematic or source-heavy idea screens, express the funnel as `Advance to deeper work`, `Valuation / expectations gated`, `Exposure not yet proven`, and `Deprioritized or reject`. Make clear that `Advance to deeper work` is a research-priority status, not an investment recommendation, approved position, or attractive entry point; an advanced candidate may still be valuation-gated or entry-gated. A candidate without a quantified or source-backed link to the theme stays in `Exposure not yet proven` and is labeled `needs exposure attribution`.

## HTML Guidance

For a substantive HTML idea-triage report, load `../../shared/html-artifact-standard.md` and apply these workflow-specific rules:

- Lead with the research-priority conclusion and candidate funnel; make the funnel or an exposure-versus-expectations matrix the primary visual object.
- Use three to five first-read tiles only when each has a distinct job, such as universe size, advance count, valuation-gated count, unproven-exposure count, or the most important evidence gap.
- Keep methodology and evidence-posture commentary compact or place it below the candidate funnel when it would otherwise delay the primary research-prioritization visual.
- Put the ranked candidate board near the top. For thematic screens, organize candidates by beneficiary pathway before or alongside rank.
- Show `Exposure proof`, `Expectations risk`, `First rejection`, and `Next workflow` in the table or visible candidate summaries. Reserve longer idea cards for the highest-priority names.
- Distinguish verified positioning from inferred crowding risk; do not make the headline or status label more certain than the evidence.
- Keep citations traceable but readable: do not fragment years, ticker symbols, ranges, product names, or guidance values into separately linked tokens, and avoid an oversized citation run in the hero.
- Visually inspect local HTML via local headless-browser screenshots, not the in-app Browser plugin, and iterate on legibility, hierarchy, clipping, citation rendering, and whitespace before delivery.

## Reference Map

- `references/source-qc.md`: source hierarchy, stale data, citations, data caveats.
- `references/workflow.md`: full workflow and context adaptation.
- `references/screen-archetypes.md`: long, short, pair, catalyst, and watchlist archetypes.
- `references/sector-overlays.md`: sector metrics and traps.
- `references/output-standards.md`: report and idea-card templates.
- `references/downstream-routing.md`: local handoff patterns.
- `references/scoring-materializer.md`: deterministic scoring contract.

## Public Equity PM Judgment Layer

For substantial screens or idea queues, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

Every top idea must include `Actionability`, `Variant Wedge`, `Why Now`, `First Rejection`, `What Would Make It Investable`, `What Would Kill It`, and `Next Workflow`.

Required PM judgment:
- Long-only: benchmark fit, active share, quality durability, downside versus benchmark, liquidity, and add/trim path.
- Long/short hedge fund: catalyst path, shortability, borrow, gross/net impact, factor crowding, and cover discipline.
- Sell-side: rating-change potential, estimate revisions, target-price debate, client relevance, and risk-to-rating.
- ETF/index: index methodology, constituent weight, rebalance effects, liquidity, passive-flow relevance, and factor exposure.
- Public equity diligence: source pack completeness, thesis readiness, diligence queue, and next evidence needed.

Referenced files: 10

View saved version →

---
name: initiating-coverage
description: Use when building public-equity-investing initiating coverage reports. Do not use for trade pitches, memos, earnings notes, models, or tearsheets.
---

# Initiating Coverage

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Market Data & Estimates`
- `Company Filings & IR`
- `Earnings Transcripts & Events`
- `Portfolio Models & Trackers`
- `Internal Research`

## Internal Support

When this workflow needs rendering, evidence/data preparation, style, or sector context, route support through the visible `public-equity-investing` router and its bundled internal playbooks. Route workbook or model QA through the visible `model-audit-tieout` workflow.

## Deliverable Intake

Before source gathering or analysis for a new substantive 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.

## Purpose

Build a full public-equity-investing initiation report that is thesis-led, model-backed, valuation-aware, source-disciplined, and explicit about what is proven versus assumed.

This skill owns initiation-style research architecture. It can produce a report outline, full initiation report, structured internal handoff, source request list, model/valuation workplan, or deck-ready storyboard. For a substantial reusable initiation package, default to a polished standalone HTML initiation report following `../../shared/html-artifact-standard.md`, unless the user requests another surface, a quick/no-file answer, or a model/workbook-first deliverable. Use `dashboard-builder` only when the user explicitly asks for a standardized dashboard, reusable validated template, or structured payload-driven render. Structured JSON is support/audit material, not the final user-facing artifact. This skill does not own live trade expression, generic memo writing, earnings notes, model-only work, or one-page issuer profiles.

## Do Not Use

- Live trade pitch, pair trade, add/trim/exit rules, short-cover logic, or variant-perception trade expression: use `long-short-pitch`.
- IC memo, investment memo, committee note, client memo, PM update, or memo rewrite: use `memo-builder`.
- Pre-earnings or post-earnings note: use `earnings-preview` or `earnings-deep-dive`.
- Model refresh, DCF, 3-statement model, comps workbook, or sensitivity-only task: use the relevant model or scenario skill.
- One-page public issuer profile: use `company-tearsheet`.

## Non-Negotiables

- Preserve user files and models. Create additive outputs or marked-up recommendations unless the user explicitly asks for edits.
- Prioritize user-provided material, connected/approved sources, primary filings/releases/transcripts, trusted providers, then clearly labeled assumptions.
- Include report date, data cut-off, evidence confidence, underwriting status, unresolved conflicts, and major assumptions. Keep evidence confidence distinct from underwriting readiness; do not describe investability as source confidence.
- Label facts, company claims, street estimates, model-derived values, PM judgment, assumptions, mixed claims, and missing sources.
- Do not make personalized investment advice or compliance/legal/tax conclusions. Treat rating/target price language as research output requiring human review.
- If context is thin, produce a skeleton, research agenda, model architecture, source request list, and thesis hypotheses rather than fabricating facts.

## Workflow

1. **Classify the mode.** Choose `sell_side_initiation`, `buy_side_deep_dive`, `long_only_initiation`, `hedge_fund_initiation`, `credit_adjacent_initiation`, `sector_initiation`, `model_first_initiation`, or `report_refresh`. Load `references/report-modes.md` only when mode-specific requirements matter.
2. **Assess context depth.** For no-context prompts, ask one targeted clarification only if company/security or output mode is unclear. For partial/full context, preserve supplied facts, identify missing inputs, and build a source register and assumption register.
3. **Complete market data and valuation inputs.** Before finalizing a substantive initiation, retrieve current price with an as-of timestamp, market capitalization, diluted share-count inputs, enterprise-value inputs, and available consensus or estimate context from approved accessible sources. Load `references/source-and-evidence.md` for required treatment. If an input is unavailable, label it missing and explain what valuation conclusion it prevents; do not omit available market context simply because the report remains preliminary.
4. **Coordinate with local skills.** Use `financial-source-of-truth` for evidence posture, `company-tearsheet` for issuer baseline, `financials-normalizer` or `excel-data-cleaner` for source prep, model skills for valuation work, `scenario-sensitivity-generator` for cases, and `thesis-tracker` after initiation.
5. **Frame the senior thesis.** Answer what the market is missing, what must be true, what falsifies the thesis, which KPI/catalyst matters, why the valuation method fits, and what would change the view.
6. **Apply the financed-growth gate when material.** When capital intensity, debt, lease liabilities, dilution, customer-funded buildout, or financing risk is central to the equity debate, require a pro forma fully diluted capitalization / enterprise-value bridge and after-financing return evidence before a positive ownership conclusion or target price. Use normalized FCF, ROIC or return on invested capacity, capacity-cohort cash returns, leverage, and interest burden as applicable. Treat equity-value-to-revenue or other revenue multiples as preliminary market context only when material financed obligations are not yet incorporated.
7. **Build the report.** Default structure: cover/view, executive summary, key debates, company overview, industry position, model summary, valuation, catalysts, risks/disconfirmers, scenarios, and source appendix. In standalone HTML, make the first read a single research-posture block, the central debate, the valuation or capital-return gate, the essential evidence, and what remains missing. Do not repeat the same conclusion in a hero, metric tile, PM-answer block, and decision box.
8. **Apply sector context.** Load `references/sector-overlays.md` for report-mode framing and use `sector-context-overlay` only when sector nuance affects KPIs, valuation, or red flags.
9. **Run QA.** Confirm the report has a real view, falsifiable thesis, sourced metrics, visible data cut-off, source conflicts, appropriate sector metrics, and non-boilerplate risks. For a local HTML file, inspect the opening viewport and important downstream sections with local headless-browser screenshots rather than the in-app Browser plugin; iterate on hierarchy, clipping, citation noise, and readability.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: evidence gathering, company and industry analysis, model/valuation, thesis and risk, and report QA. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Artifact Contract

Default initiation output should include:

- MD / PM-level answer with recommendation or research posture.
- Investment thesis with 3-5 evidence-linked claims.
- Key debates and variant perception.
- Company and industry overview.
- Model and forecast driver table.
- Valuation / target price methodology, sensitivity, and backup method.
- Current market data and valuation-input status, including as-of time and explicit missing inputs.
- Earnings quality and EPS basis when P/E or EPS-driven valuation is used.
- Catalysts, risks, disconfirming evidence, and monitoring items.
- Source register, conflicts, assumptions, and open evidence requests.

For a long-only initiation where valuation, the capital stack, or after-financing cash economics remain materially unproven, label the output a `Preliminary initiation underwrite` or `Watchlist initiation`. State the evidence and modeling required before ownership rather than implying a completed positive initiation or supplying an unsupported target price. This posture does not excuse omitting current market data that is obtainable from approved accessible sources.

For standalone HTML artifacts, keep citations traceable but readable: do not fragment tickers, fiscal periods, dates, prices, ranges, multiples, or metric names with inline source links. Cite a complete figure or statement, or use a compact nearby source note.

Structured handoffs should follow `references/output-schema.md` and can be validated with:

```bash
python scripts/validate_initiation_json.py path/to/initiation.json
```

For publication-looking reports, run `python scripts/validate_initiation_json.py path/to/initiation.json --publication-ready` so unresolved placeholders, weak source metadata, and unknown source IDs hard-fail. Use the validated structure to render or support the human-readable report; do not make raw JSON the lead deliverable unless explicitly requested.

Use `scripts/calculate_price_target.py` only when valuation assumptions are available in JSON; the helper calculates math, not analyst judgment.

If the user explicitly asks for a standardized dashboard, use `references/DASHBOARD_PACK.md`. `initiating-coverage` owns the thesis, report architecture, and valuation judgment; `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 support files behind the HTML dashboard unless explicitly requested.

## Reference Map

- `references/report-modes.md`: mode-specific output standards.
- `references/report-architecture.md`: full report structures and section variants.
- `references/thesis-framework.md`: senior thesis, debate, and falsification prompts.
- `references/valuation-and-modeling.md`: valuation methods, assumptions, and price-target logic.
- `references/source-and-evidence.md`: source hierarchy, labels, stale data, and evidence requests.
- `references/sector-overlays.md`: sector KPI, valuation, and red-flag overlays.
- `references/pm-md-standards.md`: quality bar for PM/MD-level initiations.
- `references/output-templates.md`: reusable report sections.
- `references/quality-checklist.md`: final QA.
- `references/integration-guide.md`: local handoff patterns.

## Final Note

End each initiation with evidence confidence, underwriting status, data cut-off, unresolved conflicts, major assumptions, and the recommended next handoff such as `thesis-tracker`, `equity-model-update`, `earnings-preview`, or `long-short-pitch`.

## Public Equity PM Judgment Layer

For substantial initiation work, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

Required PM judgment:
- State the decision hinge, variant perception, what is priced in, valuation basis, downside mechanism, ownership/positioning, benchmark relevance, and falsifiers.
- Add `etf_index_constituent_diligence` when the user is assessing an issuer as an ETF/index constituent, index exposure, passive-flow risk, or benchmark-relative holding.
- Include market cap, float/liquidity, ownership, short interest, factor exposure, index membership, and capital allocation when source-backed or clearly missing.
- Fund/product diligence is out of scope; public issuer or constituent diligence is in scope.

Referenced files: 19

View saved version →

---
name: long-short-pitch
description: Use when building PM-facing Public Equity Investing trade pitches, including sparse-context or partial-section requests. Do not use for formal memos; use memo-builder.
---

# Long / Short Pitch

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Market Data & Estimates`
- `Company Filings & IR`
- `Earnings Transcripts & Events`
- `Portfolio Models & Trackers`
- `Internal Research`

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For a substantive reusable trade pitch or explicit HTML pitch, the default resolves the presentation surface to a polished standalone HTML trade-pitch report unless the user requests another surface, a quick/no-file answer, or a standardized dashboard. In interactive runs, ask only remaining material choices such as depth, audience/use, or focus; in non-interactive runs, default to the HTML trade-pitch report and `Full working analysis` while disclosing those assumptions outside the artifact. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

## Goal

Turn a public-equity-investing idea into an investable trade pitch. This is the buy-side pitch muscle: what is mispriced, how to express it, why now, how much can be made or lost, what proves us wrong, and what action discipline governs add, trim, cover, hedge, or exit decisions.

Default deliverable: full PM-facing trade pitch. Chat is fine for conversational or narrow pitch work, but a substantial reusable pitch or explicit HTML pitch should become a polished standalone HTML trade-pitch report following `../../shared/html-artifact-standard.md`. Let the trade decision, expression, and implementation gates determine the hierarchy. The output should sound like a seasoned portfolio manager forming a research posture, not an analyst filling a template. Do not compress to a quick pitch unless the user explicitly asks for `quick`, `short`, `summary`, `one-pager`, `TL;DR`, red-team-only review, or one specific section.

## Use When

Use this skill when the user asks to:

- pitch a public-equity long, short, pair, relative-value equity, or event-driven equity idea
- build variant perception, trade expression, catalyst path, sizing considerations, add/trim/exit/cover rules, or investability
- pressure-test weak catalysts, poor risk/reward, missing disconfirmers, crowding, borrow, carry, or bad exit discipline
- upgrade a hedge-fund-style idea note rather than a formal memo
- answer only part of a pitch, such as variant perception, why now, expression, sizing logic, disconfirmers, or cover rules

Do not use for:

- formal IC memos, investment memos, committee notes, client notes, research notes, or polished PM updates; use `memo-builder`
- pure merger-arb spread math or regulatory timeline; use `event-driven-analyzer` first
- pure capital-structure, covenant, recovery, maturity-wall, bond, loan, CDS, or debt-security work; use Credit Markets
- model refresh, earnings preview/deep dive, source update, or scenario table generation with no pitch synthesis
- personal investment advice or trade execution

## Boundary With `memo-builder`

`long-short-pitch` owns trade construction and pitch discipline. `memo-builder` owns formal written artifacts and final memo synthesis.

Use this skill first when the unresolved question is: what is the trade, variant perception, expression, catalyst, and action discipline?

Hand off to `memo-builder` when the pitch needs to become an IC memo, investment memo, committee note, client note, PM update, or formal equity research note. Credit-first memos route to Credit Markets.

## Operating Defaults

- Do not create files for narrow pitch work unless the user explicitly asks. For substantial reusable or explicitly requested HTML pitches, produce one polished standalone HTML trade-pitch report; do not force it through a fixed dashboard module inventory.
- Use `dashboard-builder` only when the user explicitly asks for a standardized dashboard, reusable dashboard template, PM cockpit, or structured payload-driven render. For that optional path, use `references/DASHBOARD_PACK.md`: `long-short-pitch` owns trade construction, variant perception, expression, risk/reward, and monitoring rules; `dashboard-builder` owns the standardized shell/rendering/QA. Build a `public_equity_investing_dashboard.v1` payload as an internal renderer input, and keep JSON/Markdown/CSV support files behind the HTML dashboard unless explicitly requested.
- Keep the pitch PM-usable; expand mechanics, not background.
- Never invent real-world facts. Unknowns must be labeled `TBD`, `not provided`, or explicit assumptions.
- Every material number must tie to a cited source, connector output, user-provided input, model output, or explicit assumption.
- If source access is incomplete, state the source posture and build a screen-grade pitch with missing data.
- Do not produce a blank template. If context is sparse, give a provisional stance, the best expression logic available, what would change the stance, and the exact missing data needed to upgrade conviction.
- If the user asks for only one section, answer that section directly with enough source posture, assumptions, and next data requests to make it usable. Otherwise default to the full pitch spine even when source context is thin.
- Ask a clarifying question only when there is no identifiable issuer, instrument, sector archetype, or trade direction and answering would be misleading.
- This skill can discuss proposed trade framing, but must not present account-specific advice or execute trades.

Load `references/intake-and-source-policy.md` for source tiers, request types, pitch modes, and minimum inputs.

## When To Invoke Support

Load `shared/support-layer-routing-contract.md` when support services are needed. Use `financial-source-of-truth` before final variant claims, market data, source conflicts, or management assertions. Use `financials-normalizer` or `excel-data-cleaner` before relying on messy financials, consensus/provider exports, ownership/short-interest tables, or event data. Use `deck-report-qc` before circulating a pitch deck/report and `style-guide-adapter` only after the pitch substance is locked. Support artifacts stay secondary; this skill owns trade construction, variant wedge, expression, catalyst path, and action discipline.

## Sparse Context And Partial Requests

When key facts are missing, lead with:

`Screen-grade only; placeholder assumptions used.`

Then give a PM stance before any metric table:

- `Actionability`: actionable candidate, watchlist, pass for now, or red-team only
- `Reason`: the one or two conditions that make the idea investable or not investable
- `What would change the stance`: evidence that would upgrade, downgrade, or kill the idea
- `Missing data`: exact items needed, not a generic diligence list

Sparse context does not mean short. Use the full pitch spine unless the user explicitly asks for a narrow section or compressed format.

For partial requests, do not force the full pitch spine. Deliver the requested slice, then add `Implications For The Trade` and `Missing Data To Upgrade Conviction`.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: variant perception, valuation/scenario work, catalyst path, risk/sizing/hedge, action rules, and red-team review. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Deterministic Scenario Support

This skill is primarily instruction-led, but it ships a scenario materializer for expected-value tables.

Use `scripts/materialize_trade_scenarios.py` when the user provides scenario rows or asks for scenario/EV math. The script accepts `references/scenario-ev-schema.md` and writes:

- `trade_scenarios_support_note.md`
- `trade_scenarios.json`

Default paths are under `/tmp/public_equity_investing_long_short_pitch/` unless explicit output paths are supplied. These are support artifacts. The helper is math-only, and the Markdown support note / JSON outputs are not the final user-facing pitch unless the user explicitly requests those formats. The final pitch still needs variant perception, expression, catalyst path, risk/reward, sizing considerations, disconfirmers, and add/trim/exit/cover rules.

## Output Spine

Use this full structure unless the user explicitly asks for a quick/short pitch, red-team-only review, or one section:

1. `Trade Recommendation`
2. `Variant Perception`
3. `Security / Expression`
4. `Why Now / Catalyst Path`
5. `Scenario Price Targets / Returns`
6. `Risk / Reward and Sizing Considerations`
7. `Disconfirmers and Kill Criteria`
8. `Add / Trim / Exit / Cover Rules`
9. `Monitoring Dashboard`
10. `Open Items / Data Requests`

Load `references/output-contract.md` for full section requirements and `references/strategy-playbooks.md` for long, short, pair, and event-driven equity pitch rules.

For sparse-context outputs, use the full spine with `screen-grade` labels and visible missing data. Use the narrower contracts in `references/output-contract.md` only when the user explicitly requests a partial section or compressed format.

## HTML Guidance

For a substantive standalone HTML trade-pitch report, load `../../shared/html-artifact-standard.md` and apply these pitch-specific requirements:

- Make actionability the primary visual object. Lead with the proposed posture (`initiate`, `watchlist`, `pass`, `cover`, or `wait for proof`), side and preferred expression if supportable, horizon, variant wedge, and the decisive implementation caveat.
- Immediately after the opening verdict, show a compact `Implementation Gate` block covering the trade-critical checks: catalyst, valuation or price anchor, liquidity, borrow/carry and squeeze/buyback risk for shorts, option cost/skew when relevant, and hedge ratio/residual exposure for pairs. Mark each as `Cleared`, `Not cleared`, `Missing`, or `Illustrative only`.
- Give the verdict, variant wedge, implementation gate, scenario skew, catalyst path, and action rules distinct jobs. Do not repeat the same recommendation in multiple large panels.
- Keep `What Is Priced In` explicit: distinguish demonstrated operating improvement from the expectation or valuation assumption a proposed trade would challenge.
- For shorts, put borrow, carry, crowding, squeeze/buyback exposure, preferred defined-risk expression if assessable, catalyst timing, and cover rule near the top rather than burying them in monitoring.
- For partnership, capacity, purchase, cloud-spend, or customer-commitment metrics shown in the first-read layer, name the economic direction explicitly. For example, label an issuer spending commitment `AWS Infrastructure Commitment` or `Snowflake AWS Spend Commitment` and state that it is not incremental revenue guidance unless the source establishes revenue.
- Title unsupported target/probability work `Illustrative Scenario Skew` when valuation support, borrow/carry, option pricing, or other implementation evidence is incomplete. Label targets and probabilities as analyst assumptions rather than company guidance, consensus, or externally validated price targets. Do not describe expected return as actionable until holding costs and constraints have been addressed.
- In standalone HTML, title the monitoring section `Monitoring Triggers` or `Evidence To Watch`; reserve `Monitoring Dashboard` for the explicitly selected standardized-dashboard path. When the proposed posture is `watchlist`, `pass`, or `wait for proof` with no current position, title action discipline `Conditional Action Rules` rather than implying an active position.
- Render evidence posture in plain investor language such as `Reported`, `Company guidance`, `Derived`, `Analyst assumption`, or `Not yet sourced`; do not expose internal evidence or schema labels in the visible report.
- Keep citations traceable but readable: do not fragment tickers, fiscal years, dates, percentages, numeric ranges, metric names, or product labels into separately linked tokens. Do not make an analyst assumption register appear to be an external evidentiary source.
- Do not render empty scenario fields, empty lists, decorative monitoring inventory, or repeated panels that do not sharpen expression or action discipline.
- Visually inspect local HTML via local headless-browser screenshots, not the in-app Browser plugin, and iterate on hierarchy, density, clipping, citation rendering, and whether the proposed trade decision is immediately usable.

## Handoffs

- Source discipline: `financial-source-of-truth`, `financials-normalizer`
- Earnings/post-print: `earnings-preview`, `earnings-deep-dive`
- Valuation/model inputs: `dcf-model-builder`, `three-statement-model-builder`, `comps-valuation`, `scenario-sensitivity-generator`
- Trade risk: `portfolio-risk-management`, `thesis-tracker`
- Event foundations: `event-driven-analyzer`
- Equity-risk credit-signal inputs: use Credit Markets when credit instruments, creditworthiness, restructuring, distressed, recovery, spreads, yields, covenants, or debt-security analysis drive the case
- Formal memo synthesis: `memo-builder`

Use `sector-context-overlay` only when the issuer clearly matches a supported sector; use `references/sector-overlays.md` only for pitch-specific framing.

## QA Self-Check

Before finalizing:

- recommendation, side, expression, horizon, and caveat are clear
- sparse-context outputs lead with a stance rather than a placeholder template
- variant perception is not just "good company / bad company"
- catalyst path is actionable
- upside/downside math is internally consistent and probabilities sum to 100% when presented
- short pitches include borrow/carry/squeeze/cover discipline when data is available
- pair trades include hedge ratio, residual exposure, and break conditions
- credit-first pitches route to Credit Markets unless the final expression is common equity and credit is only an input
- missing live market data is labeled before any metric table
- partial-section requests answer only the requested section, plus trade implications and missing data; ambiguous broad pitch requests default to the full pitch
- action rules are evidence-based and not account-specific instructions
- ordinary standalone HTML pitches use actionability-first hierarchy and do not expose internal evidence labels or empty dashboard modules
- illustrative scenarios are clearly labeled when valuation anchors or implementation inputs are incomplete
- standalone HTML watchlist or no-position pitches use conditional action and monitoring-trigger language rather than dashboard or active-position headings

## Public Equity PM Judgment Layer

For substantial pitches, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

Use this PM-native spine: `Proposed Trade / Actionability`, `Variant Wedge`, `What Is Priced In`, `Expression and Risk Budget`, `Scenario Skew`, `Catalyst Path`, `Disconfirmers`, `Add / Trim / Exit / Cover`, `Monitoring`.

Required PM judgment:
- Shorts require borrow, carry, squeeze path, buyback/low-float risk, catalyst timing, and cover rules when data is available or clearly missing.
- Pairs require hedge ratio, residual exposures, liquidity mismatch, catalyst symmetry, and break conditions.
- ETF/index can be a hedge, basket expression, benchmark-relative pair, or index rebalance/event setup.
- Preserve non-advice posture: discuss proposed expression and risk controls, not account-specific trade execution.

Referenced files: 8

View saved version →

---
name: meeting-prep
description: Use when creating Public Equity Investing meeting prep briefs. Do not use for private diligence, IB, FP&A, legal, or scheduling-only tasks.
---

# Meeting Prep

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the catalogued source categories needed for the current meeting. Prefer a user-named source first, then one available app, connector, file, export, or pasted input that satisfies the category. Attempt the smallest useful native read only when the workflow needs that source. If a route needs auth, connection, or setup, state the practical limitation and continue from prompt context, active artifacts, pasted or exported material, and public sources when the meeting brief can still be useful. Do not inspect unrelated source categories, run broad source setup, write connector readiness, or create, read, migrate, or update `category-state.json`.

The runtime source categories below cover the catalogued Public Equity Investing sources. Use `references/context-and-sources.md` for the broader evidence hierarchy, including optional meeting-logistics connectors.

### Workflow Sources

When this skill uses a source category, use it for the following information. These are semantic source categories, not fixed connector names.

- `company_filings_ir`: filings, IR materials, and reported financials needed for the meeting baseline.
- `earnings_transcripts_presentations`: transcripts, presentations, events, and recent management commentary needed for question planning.
- `internal_research`: internal notes, expert context, and team discussions when they materially improve the meeting plan.
- `portfolio_models_trackers`: portfolio context, watchlists, models, and thesis trackers only when they materially change the investor stance or follow-up.
- `market_data_estimates`: market data, consensus, estimates, and ownership only when they materially change the investor stance or questions.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Internal Research`
- `Company Filings & IR`
- `Earnings Transcripts & Events`
- `Portfolio Models & Trackers`
- `Market Data & Estimates`

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For a substantive reusable meeting-prep packet or explicit HTML meeting brief, the default resolves the presentation surface to a polished standalone HTML live-meeting brief unless the user requests another surface, a quick/no-file answer, or a standardized dashboard. In interactive runs, ask only remaining material choices such as depth, audience/use, meeting type, or focus; in non-interactive runs, default to the HTML live-meeting brief and `Full working analysis` while disclosing those assumptions outside the artifact. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

## Mission

Create decision-useful Public Equity Investing meeting readiness: what to ask first, what to listen for, how to follow up if the answer is evasive, what not to say, what evidence to request, what decisions to drive, and what follow-ups to send. For a live meeting, the prep sheet is a conversation tool, not a general research report.

Default prep bundle:

1. meeting objective, investor stance, and compact verified baseline;
2. conversation flow: opening frame, lead question, pressure-test, and close;
3. three or four must-ask questions ranked by decision impact, with listen-fors and evasive-answer follow-ups;
4. compact must-know context, time-permitting questions, and evidence requests;
5. likely pushbacks, compliance boundaries, and what not to ask or say;
6. follow-up/action tracker;
7. source log and material open gaps.

Preserve existing briefs, decks, memos, spreadsheets, trackers, and notes. Add new outputs, comments, suggested edits, speaker notes, or change logs unless the user explicitly asks to modify the original.

Use chat for quick prep. For a substantive reusable prep packet or explicit HTML meeting brief, produce a polished standalone HTML live-meeting brief following `../../shared/html-artifact-standard.md`; let the meeting type and decision needed determine the hierarchy. Keep background research proportional to its utility in the conversation: do not turn meeting prep into an earnings deep dive, tearsheet, or initiation report merely because HTML space is available.

Use `dashboard-builder` only when the user explicitly asks for a standardized dashboard, reusable dashboard template, or structured payload-driven render. For that optional route, use `references/DASHBOARD_PACK.md`: `meeting-prep` owns the meeting objective, context, question sequencing, evidence requests, pushbacks, and follow-up logic; `dashboard-builder` owns the standardized shell/rendering/QA. Build a `public_equity_investing_dashboard.v1` payload as an internal renderer input, and keep JSON/Markdown/CSV support files behind the HTML dashboard unless explicitly requested.

## Public Equity Investing Boundary

Use this skill for meetings tied to public securities, listed issuers, equity-risk credit signals, event-driven situations, sector research, PM/risk reviews, earnings, investor days, conferences, expert calls, and public-equity-investing client or committee discussions. Route credit-instrument, creditworthiness, covenant, recovery, restructuring, and debt-security meetings to Credit Markets.

Do not use this skill as the lead owner for private-markets diligence, investment-banking pitch or process meetings, corporate FP&A or operating-cadence meetings, legal/regulatory/contract meetings, or scheduling-only tasks.

If the user asks for those non-local workflows, route to the appropriate plugin/tool when available or state that the workflow is non-local to Public Equity Investing.

## Workflow

1. **Determine mode.** Build from scratch, refresh existing prep, turn analysis into call prep, prepare for a specific meeting, prepare follow-ups, or review/upgrade an existing prep packet.
2. **Infer audience and meeting type.** Management/IR, issuer, PM, client, committee, expert, earnings, investor day, credit, risk, portfolio review, model review, catalyst prep, or research kickoff. Load `references/meeting-type-playbooks.md` when needed.
3. **Build context pack.** Start with the prompt and active artifacts. Use runtime apps/connectors only when they are actually callable. Do not imply calendar, email, Slack, Drive, market-data, or research connectors are available if they are not.
4. **Handle sparse context.** With no context, produce starter prep plus data request list. With partial context, label assumptions and prioritize decision-changing gaps. With full context, produce tailored questions, evidence requests, likely responses, and follow-ups. Do not reproduce a long issuer or earnings background unless it changes the meeting plan.
5. **Compose with local skills.** Use source, tearsheet, memo, style, QC, scenario, audit, model, earnings, event, risk, hedge, thesis, or sector skills when meeting prep depends on their domain. Use Credit Markets as a handoff for credit-first meeting prep.
6. **Create brief.** State why the meeting matters now, what decision/information is needed, what is known/assumed, the must-ask questions in meeting order, what to listen for, what follow-up to use if an answer remains qualitative or evasive, evidence requests, pushbacks, and action items.
7. **Prepare follow-ups if post-meeting.** Capture decisions, new facts, changed assumptions, open questions, evidence requests, commitments, owners, dates, dependencies, and draft follow-up language if useful.

## First-Class Meeting Modes

Support these modes explicitly: `management_ir`, `expert_call`, `pm_internal_review`, `investment_committee`, `client_update`, `sell_side_call`, `earnings_call`, `investor_day`, `portfolio_watchlist_review`, `model_review`, `research_kickoff`, and `post_meeting_follow_up`.

For every mode, rank questions by decision impact, include what not to ask or say, identify evidence requests, anticipate likely pushbacks, and assign follow-up actions. For a finite live conversation, make three or four questions the must-ask set and place additional questions in an `If Time Permits` block. Tie every must-ask question to an estimate, valuation, thesis, catalyst, sizing, or monitoring consequence. The senior PM layer should press on what would change the view, what evidence is missing, what answer would be evasive, what the market already knows, and what should route to a model, memo, thesis tracker, sizing review, or Credit Markets handoff.

## HTML Guidance

For a substantive standalone HTML meeting brief, load `../../shared/html-artifact-standard.md` and apply these meeting-specific requirements:

- Make the live conversation plan the primary visual object. Lead with the meeting objective, one-sentence investor stance, core decision or information gap, and a compact disclosed baseline.
- Place a compact `Conversation Flow` block immediately after the opening stance/baseline and before detailed question cards or extended background. It should show the opening frame, lead question, pressure-test, and close/evidence request at a glance.
- For `management_ir`, `sell_side_call`, `expert_call`, `earnings_call`, or `investor_day`, display three or four must-ask questions after the conversation flow and before extended background. For each, show `Why it matters`, `Listen for`, `If evasive`, and `Model / thesis implication` or the closest decision consequence.
- Keep each must-ask subfield concise enough for live use: generally one short sentence, and no more than two short sentences where material nuance would otherwise be lost.
- Put secondary questions in a compact `If Time Permits` block. Do not render a long list of equally weighted question cards.
- Keep the disclosed baseline short: usually four or five facts or metrics that make the questions intelligible. Detailed historical tables, scenario work, and extended industry context belong only when they change a live question or follow-up.
- Include a usable conversation-flow block before detailed questions: opening frame, first question, productive follow-up if management remains qualitative, and closing evidence request or next public disclosure to monitor.
- Keep the compliance boundary visible for external meetings: public-disclosure-only posture, prohibited asks, and clean ways to restate questions without seeking material nonpublic information.
- Give the headline, stance box, baseline, and question plan distinct jobs. Do not repeat the same conclusion across several visible panels.
- Keep citations traceable but readable: do not fragment company names, product names, periods, dates, numeric ranges, or metric labels into separately linked tokens.
- Visually inspect local HTML via local headless-browser screenshots, not the in-app Browser plugin, and iterate on hierarchy, density, clipping, citation rendering, and whether the must-ask questions are quickly usable in a live meeting.

## When To Invoke Support

Load `shared/support-layer-routing-contract.md` when support services are needed. Use `financial-source-of-truth` for verified facts, claims, citations, and source gaps; use `company-tearsheet`, `financials-normalizer`, or `excel-data-cleaner` for issuer/table prep; use `deck-report-qc` for pre-read/circulation review; use `style-guide-adapter` only after substantive prep is locked. Support artifacts stay secondary to the live-meeting brief or optional standardized dashboard.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: source pack, company and market context, key questions, risk flags, and follow-up tracker. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Quality Bar

The objective is explicit, the brief is usable during the meeting, facts and assumptions are separated, material source gaps are visible, must-ask questions are sequenced by decision impact, evasive-answer follow-ups and decision consequences are clear, evidence requests are specific, likely objections are covered, action items have owner/timing where available, and no source artifact is modified or deleted without permission.

## Reference Map

- `references/context-and-sources.md`: source hierarchy and optional connector behavior. Treat connectors as optional runtime inputs.
- `references/meeting-type-playbooks.md`: persona and meeting-type modules.
- `references/question-and-evidence-bank.md`: question and evidence-request patterns.
- `references/follow-up-and-action-tracking.md`: debrief and tracker fields.
- `references/output-templates.md`: standard brief formats.
- `references/safety-and-integrations.md`: non-destructive editing and circulation rules.

Referenced files: 9

View saved version →

---
name: memo-builder
description: Use when drafting or reviewing formal public-equity investment memos. Do not use for live trade construction or credit-first memos; use long-short-pitch or Credit Markets as appropriate.
---

# Memo Builder

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Internal Research`
- `Portfolio Models & Trackers`
- `Market Data & Estimates`
- `Company Filings & IR`
- `Earnings Transcripts & Events`

## Deliverable Intake

Before source gathering or analysis for a new substantive 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.

## Goal

Produce decision-grade Public Equity Investing memos that are evidence-led, numerically auditable, and ready for PM, committee, client, or internal research review.

This skill owns formal written artifacts and synthesis. It does not own raw trade construction; use `long-short-pitch` first when the user needs variant perception, trade expression, sizing considerations, add/trim/exit/cover rules, or pair-trade mechanics.

## Use When

Use this skill when the user asks for:

- IC memo, investment memo, committee note, client memo, research note, PM update, or equity event note
- memo rewrite, upgrade, shortening, pressure test, or QA review
- synthesis of outputs from models, comps, scenarios, earnings, event-driven equity, balance-sheet-risk, or long/short pitch work
- committee-ready framing with source posture, valuation, scenarios, risks, catalysts, open items, and recommendation

Credit-first memos route out: Use Credit Markets for credit instruments, creditworthiness, restructuring, distressed, recovery, spreads, yields, covenants, and debt security analysis. This skill may synthesize Credit Markets output only when the final deliverable is a common-equity or listed-equity memo.

Do not use when the user asks to "pitch this long/short," "make this investable," "build a pair trade," "what is the variant perception," or "what would make us cover/add/trim." Use `long-short-pitch`.

## Artifact Boundary

- Default deliverable: produce the full decision-grade memo in the selected or high-confidence inferred surface. For formal investment committee, PM, committee, client, or research memo circulation, use a real Word document (`.docx`) as the normal recommended surface. For high-confidence source-heavy web-style investment reports, use a polished standalone HTML report following `../../shared/html-artifact-standard.md`. For quick or conversational memo updates, inline response can be the recommended surface.
- If the surface is semi-ambiguous, use `../../shared/deliverable-intake-policy.md` before drafting and let the chosen or timeout-resolved option control the hero deliverable.
- Chat can be the presentation surface for narrow or conversational memo requests, but Markdown is formatting, not the deliverable contract.
- This skill ships `scripts/build_memo_package.py`, which can generate a real DOCX memo and an HTML companion, or HTML as primary with a DOCX companion. If DOCX is selected, generate the full memo in DOCX; do not treat DOCX as a thin companion to HTML.
- Route workbook-backed outputs to the model/workbook skills and create `.xlsx` artifacts only when the user selects or clearly implies a model, tracker, valuation, or workbook surface.
- Use `dashboard-builder` only when the user explicitly asks for a standardized dashboard, reusable dashboard template, PM cockpit, or structured payload-driven render. On that path, load `references/DASHBOARD_PACK.md`; `memo-builder` owns memo synthesis, narrative architecture, evidence selection, and audience framing, while `dashboard-builder` owns the standardized shell/rendering/QA. Build a `public_equity_investing_dashboard.v1` payload as an internal renderer input.

## Source And Mode Selection

Use the strongest available source tier and label assumptions, stale data, proxies, and unsupported figures. Load `references/source-policy.md` for source priority and minimum inputs.

Default to the full memo mode that best fits the decision. Use a compressed mode only when the user explicitly asks for a `summary`, `short`, `quick`, `one-page`, `brief`, `TL;DR`, or review-only output:

- `ic-note`
- `investment-memo`
- `event-driven-committee-note`
- `pm-update`
- `client-research-note`
- `qa-review`

Load `references/memo-modes.md` for mode selection and `references/output-contracts.md` for section-level contracts.

## When To Invoke Support

Load `shared/support-layer-routing-contract.md` for source/data/QC/style support. Use `financial-source-of-truth` before final claims, metrics, citations, or management assertions. Use `financials-normalizer` before building from messy financials, consensus exports, guidance tables, segment data, share count, net debt, or capital allocation inputs. Use `excel-data-cleaner` before relying on malformed tables or mixed fiscal periods. Use `deck-report-qc` before circulating a memo-derived deck/report or source-heavy packet, and use `style-guide-adapter` only after substance is locked. These support artifacts stay secondary; `memo-builder` owns the memo and investment judgment.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: evidence, model/valuation, risks and catalysts, narrative synthesis, and memo QA. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Default Memo Spine

Use this full spine unless another memo mode is clearly requested:

1. `Recommendation / Decision Ask`
2. `Executive Summary`
3. `Thesis and Evidence`
4. `What Must Be True`
5. `Valuation / Scenario Work`
6. `Risks, Disconfirmers, and Mitigants`
7. `Catalysts and Monitoring`
8. `Implementation Considerations`
9. `Open Items / Data Requests`

If the memo is screen-grade because source context is thin, say so before the first metric table.

## Handoffs

Upstream inputs this skill can synthesize:

- source/evidence: `financial-source-of-truth`, `financials-normalizer`, `company-tearsheet`
- models/valuation: `equity-model-update`, `dcf-model-builder`, `three-statement-model-builder`, `comps-valuation`, `scenario-sensitivity-generator`
- earnings/research: `earnings-preview`, `earnings-deep-dive`, `initiating-coverage`
- trade/event/risk: `long-short-pitch`, `event-driven-analyzer`, `portfolio-risk-management`
- monitoring and QC: `thesis-tracker`, `catalyst-calendar`, `deck-report-qc`, `style-guide-adapter`

Use `sector-context-overlay` only when issuer economics clearly match a supported sector; load `references/sector-overlays.md` only for memo-specific sector framing.

## Rendering And Compression

- Lead with the decision ask or conclusion.
- For a standalone HTML investment committee memo, make the first-read layer a compact memo opening: recommendation / decision ask, decision hinge, what is priced in, valuation or scenario skew, and any source limitation that changes the action. Do not repeat the same recommendation across a dashboard-style hero, summary tile, and full decision panel.
- Keep background proportionate; preserve recommendation, scenario/downside, source posture, catalysts, monitoring, and open items.
- Use tables only when they compress decision-critical information.
- For long memos, put source caveats and open items near the end, but do not bury data limitations that affect the recommendation.
- Sparse source context should produce a full screen-grade memo skeleton with assumptions, missing evidence, and upgrade path, not a shortened memo.
- State source readiness in decision-specific terms when evidence supports only one direction of action, such as `sufficient to decline initiation today; insufficient to support initiation`, rather than using broad readiness labels that imply the entire underwrite is decision-grade.
- Keep citations traceable but readable in HTML: do not fragment tickers, prices, EPS ranges, percentages, dates, multiples, or metric labels into separately linked tokens.
- Before delivering standalone local HTML, visually inspect the opening viewport and decision-critical downstream sections through local headless-browser screenshots, not the in-app Browser plugin. Check desktop and narrow-screen legibility, clipping, citation density, whitespace, and that the page does not acquire horizontal overflow.
- When delivering DOCX, ensure the document itself contains the full memo spine, including recommendation, decision hinge, thesis/evidence, valuation or scenario view, risks, catalysts, source posture, and open items. The HTML report may be a companion, but the DOCX must be usable as the first-read artifact on its own.

## QA

Before finalizing, verify:

- recommendation and decision hinge are clear
- material numbers are sourced, model-derived, or explicit assumptions
- downside is mechanistic, not generic
- `what must be true` items are measurable
- valuation/pricing/recovery support matches memo type
- a multi-year valuation using forward-period earnings and an exit or terminal multiple shows either present value using an explicit discount-rate / required-return assumption or annualized return / IRR versus a stated hurdle; undiscounted terminal price appreciation alone does not support initiation
- disconfirmers and monitoring triggers are present
- trade-construction asks are handed to `long-short-pitch`

Load `references/quality-workflow.md` for the full quality bar and workflow.

## Script Map

When deterministic packaging from structured memo inputs is appropriate, use `scripts/build_memo_package.py --primary-format docx` or `scripts/build_memo_package.py --primary-format html` according to the selected memo surface. The script writes both reader-facing surfaces plus a manifest; the selected primary format controls the manifest's first-read artifact.

## Public Equity PM Judgment Layer

For substantial memos, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

Memo modes to support: `buy-side-investment-memo`, `pm-update`, `sell-side-research-note`, `client-research-note`, `etf-index-diligence-note`, and `public-equity-diligence-memo`.

Required PM judgment:
- Every full memo needs a decision hinge, what must be true, what is priced in, downside mechanism, measurable disconfirmers, source posture, and action discipline.
- Build-from-scratch memo mode must include an intake checklist, source packet requirements, first-pass house view, variant wedge, priced-in debate, estimate path, valuation/skew, downside mechanism, catalysts, disconfirmers, action rules, and exact evidence needed to upgrade from screen-grade to decision-grade.
- Sell-side notes need rating/target-price debate, estimate revision bridge, variant versus Street, risk-to-rating, and compliance-safe wording.
- ETF/index notes need mandate, methodology, holdings/weights, tracking-error or benchmark implications, factor exposure, liquidity, and rebalance/corporate-action risk.

Referenced files: 8

View saved version →

---
name: model-audit-tieout
description: Use when auditing existing Public Equity Investing models or spreadsheets. Do not use to build a new model from scratch.
---

# Model Audit Tie-Out

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Portfolio Models & Trackers`
- `Company Filings & IR`
- `Market Data & Estimates`

## Internal Support

When the audit requires evidence control, generic data cleaning, dashboard rendering, style application, or sector context, route that support through the visible `public-equity-investing` router and its bundled internal playbooks. This visible skill remains the owner of the model-review deliverable.

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For a substantive standalone review of an existing model or explicit HTML model-audit request, the default resolves the presentation surface to a polished standalone HTML model-audit report unless the user requests an alternate surface, a quick/no-file answer, remediation output, or a standardized dashboard. In interactive runs, ask only remaining material choices such as depth, audience/use, materiality, or focus; in non-interactive runs, default to the HTML model-audit report and `Full working analysis` while disclosing those assumptions outside the artifact. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

## Purpose

Review an existing public-equity model, workbook, forecast, valuation file, estimate update, comps workbook, sensitivity deck, or model-derived output and produce a decision-useful audit pack. This skill is a QA layer for formula integrity, source support, assumption hygiene, scenario quality, controls, and decision readiness.

Do not rebuild the model unless the user explicitly asks for remediation. Default to an audit memo, issue log, source tie-out ledger, and prioritized fix list.

The headline output is an audit verdict on permitted use: `Ready`, `Ready with caveats`, `Not ready`, or `Not assessable`. This skill does not turn an unsupported model into an investment recommendation. When required valuation, scenario, or market-price outputs are absent, state that the model or model package cannot support portfolio action until remediated and re-audited.

## Core Principles

- Review before changing; never overwrite formulas, assumptions, outputs, or tabs unless asked.
- Separate model mechanics from investment judgment.
- Tie material outputs to workbook tabs/cells, source documents, or explicit assumptions.
- Prioritize by decision impact, not issue count.
- Escalate unsupported decision drivers even when formulas are mechanically clean.
- Distinguish a broken model from an undocumented or unsupported underwriting assumption, a stale forecast, a missing source bridge, and a missing decision-output layer.
- A three-statement operating model need not itself contain target price or valuation; for portfolio-decision use, require a linked valuation/scenario decision output in the model package before concluding that forecasts support action.
- Label auditor-created stresses as `Illustrative audit sensitivity` unless the user explicitly approves them as revised base-case assumptions.

## Workflow

1. **Confirm audit mandate.** Identify model type, intended model-package scope, decision context, materiality threshold, and requested output. Determine whether the workbook is expected to contain decision outputs or to feed a separate linked valuation/scenario layer.
2. **Run workbook inspection when available.** For `.xlsx` workbooks, use the helper as a starting point:

```bash
python scripts/audit_workbook.py path/to/model.xlsx --out-dir audit_output
```

Dependency note: the helper requires `openpyxl`; install the local dependency file in a fresh environment:

```bash
python -m pip install -r scripts/requirements.txt
```

3. **Map key outputs.** Trace valuation, target-price, estimate, earnings, event, risk, or common-equity downside outputs back to assumptions, formulas, source tabs, and source documents.
4. **Apply formula and workbook controls.** Check inconsistent formulas, hardcodes, broken links, hidden sheets, volatile functions, bypassed assumption tabs, circularity, plugs, unsupported checks, and formulas that do not tie to schedules.
5. **Review first-tab decision readiness.** Flag missing or thin first-visible `Cover` tabs when net read, key outputs, scenario metrics, model status, source posture, warnings/hard failures, chart-ready data, and workbook navigation are buried.
6. **Tie assumptions to evidence.** Use `references/tieout-and-source-checks.md` and `financial-source-of-truth` standards to label primary facts, claims, estimates, assumptions, inferences, and unsupported items.
7. **Review scenarios and downside.** Test whether scenarios focus on true value/risk drivers and whether downside captures liquidity/refinancing risk as common-equity impairment, multiple compression, estimate cuts, cash-burn dilution, or event failure as relevant. Treat auditor-created replacement assumptions or stress math as diagnostic illustrations, not repaired model forecasts.
8. **Build issue log.** Include severity, finding type, category, location, finding, decision impact, recommended fix, and owner. Use reader-facing finding types: `Formula/control defect`, `Source contradiction`, `Unsupported assumption`, `Missing forecast refresh`, `Missing decision output`, or `Not comparable without bridge`.
9. **Deliver audit pack.** Choose rapid screen or full audit pack based on user need.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: workbook controls, formula review, source tie-out, scenario/downside review, and issue prioritization. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Output Contract

**Rapid screen**

- model health score;
- top issues by severity;
- decision readiness;
- immediate fixes.

**Full audit pack**

Default substantial workbook audits to a reader-facing `model_audit_report.html`, produced as a polished standalone HTML model-audit report following `../../shared/html-artifact-standard.md`, plus an optional `model_audit_issues.xlsx` companion workbook. Keep `model_audit_findings.json`, `formula_exception_log.csv`, `source_tieout_ledger.csv`, raw workbook maps, and support notes behind the HTML/workbook unless the user asks for audit files. In the default delivery message, link only the primary HTML report and any requested user-facing workbook; mention supporting audit files without linking them unless the user asks.

- executive summary;
- readiness posture;
- issue log;
- formula/workbook controls;
- source tie-out findings;
- assumption and scenario critique;
- sensitivity review;
- remediation sequence;
- open evidence requests;
- appendix with formula exceptions and tie-out ledger.

Use `dashboard-builder` and `references/dashboard-map.md` only when the user explicitly requests a standardized dashboard, reusable validated template, model-health cockpit, remediation tracker, or structured payload-driven render. A substantial ordinary audit should remain a flexible standalone HTML report rather than a fixed dashboard-module package.

## HTML Guidance

For a substantive standalone HTML model-audit report, load `../../shared/html-artifact-standard.md` and use this audit-specific hierarchy:

1. Audit verdict and permitted use: whether the model may support the stated decision, the top blocker, the scope reviewed, and any limitations on recalculation or source verification.
2. Critical blockers and what appears mechanically sound, separated clearly so a linked workbook is not confused with an underwritten forecast.
3. Decision-output assessment: whether a linked valuation/scenario layer, current-price anchor, estimate bridge, or downside view exists and is supportable for the requested use.
4. Priority issue log with workbook location, finding type, decision impact, and remediation.
5. Source tie-out findings, diagnostic sensitivities, controls, remediation sequence, evidence requests, and method/limitations.

Additional rules:

- Keep the headline as an audit verdict. When decision outputs are absent or unreliable, say `Do not use for portfolio action until remediated and re-audited`; do not imply an `add`, `trim`, `exit`, `hedge`, or `wait for proof` recommendation from an audit-only mandate.
- Classify decision-relevant findings as `Formula/control defect`, `Source contradiction`, `Unsupported assumption`, `Missing forecast refresh`, `Missing decision output`, or `Not comparable without bridge`; do not make every unsupported forecast assumption sound like a formula error.
- Display auditor-created cash, leverage, EPS, valuation, or scenario stresses as `Illustrative audit sensitivity`; do not represent a diagnostic stress as a corrected forecast or revised base case.
- When reviewing an operating or three-statement model, distinguish absence of valuation inside that workbook from absence of a linked valuation/scenario decision output in the overall package. The latter blocks portfolio-decision use when required by the mandate; the former is not automatically a model defect.
- Do not feature a current-price or market-data anchor in the verdict, headline KPI row, or decision-output assessment unless the cited source has been verified for the correct security and as-of date; if it cannot be verified, state that the external price anchor is unavailable.
- Cite critical findings with workbook sheet/cell or range plus controlling source location where available. Keep source/as-of posture and limitations such as cached outputs versus native recalculation visible.
- Visually inspect local HTML via local headless-browser screenshots, not the in-app Browser plugin, and iterate on hierarchy, legibility, table density, citation rendering, and whether the audit verdict and top fixes are immediately visible.

## Handoffs

- `financial-source-of-truth`: evidence hierarchy, stale/conflicting data, citations, labels.
- `excel-data-cleaner`: malformed tables or unclear row/column grain before audit.
- Model/research builders: rebuild, refresh, expand, or stress-test after audit.
- `memo-builder`: convert audit findings into a decision memo.
- `deck-report-qc`: reconcile audited model outputs to decks, board packs, IC memos, or client presentations.

## Resources

- `scripts/audit_workbook.py`: static workbook inspection helper.
- `scripts/requirements.txt`: workbook helper dependency declaration.
- `references/audit-playbook.md`: audit modes by model type.
- `references/formula-and-workbook-controls.md`: formula and architecture checks.
- `references/tieout-and-source-checks.md`: source tie-out process and evidence labels.
- `references/issue-taxonomy.md`: severity and issue categories.
- `references/output-templates.md`: audit memo, issue log, tie-out ledger, and IC-ready templates.
- `references/dashboard-map.md`: dashboard mapping for model health, formula exceptions, source tie-outs, and readiness.
- `references/p0-integrations.md`: coordination with launch skills.

## Final QA

Confirm severity is tied to decision impact, model issues are separated from evidence issues, audit sensitivities are identified as illustrative rather than repaired forecasts, missing decision-layer scope is not confused with a formula defect, source/as-of dates are visible, unsupported assumptions are not buried, remediation steps are concrete, and no user workbook content was destructively changed.

## 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.

Referenced files: 10

View saved version →

---
name: portfolio-risk-management
description: Use when sizing Public Equity Investing positions, finding equity hedges, or building an integrated position-and-hedge risk plan from a listed-equity thesis. Do not use for thesis construction, standalone event underwriting, trade execution, personal investment advice, or credit-instrument risk.
---

# Portfolio Risk Management

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Portfolio Models & Trackers`
- `Market Data & Estimates`
- `Internal Research`

## Internal Support

When this workflow needs rendering, evidence/data preparation, style, or sector context, route support through the visible `public-equity-investing` router and its bundled internal playbooks. Route workbook or model QA through the visible `model-audit-tieout` workflow.

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For a substantive integrated position-and-hedge plan or explicit HTML risk-plan request, the default resolves the presentation surface to a polished standalone HTML risk decision report unless the user requests another surface, a quick/no-file answer, workbook output, or a standardized dashboard. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

## Purpose

Turn a listed-equity investment view into an implementable risk posture: the right size, any appropriate hedge, the exposure intentionally retained, and the rules for resizing or removing protection. This skill owns equity longs, equity shorts, pair trades, ETFs/index constituents, listed options, equity factor hedges, futures/index overlays, and macro proxies when the decision remains a public-equity decision.

Do not treat sizing and hedging as independent answers when one changes the other. Size from the tightest credible constraint; hedge only risks that can be reduced without destroying the intended alpha. A size-down/no-hedge outcome is valid when hedge basis risk, cost, liquidity, or complexity is worse than the unwanted exposure.

For a substantive reusable risk package, produce a polished standalone HTML risk decision report following `../../shared/html-artifact-standard.md`; retain the structured decision-sheet strengths of sizing tables, hedge comparisons, scenarios, and monitoring triggers without forcing a standardized dashboard shell. Use `dashboard-builder` only when the user explicitly asks for a standardized dashboard, recurring monitoring dashboard, reusable validated template, or structured payload-driven render.

## Mode Selection

Infer the mode from the requested decision and available context:

| Mode | Use when | Core output |
| --- | --- | --- |
| `position_sizing` | The user asks how much to own or short, add/trim/exit thresholds, loss budgets, liquidity capacity, or portfolio exposure impact. | Recommended size, binding constraint, scenario P&L, liquidity exit, monitoring rules. |
| `hedge_design` | The user asks how to hedge, neutralize, protect, de-beta, rank hedge candidates, or compare hedge instruments. | Hedge objective, candidate set, basis-risk ledger, sizing method, readiness checks, exit rules. |
| `integrated_risk_plan` | The user asks for both position size and hedge, or the hedge choice could materially change recommended size. | Unhedged versus hedged/size-down comparison, recommended package, retained exposure, action rules. |

Do not ask the user to choose a mode when the prompt or supplied artifact makes the decision clear. Ask one targeted clarification only when selecting the wrong mode would materially change the deliverable, such as an ambiguous request to "manage risk" without a stated position, unwanted exposure, or requested action.

## Public Equity PM/Risk Lens

Load `../../shared/pm-judgment-heuristics.md` and `../../shared/credit-markets-handoff.md` before producing a substantial risk recommendation.

Audience modes:

- `long_only_pm`: emphasize benchmark active weight, tracking error, liquidity/capacity, drawdown tolerance, add/trim discipline, and portfolio role.
- `long_short_hf`: emphasize gross/net/beta/factor impact, borrow, short squeeze risk, catalyst path, hedge fit, and cover/resize rules.
- `market_neutral_pairs_pm`: emphasize leg sizing, beta/factor/driver neutrality, residual spread risk, borrow, and liquidity.
- `event_driven_equity_pm`: emphasize adverse gap, timing delay, probability-weighted outcomes, options/borrow liquidity, and event slippage.
- `etf_index_benchmark_pm`: emphasize constituent weight, active weight, ETF/index flow exposure, rebalance risk, liquidity, and tracking-error impact.

Every substantive output must state intended alpha, unwanted risk, retained exposure, binding constraint, liquidity/exit posture, hedge or size-down tradeoff, monitoring triggers, implementation readiness, and missing evidence that could change the decision. Include basis risk and a hedge-failure scenario whenever protection is proposed.

## Boundary With Credit Markets

This skill may use CDS levels, credit spreads, ratings, maturity walls, refinancing pressure, covenant headlines, or liquidity stress only as common-equity downside signals.

Use CDS/spreads only as common-equity risk context. CDS levels and credit spreads may appear only as equity-risk signals or common-equity downside context; never treat them as a locally owned hedge implementation.

Use Credit Markets for CDS, bonds, loans, spread DV01/CS01, credit spread hedges, capital-structure hedges, distressed hedges, recovery waterfalls, covenant analysis or covenant hedges, debt-security sizing, and credit-security relative value. Do not present a credit instrument as a local hedge recommendation.

## Do Not Use

- Thesis, variant perception, or pitch construction: use `long-short-pitch` or `memo-builder`.
- Dated event probability and payoff underwriting: use `event-driven-analyzer`.
- Macro/economic transmission mapping: use `economic-impact-report`.
- Catalyst calendar or monitoring-only work: use `catalyst-calendar` or `thesis-tracker`.
- Personal investment advice, trade execution, or legal/compliance conclusions.

## Context Modes

| Context | Default behavior |
| --- | --- |
| No context | Request the security/exposure, desired action, horizon, constraints, and available data; provide a usable intake frame without inventing a recommendation. |
| Partial context | Produce a conditional risk screen or screen-grade integrated plan with explicit assumptions and missing-data checks; do not recommend initiation when required implementation inputs are missing. |
| Full source | Normalize inputs, tie out sources, run scenarios, and produce decision-ready risk guidance. |
| Review or refresh | Preserve prior work, identify stale inputs and hidden exposures, and show what changes the size or hedge. |

## Workflow

1. **Define the decision.** Capture security, direction, current/proposed size, thesis exposure to retain, unwanted risk, price/as-of time, horizon/catalyst, portfolio context, mandate limits, liquidity, and requested action.
2. **Resolve the loss-budget interpretation.** Distinguish a `scenario loss budget`, which constrains loss under a stated adverse move, from an `absolute loss cap`, which must remain satisfied even if the stock moves beyond that scenario. When the user gives a loss limit for a short but does not say which interpretation applies, ask one targeted clarification in an interactive run. In a non-interactive run, show both branches and do not silently turn an assumed squeeze magnitude into an initiation recommendation. For a short with an absolute cap, require priced defined-loss protection or recommend no position.
3. **Map exposures.** Separate intended idiosyncratic, event, and chosen factor/macro exposures from unwanted beta, sector, factor, FX, commodity, liquidity, borrow, financing, crowding, gap, and portfolio-concentration risk.
4. **Build risk cases.** Estimate upside/base/downside/stress outcomes, probability-weighted return when supportable, scenario P&L, liquidity/exit implications, and any hedge-failure case. Label assumed stress magnitudes as illustrative until confirmed by the user or a governing risk policy.
5. **Apply the selected mode.**
   - For `position_sizing`, triangulate loss-budget, volatility, liquidity, exposure-limit, benchmark/factor, borrow/squeeze, catalyst, and portfolio-fit constraints; recommend the most restrictive credible size.
   - For `hedge_design`, classify exposures as keep, hedge, reduce, or monitor; evaluate direct equity, ETF/index, factor, pair, listed-option, futures/index, causal macro-proxy, portfolio-overlay, and no-hedge/size-down alternatives.
   - For `integrated_risk_plan`, compare unhedged size, hedged size, and size-down/no-hedge outcomes; recommend the package with the clearest retained alpha and acceptable cost/basis risk.
6. **Assess feasibility.** State market-data freshness, ADV/exit days, borrow/recall/squeeze constraints, option chain/Greeks where relevant, cost/carry, basis risk, mandate/compliance checks, and implementation-readiness gaps. For a short recommendation, current executable quote, ADV/exit capacity, locate/borrow terms, and current squeeze/crowding inputs are required before using `initiate` or other implementation-ready language; live option terms are additionally required before recommending an options hedge.
7. **Recommend and monitor.** If implementation inputs are missing, label the result `Conditional risk screen` or `Not implementation-ready` and state the conditional size/package rather than instructing initiation. Otherwise state recommended size and/or hedge, action, binding constraint, retained exposure, rejected alternative where material, add/trim/exit/cover/resize/roll/remove triggers, confidence, and missing evidence.
8. **Render and inspect when HTML is delivered.** In a standalone HTML report, front-load a compact constraint-interpretation table, conditional or executable action, hedge tradeoff, and missing inputs before entry. Keep citations readable: do not fragment tickers, dates, percentages, basis-point amounts, instrument terms such as `GLP-1`, or scenario labels with inline links. For a local HTML file, inspect the opening viewport and decision-critical downstream sections with local headless-browser screenshots rather than the in-app Browser plugin.

## Reference Map

Load only references needed by the selected mode:

- All substantive modes: `references/source-and-context-protocol.md`, `references/exposure-and-factor-risk.md`, and `references/liquidity-drawdown-scenarios.md`.
- `position_sizing`: `references/sizing-framework.md`, `references/strategy-nuance.md`, `references/position-sizing-output-templates.md`, and `references/quality-control.md`.
- `hedge_design`: `references/hedge-workflow.md`, `references/instrument-playbooks.md`, `references/hedge-output-templates.md`, and `references/hedge-scorecard-schema.md`.
- `integrated_risk_plan`: the sizing and hedge references necessary for the recommended package; avoid loading unused instrument playbooks.
- Standalone HTML deliverables: `../../shared/html-artifact-standard.md` and the selected mode's output template.
- Explicit standardized dashboard deliverables: `references/DASHBOARD_PACK.md`.

## Deterministic Scripts

Use bundled helpers when structured inputs are supplied or the user asks for templates/files:

```bash
python scripts/create_position_sizing_templates.py --out path/to/templates
python scripts/position_sizing_calculator.py --input path/to/input.json --out path/to/outputs
python scripts/score_hedge_candidates.py hedge_candidates.csv --output-dir path/to/outputs
```

The sizing helpers write transparent calculation/audit support files including `position_summary.csv`, `sizing_cases.csv`, `scenario_pnl.csv`, `exposure_impact.csv`, `liquidity_exit.csv`, `monitoring_rules.csv`, `support_note.md`, `run_log.json`, and `manifest.json`. The hedge helper writes `hedge_scorecard_support_note.md`, `hedge_scorecard.csv`, `hedge_scorecard.json`, and `basis_risk_ledger.csv`.

These helpers do not fetch live data, run portfolio risk systems, satisfy compliance checks, or replace PM judgment. CSV, Markdown, JSON, run-log, and manifest files are support artifacts unless the user explicitly asks for those formats. For substantial reusable packages, lead with a polished standalone HTML risk decision report unless the user explicitly requests a standardized dashboard.

## Dashboard Handoff

If the user explicitly asks for a standardized or recurring dashboard, use `references/DASHBOARD_PACK.md`. `portfolio-risk-management` owns size, hedge, retained-exposure, binding-constraint, basis-risk, scenario, liquidity, and monitoring judgment; `dashboard-builder` owns rendering and validation. Build a `public_equity_investing_dashboard.v1` payload as an internal renderer input and keep support files behind the HTML dashboard unless explicitly requested.

## Handoffs

- `long-short-pitch`: establish the thesis and trade expression before risk construction.
- `thesis-tracker`: maintain decision triggers after a position or hedge is adopted.
- `earnings-preview`, `earnings-deep-dive`, `equity-model-update`, `economic-impact-report`, or `event-driven-analyzer`: refresh the underlying equity case before risk work when needed.
- `scenario-sensitivity-generator`: build larger grids or breakevens.
- `financial-source-of-truth`, `financials-normalizer`, `model-audit-tieout`, and `excel-data-cleaner`: de-risk source data or workbook inputs.
- `memo-builder`, `deck-report-qc`, and `style-guide-adapter`: package or circulate a final artifact.

## Output Contract

Default output should include:

1. Decision summary: mode, recommendation or conditional screen status, action readiness, confidence, and binding constraint.
2. Exposure objective: intended alpha, unwanted risk, and retained exposure.
3. Constraint interpretation: scenario loss budget versus absolute loss cap, the assumptions needed for each branch, and the compliant action.
4. Risk/return cases: downside, stress, catalyst/path case, and hedge-failure case when relevant.
5. Sizing recommendation or hedge package, including size-down/no-hedge comparison where material.
6. Portfolio impact, liquidity/exit, cost/carry, basis risk, and readiness gaps.
7. Monitoring rules: add, trim, exit, cover, resize, roll, remove, and re-underwrite triggers as applicable.
8. Sources, assumptions, stale inputs, and open data requests.

Before finalizing a sizing or integrated recommendation, apply `references/quality-control.md`. Before recommending a hedge, confirm it preserves desired thesis exposure, names basis risk and cost/carry, and includes a no-hedge/size-down alternative.

Referenced files: 19

View saved version →

---
name: public-equity-investing
description: Route Public Equity Investing workflows for listed-company and public-security research, earnings analysis, valuation, model updates, long/short pitches, catalysts, thesis tracking, ETF/index and constituent diligence, position sizing, hedging, dashboards, and investment memos. Use when the user is evaluating a public company, ticker, sector, portfolio position, event, earnings setup, or investment thesis through an investor lens, including what is priced in, what is mispriced, what proves or kills the thesis, and what to watch next. Do not use for private-company diligence, credit-first analysis, personal financial advice, generic company summaries, or generic document drafting with no public-equity investment context.
---

# Public Equity Investing Router

## Skill Purpose

Route broad or focused Public Equity Investing intent to one or more explicit-only constituent skills. Treat explicit `@public-equity-investing`, `@Public Equity Investing`, or direct plugin invocation as strong intent to use this plugin, then apply the invocation gate below before substantive work. When the gate passes, choose the narrowest relevant lead skill from the map below, read each exact installed `skills/<skill-id>/SKILL.md` file before using it, and preserve any support-skill sequence from the routing playbook. Prefer a relevant Public Equity Investing sibling when the request overlaps generic company research, market commentary, valuation, modeling, memo, deck, report, catalyst, earnings, or risk work but the actual job is a listed-equity investment decision. Do not answer from the router alone when a focused owner exists.

## Plugin Purpose

Public Equity Investing provides investor-readable workflows for listed-company research, earnings work, valuation, model updates, long/short pitches, catalysts, thesis tracking, event-driven analysis, ETF/index and constituent diligence, sell-side research notes, position sizing, hedging, risk reviews, dashboards, and investment memos. It uses workflow-scoped source setup: connect or request only the source categories a selected investor workflow actually needs, while supporting pasted context, uploaded files, exports, public evidence, existing models, and portfolio trackers as fallback inputs.

## Bundled Path Resolution

Resolve router-owned bundled Markdown paths relative to the directory containing this `SKILL.md` before the first read; do not probe the caller's current working directory. From this router directory, shared references use `../../shared/...`, sibling visible skills use `../...`, and bundled internal support uses `internal-support/...`.

Shell commands explicitly labeled plugin-root-relative are the exception: set the shell working directory to the plugin root (`../..` from this router directory) before running them.

## Invocation Gate

Read `../../shared/invocation-policy.md` before choosing any specialist. If the prompt has neither an explicit Public Equity Investing invocation nor listed-company, public-security, ticker, sector, portfolio position, event, earnings, thesis, catalyst, valuation, model update, or investor-lens context, do not route into this plugin.

# Skills

## company-tearsheet

Use for cited public-company profiles, issuer/ticker verification, business mix, financial snapshot, ownership, trading context, and fact packs that feed investor work.

## initiating-coverage

Use for full initiation reports, investment views, target-price frameworks, thesis/risk sections, valuation support, and coverage-style public-equity writeups.

## earnings-preview

Use before a print for expectation bar, consensus, guidance, KPI setup, management questions, scenarios, watchouts, and pre-earnings investment framing.

## earnings-deep-dive

Use after results, transcript, guidance, call commentary, or price reaction are available and the user needs thesis/model/action implications.

## equity-model-update

Use when an existing public-equity model, workbook, tracker, or source-to-cell map needs actuals, guidance, assumptions, or formula-preserving updates.

## comps-valuation

Use for public comps valuation, peer selection, metric definitions, market-data support, outlier logic, and valuation-range read-through.

## dcf-model-builder

Use for public-company DCF models, WACC, terminal value, EV/equity bridge, price-target support, and sensitivity workbooks.

## three-statement-model-builder

Use for public-company three-statement forecast models, reported actuals, forecast architecture, formula-first workbooks, and model checks.

## long-short-pitch

Use for long, short, or pair-trade pitches, variant perception, trade expression, catalyst path, risk/reward, sizing considerations, and exit or cover rules.

## idea-generation

Use for idea screens, watchlist triage, thematic or universe scans, exclusions, prioritization, and next-diligence recommendations.

## thesis-tracker

Use for thesis status, stable catalyst/source IDs, monitoring triggers, prove/kill checks, position watchlists, and review cadence artifacts.

## catalyst-calendar

Use for dated catalyst calendars, monitoring windows, event timing, confirmed versus inferred dates, and investor read-throughs.

## event-driven-analyzer

Use for probability/payoff/timing/downside event underwriting, merger or regulatory events, special situations, and event-driven expected-return framing.

## portfolio-risk-management

Use for position sizing, add/trim/exit decisions, hedge design, risk budget, thesis-preserving hedge plans, factor/sector risk, and portfolio-action rules.

## scenario-sensitivity-generator

Use for investment scenarios, sensitivity matrices, skew, action-impact cases, target backsolves, and decision-trigger analysis.

## economic-impact-report

Use for macro, policy, commodity, rate, FX, sector, or economic-impact read-throughs to listed equities.

## memo-builder

Use for PM memos, IC updates, investment memos, thesis updates, client-ready notes, or synthesis artifacts that import analysis from owning skills.

## meeting-prep

Use for investor meeting briefs, management-meeting prep, analyst/PM questions, diligence-call prep, and thesis-linked discussion guides.

## financials-normalizer

Use for model-ready public-company financials, reported statements, KPI schedules, normalized tables, source IDs, and QA flags.

## model-audit-tieout

Use for model audit, source tie-out, formula checks, workbook integrity, and remediation recommendations.

## deck-report-qc

Use for deck/report QC, source/model tie-out, circulation readiness, writing consistency, and investor-facing issue logs.

## user-context

Use only for explicit Public Equity Investing saved preferences, source setup, onboarding, recall, inspect, update, export, reset, or automation setup. Do not use as an ordinary workflow pre-answer gate.

## test-public-equity-investing-workflows

Use only when the user explicitly asks to test, evaluate, regression-check, or review Public Equity Investing plugin workflows.

## Cross-Skill Runtime Contract

Use this shared contract as the plugin's Cross-Skill Best Practices for ordinary Public Equity Investing workflows, whether this router or a focused skill was invoked first.

### Audience And Language

Users expect investor-readable work product, not plugin setup narration. Explain source limits, assumptions, readiness, confidence, and next steps in portfolio-manager or analyst language. Avoid exposing internal terms such as `source_category_plan`, `preflight`, `configured_route`, or `next_action` in user-facing output unless the user asks for implementation details.

### Dependency And Source Categories

The configured apps and their semantic categories live in this plugin's `.app.json`. Treat `.app.json` as the dependency-category registry, not as proof that any source is installed, authorized, or readable for the current user. An app can satisfy a category when its `category` or `categories` field matches the attempted category label below.

Use these category labels and legacy ids interchangeably inside this plugin:

- `Market Data & Estimates` / `market_data_estimates`: prices, estimates, ownership, benchmark data, factors, public-company facts, and comparable-company evidence.
- `Company Filings & IR` / `company_filings_ir`: filings, investor presentations, reported fundamentals, KPI disclosures, transcripts tied to reported company materials, and company-owned disclosures.
- `Earnings Transcripts & Events` / `earnings_transcripts_events` / `earnings_transcripts_presentations`: earnings calls, management remarks, investor-day events, conferences, release calendars, and event transcripts.
- `Portfolio Models & Trackers` / `portfolio_models_trackers`: existing models, watchlists, trackers, source exports, workbooks, portfolio files, and analyst workpapers.
- `Internal Research` / `internal_research`: analyst notes, PM discussions, meeting notes, saved theses, expert-research summaries, email or chat context, and team research color.

When resolving a dependency, identify only the categories needed for the selected workflow, prefer user-named sources first, then choose one available app, connector, file, export, or pasted input that can satisfy the category. Prefer canonical finance plugins or provider-specific helper guidance over raw connectors when they add workflow support. Use additional sources only when they materially improve evidence, confidence, recency, or the investment decision.

Do not silently substitute a weaker category for a stronger required one. If the needed category is unavailable, unauthorized, too slow, or returns no useful context, state the practical limitation, continue from user-provided or public context when a limited answer is still useful, and label the output posture accordingly. Stop only when the missing source owns a required input that cannot be supplied or reliably inferred.

Attempt connector reads only when the active workflow needs that source. Before saying a source is ready, use the smallest safe native read-only check for that run. A successful read is run-specific evidence, not durable setup state. Do not use browser automation, UI observation, screenshots, or mirrored adjacent sources as readiness proof.

### Provider And Helper Routing

Provider-specific guidance stays internal in this pass; do not expose provider guides as selectable skills. When a selected workflow needs provider call shaping, first choose the semantic source category, then confirm the concrete route is callable, then load `internal-support/policy.md` and only the matching internal guide.

- Use `internal-support/daloopa-provider-guide/INTERNAL.md` only for callable Daloopa routes that supply source-backed public-company financials, KPIs, or model-ready schedules. Keep prices, consensus, news, and non-Daloopa values separately labeled.
- Use `internal-support/quartr-provider-guide/INTERNAL.md` only for callable Quartr routes that supply filings, reports, earnings releases, presentations, transcripts, events, management commentary, or standardized actual financials. Prefer Quartr over web fallback for those document-backed facts when it is callable.
- For FactSet, LSEG, S&P, Morningstar, PitchBook, Third Bridge, Alpaca, Google Drive, SharePoint, Gmail, Outlook Email, Slack, Teams, or other configured apps without a bundled provider guide, follow the live tool surface, preserve provider/source provenance, and do not invent a helper skill or imply access that was not verified in the current run.
- If the preferred provider is unavailable, unauthorized, or missing the needed field, state the provider gap, request a specific export or user-supplied source when useful, and use an alternate route only with clear source labeling.

### User Context And Setup

Do not run `skills/user-context/scripts/user_context_preflight.py` during ordinary Public Equity Investing workflows. Saved preferences and source setup are optional accelerators, not a pre-answer gate.

Route explicit remember, save, update, forget, inspect, export, reset, source-setup, onboarding, or automation-setup requests for Public Equity Investing context to `../user-context/SKILL.md` relative to this router directory, equivalently `skills/user-context/SKILL.md` from the plugin root. That skill owns durable `user-context.md`, `onboarding-state.json`, explicit source setup, and optional automations.

### User Input Modalities

Ask only for choices that materially change the lead owner, first-read artifact, evidence path, reliance standard, investment decision, or user action. Use `request_user_input` when available for bounded choices with strong defaults: send all material unresolved questions together, put the recommended option first with `(Recommended)`, and set `autoResolutionMs` so an unanswered picker resolves to the recommended option. If `request_user_input` is unavailable or errors, ask all known material questions together in the next normal response, with recommended/default options first for bounded choices, and wait for the user's answer. Use `request_plugin_install` when a material missing source category can be solved by installing or connecting an available plugin, connector, or app. For open-ended facts, unknown ticker or portfolio context, or cases with no useful option set, group every known missing question in one concise plain-text response rather than asking one by one.

### Default Workflow

1. Resolve dependencies and clarify only material ambiguity.
2. Gather the smallest useful context from the category that owns the core source of truth, then broaden only when the first pass is empty, thin, conflicting, stale, or decision-relevant.
3. Produce the first useful investor-facing output in the workflow's preferred artifact form. Default to the skill's documented hero artifact when the user asks for substantive work, and chat only for narrow or explicitly quick answers.
4. End with a short useful next step tied to the artifact, such as refining the output, adding a model/deck/memo, running QC, refreshing sources, updating a tracker, or setting up an explicit saved preference or source connection.

## Plugin Workflow Routing

After the gate passes, read `../../shared/plugin-routing-playbook.md` and select one lead skill for the listed-equity investor workflow. Preserve its artifact hierarchy and load supporting skills only for the workstreams the lead skill assigns. Use `../../shared/final-deliverable-framework.md` for final artifact routing after the lead skill is selected. For a new substantive hero artifact, that owner reads `../../shared/deliverable-intake-policy.md` before source gathering or analysis; support and presentation skills inherit resolved choices and do not re-prompt.

If the lead workflow, first-read artifact, source posture, or risk/event mode remains materially ambiguous after reading the playbook, use the Material Ambiguity Choice Sets in `../../shared/deliverable-intake-policy.md`. Do not ask merely because multiple skills could help; ask only when the answer changes the lead owner, hero artifact, evidence path, or reliance standard.

## Internal Support

Read `internal-support/policy.md` when the selected workflow needs evidence control, generic data cleaning, rendering, style application, sector context, or provider-specific call shaping after selecting a callable connector route. Those supporting capabilities are bundled internal playbooks rather than selectable skills. Keep standalone normalization and model-audit requests with the visible `financials-normalizer` and `model-audit-tieout` workflows. For an explicitly requested internal support-only task admitted to this plugin, this router coordinates the task through the matching internal playbook.

Referenced files: 122

View saved version →

---
name: scenario-sensitivity-generator
description: Use when turning a public-equity base case, model, thesis, event, or catalyst into scenario skew, sensitivity, breakpoint, and PM action-threshold analysis. Do not use for first-pass model builds, credit-security valuation, or generic planning.
---

# Scenario & Sensitivity Generator

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Market Data & Estimates`
- `Company Filings & IR`
- `Portfolio Models & Trackers`
- `Earnings Transcripts & Events`

## Internal Support

When this workflow needs rendering, evidence/data preparation, style, or sector context, route support through the visible `public-equity-investing`
router and its bundled internal playbooks. Route workbook or model QA through the visible `model-audit-tieout` workflow.

## Deliverable Intake

Before source gathering or analysis for a new substantive 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. For a substantive reusable scenario analysis, explicit HTML scenario report, or sourced discrete-event success/delay/break overlay, the default resolves the presentation surface to a polished standalone HTML scenario report unless the user requests an alternate surface, a quick/no-file answer, workbook/model output, or a standardized dashboard. In interactive runs, ask only remaining material choices such as depth, audience/use, or focus; in non-interactive runs, default to the HTML scenario report and `Full working analysis` while disclosing those assumptions outside the artifact. Reuse resolved preferences in downstream steps; when acting only as input to an owning workflow, do not re-prompt.

## Purpose

Turn an existing Public Equity Investing base case into scenario and sensitivity outputs that show what changes the investment view. This skill owns grids, breakpoints, probability cases, thesis triggers, source posture, and interpretation after a model, earnings setup, equity-risk credit-signal handoff, event case, macro view, or thesis tracker already exists.

The default lens is a public-equity investor deciding whether to add, press, hold, trim, exit, hedge, wait for proof, re-underwrite, or change rating/target. The output should tell a buy-side PM, long/short analyst, sell-side equity researcher, or ETF/index diligence user what the stock already discounts, what scenario is underwriteable, what is merely optical, what breaks first, and what evidence would change the action.

For a concrete dated corporate event, this skill may directly produce a success/delay/break, implied-probability, or breakpoint overlay when the user specifically requests scenario sensitivity and the relevant deal terms, current-price anchor, timing, and downside convention are available or can be verified. This is a scenario overlay, not a replacement for full event underwriting.

## Do Not Use

- First-pass DCF, 3-statement, comps, credit, earnings, full event-underwriting, or memo builds.
- Raw source cleanup, source hierarchy, or evidence conflict resolution.
- Final memo, pitch, hedge, sizing, or deck QC ownership.
- Generic FP&A planning or target-setting exercises.

Use the relevant local owner first, then return here for the scenario layer.

## Routing

Use downstream of `equity-model-update`, `dcf-model-builder`, `three-statement-model-builder`, `comps-valuation`, `earnings-preview`, `earnings-deep-dive`, Credit Markets read-throughs, `event-driven-analyzer`, `economic-impact-report`, or `thesis-tracker`.

Use `financial-source-of-truth`, `financials-normalizer`, or `excel-data-cleaner` first if inputs are not clean or sourced. Use `model-audit-tieout` before treating workbook scenarios as final. See `references/p0-integration.md` for ownership boundaries.

Use `event-driven-analyzer` when the work requires a full event fact pack, process or regulatory/legal underwriting, trade expression, execution inputs, or ongoing event monitoring. When the request is explicitly for scenario skew on a named event and verified terms and pricing can anchor the cases, this skill may own the focused overlay while making any missing event diligence visible.

## Workflow

1. **Confirm base case and decision.** Identify security/issuer/model/event/thesis, decision type, and base-case source. If the base case is not model-validated, label outputs screen-grade or illustrative. For event overlays, verify offer or terminal terms, current price and as-of timestamp, key dates, contractual protections where relevant, and the chosen break/downside convention before presenting expected value. Use primary transaction documents and the freshest accessible market-data source for load-bearing inputs before relying on press reporting or older price observations; a focused overlay reduces analytical scope, not source-quality requirements.
2. **Select scenario mode.** Choose price-target, valuation, EPS/estimate revision, KPI driver, equity-liquidity downside, Credit Markets read-through sensitivity, event probability tree, macro factor, or thesis trigger table.
3. **Materialize tables when useful.** Use the deterministic helper for repeatable shells or populated calculations; if inputs are missing, it emits input-required rows instead of inventing values. Treat JSON, CSV, Markdown, run logs, and manifests as support artifacts unless the user explicitly asks for them.
4. **Interpret investor impact.** State the driver that matters most, what breaks first, whether upside is underwriteable, where the thesis depends on multiple expansion, estimate revisions, event probability, financing, or macro conditions, and which PM action would change. For event probability cases, state the analyst probability assumptions, hurdle, break-value convention, market-implied probability, and entry or maximum-break-probability threshold.
5. **Hand off cleanly.** Send model mechanics back to model builders, final narrative to `memo-builder` or `long-short-pitch`, exposure/sizing and hedge construction to the appropriate `portfolio-risk-management` mode, monitoring thresholds to `thesis-tracker`, and circulated decks/reports to `deck-report-qc`.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: base-driver ownership, scenario design, sensitivity math, output tables, and QA. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Deterministic Materializer

Run from this skill folder:

```bash
python3 scripts/materialize_public_equity_sensitivities.py --tables all --format json
```

With an assumptions file:

```bash
python3 scripts/materialize_public_equity_sensitivities.py --input assumptions.json --tables price_target_scenario,valuation_sensitivity --format json
```

Canonical table names:

- `price_target_scenario`
- `valuation_sensitivity`
- `eps_revision_sensitivity`
- `kpi_driver_sensitivity`
- `equity_liquidity_downside`
- `event_probability_tree`
- `macro_factor_sensitivity`
- `thesis_trigger_table`

Probability-weighted rows require complete probabilities that sum to 100%. Deterministic rows include `source_id`, `source_posture`, and `as_of_date` so downstream artifacts can distinguish model outputs from illustrative math. Load `references/materializer-schema.md` for the full input/output contract.

When `--output` or `--run-log` is used, the helper also writes `run_log.json` and `manifest.json` with `status`, `model_status`, warnings, hard failures, source basis, output paths, and output manifest. These deterministic tables are support artifacts unless a downstream workbook or dashboard turns them into the human-facing deliverable. Invalid table names or unsupported CSV multi-table requests must return non-zero with a failed run log when a log path is available.

Readiness is conservative: missing input JSON, missing base case, missing current price, or invalid probabilities must cap `model_status` at `not-decision-ready`. Complete math with missing source/as-of posture is `screen-grade`, not senior-review-ready. Only source-backed current price, valid scenario values, valid probabilities, and visible source posture can produce `senior-review-ready`.

If scenario outputs are inserted into or packaged as an XLSX workbook by a downstream tool, require a first visible `Cover` or scenario dashboard summarizing base case, cases tested, driver deltas, output range, source posture, validation status, warnings/hard failures, and the workbook/tab map.

## Output Modes

- **Full scenario report:** default route for substantive reusable scenario analysis, an explicit HTML scenario report, or a sourced discrete-event success/delay/break overlay. Produce a polished standalone HTML scenario report following `../../shared/html-artifact-standard.md`; let the decision and primary scenario object determine the layout rather than forcing a fixed dashboard module inventory.
- **Standardized dashboard:** use only when the user explicitly asks for a standardized dashboard, reusable dashboard template, PM cockpit, or structured payload-driven render. For that path, use `references/DASHBOARD_PACK.md`: `scenario-sensitivity-generator` owns the scenario math, stock-price anchoring, expected-return/skew interpretation, action thresholds, source posture, and missing-evidence calls; `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.
- **Explicit quick PM read:** use only when the user explicitly asks for quick, short, summary, brief, one-page, or TL;DR. Include decision posture, current-price/base-case anchor, scenario range, binding breakpoint, primary missing evidence, and what changes the action.
- **Workbook/model overlay:** preserve or extend the owning workbook/model when scenario outputs are an input to an existing model package rather than a new standalone report.

## Artifact Contract

Every final answer or handoff should include:

- decision context and base-case source;
- table names used;
- driver changes, timing, absolute outputs, and deltas;
- source labels and as-of dates for market-sensitive inputs;
- whether outputs are model-validated, source-derived, user-provided, or illustrative;
- threshold, trigger, or breakpoint interpretation;
- expected return versus hurdle, downside/upside ratio, break-even probability, and skew label where applicable;
- explicit PM action rules for add, press, hold, trim, exit, hedge, wait for proof, or re-underwrite;
- what would change the investment view;
- recommended next workflow or user data request.

## HTML Guidance

For a substantive standalone HTML scenario report, load `../../shared/html-artifact-standard.md` and apply these scenario-specific requirements:

- Give each first-read element a distinct job: lead with the investment conclusion and posture; then show the current-price/base-case anchor, primary scenario tree or sensitivity object, market-implied hurdle or breakpoint, and what must be verified next. Do not repeat the same verdict through a hero, posture card, metric-tile row, and second decision panel.
- For a sourced discrete-event overlay, organize the report around verified terms and as-of price, success/delay/break cases, expected value versus hurdle, implied completion probability, break-value convention, timing sensitivity, regulatory or evidence gates, and conditional action rules. If wider event diligence is missing, label the output as a focused scenario overlay or screen-grade report and route full underwriting to `event-driven-analyzer`.
- Require agreement-verified ticking-fee or contingent-consideration mechanics and an exact assumed close or break date before featuring precise timing-adjusted payoff or hurdle-probability calculations. If either is missing, show timing math only as a clearly provisional sensitivity or omit it in favor of the evidence needed to calculate it.
- When scenario probabilities are illustrative rather than independently underwritten, lead with market-implied probabilities and required-probability or entry-price breakpoints. Keep any sample probability-weighted value secondary, explicitly illustrative, and out of the headline investment case.
- Distinguish `Reported` or `Source-derived` facts from `Analyst assumption`, `Derived calculation`, and `PM judgment`. Scenario probabilities, hurdle rates, break-value capture, terminal-value adjustments, and unvalidated timing assumptions must never appear to be sourced from a filing or market-data citation.
- Use action language appropriate to position status and evidence: when no holding or executed trade is provided, prefer `Conditional Action Rules`, `wait for proof`, `research`, or `re-underwrite` over language that implies an active position.
- Cite load-bearing terms, prices, dates, and calculations near use while keeping the page readable. Do not fragment tickers, dates, prices, percentages, scenario labels, or table cells into repetitive citation links; prefer a compact nearby source note when adjacent values share the same basis.
- Visually inspect local HTML via local headless-browser screenshots, not the in-app Browser plugin, and iterate on hierarchy, density, clipping, citation rendering, whitespace, and whether the scenario decision is immediately usable.

## Reference Map

- `references/p0-integration.md`: local ownership and handoffs.
- `references/public-equity-investing-sensitivity-taxonomy.md`: table selection and interpretation rules.
- `references/materializer-schema.md`: deterministic script contract.
- `references/planning-mode-router.md`: Public Equity Investing mode selection.
- `references/scenario-overlay-contract.md`: workbook/cross-skill overlay schema.
- `references/target-backsolve-rubric.md`: feasibility labels for target backsolves.
- `references/output-templates.md`: trigger tables, QA checks, and reusable outputs.

## Quality Bar

Keep scenarios tied to a concrete security, issuer, model, event, or thesis. Label unsourced assumptions and stale data. Distinguish price-target math from investable risk/reward. Do not rebuild the base model, hide weak assumptions behind clean tables, or present probability-weighted outputs without source posture and downside. For discrete event overlays, require primary-document terms and fresh market-data anchoring when accessible, clear success/delay/break definitions, break-value methodology, expected return versus hurdle, market-implied probability where calculable, and the evidence gate that changes the conditional action. Treat timing-adjusted precision and probability-weighted values as provisional or secondary when their mechanics or probabilities have not been independently supported.

## 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.

Referenced files: 15

View saved version →

---
name: thesis-tracker
description: Use when building or updating Public Equity Investing thesis trackers. Do not use for generic news summaries, trade pitches, or first-pass memos.
---

# Thesis Tracker

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

### Source Resolution

Load `../../shared/workflow-source-resolution.md`. Resolve only the categories needed for this workflow: `company_filings_ir`, `earnings_transcripts_presentations`, `internal_research`, `portfolio_models_trackers`, and `market_data_estimates`. Use the shared runtime contract to map each attempted category to an available app, connector, file, export, or user-provided input.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Portfolio Models & Trackers`
- `Internal Research`
- `Earnings Transcripts & Events`
- `Market Data & Estimates`
- `Company Filings & IR`

## Deliverable Intake

Before source gathering or analysis for a new substantive 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.

For an update to an attached or existing thesis tracker, treat a polished XLSX thesis tracker workbook as the resolved presentation surface unless the user requests another format, a quick/no-file answer, or an HTML review package. Ask only remaining material choices that change the analysis.

## Purpose

Maintain a falsifiable public-equity-investing thesis over time. Preserve original underwriting, append new evidence, and translate each update into company-thesis status, security-thesis readiness, KPI/estimate/catalyst movement, model/valuation impact, risk/reward, and PM action.

## Non-negotiables

- Preserve user data append-only by default; never delete, collapse, or rewrite prior thesis data unless explicitly asked.
- Prefer user prompt, files, existing trackers/models/memos, and connected context before public sources. Use web/current sources only when needed and cite facts.
- Label source type, as-of date, reliability, stale data, assumptions, judgments, and possible MNPI/restricted or redistribution-sensitive material.
- Separate company-thesis status, security-thesis readiness, and position action; better fundamentals can coexist with worse forward risk/reward, and incomplete market data can block a stock conclusion.
- Track confirming and disconfirming evidence. Do not treat price action as proof; decompose it into fundamentals, estimates, multiple/spread, factor/sector, positioning, liquidity, rates/macro, and options effects.
- Convert narrative into prioritized falsifiable pillars, KPIs, thresholds, catalysts, kill criteria, and action triggers. Retain numeric weights or scores only when inherited from an existing tracker or explicitly requested; do not create scoring charts that imply false precision.
- For a material security-thesis update, attempt to retrieve current public price and basic market context when accessible, record the as-of timestamp and source, and label any unavailable consensus, internal model, ownership, or portfolio inputs as decision-blocking gaps.
- Identify whether each action threshold is an `Inherited threshold`, `Draft threshold for PM confirmation`, or `Approved monitoring rule`; never present analyst-created falsifiers as approved mandate rules.
- Every material update must state impact on assumptions/model lines, valuation/downside, conviction, sizing/hedge, decision timing, and next proof point.
- Avoid vague "monitor" language unless paired with exact metric, threshold, source, date, and action.

## When To Load References

- Missing/partial/conflicting context or source sensitivity: `references/intake-and-source-priority.md`.
- Full build/update sequence: `references/workflow-core.md`.
- Tables, fields, statuses, scoring, or spreadsheet shape: `references/thesis-schema.md`.
- CSV/XLSX scaffold helper: `references/tracker-materializer.md`.
- Investor mandate or sector-specific nuance: `references/investor-sector-overlays.md`.
- Final memo/dashboard/table formats: `references/output-templates.md`.
- Final PM judgment, compliance, drift, and red-team checks: `references/quality-guardrails.md`.

## Operating Modes

| Mode | Default behavior |
|---|---|
| Blank template | No ticker/thesis/files: create institutional shell plus minimal intake; invent no facts. |
| Ticker-only | Build preliminary shell from objective facts; label thesis fields as inferred/requires house-view confirmation. |
| Existing thesis | Extract original thesis, variant view, pillars, KPIs, catalysts, kill criteria, risks, and open questions. |
| Tracker update | Append evidence, preserve prior data, update statuses, and add changelog. |
| Post-earnings | Map release/transcript/guidance/estimate changes to pillars and decision impact. |
| Portfolio review | Triage by deterioration, improvement with worse risk/reward, catalysts, and required decisions. |
| Sell-side | Tie facts to rating, target price, estimates, valuation, client debate, and risks. |
| Long/short | Emphasize variant perception, setup, crowding/borrow/squeeze, catalyst path, sizing, and hedges. |
| Equity-risk credit signal / Credit Markets handoff | Track only credit facts that change common-equity downside, sizing, hedge, or re-underwrite status; route credit-security, covenant-package, restructuring, and recovery analysis to Credit Markets. |

## Workflow Contract

1. Define context: issuer/security, direction, mandate, horizon, exposure, benchmark/peers, rating/target/cost basis if supplied, and output need.
2. Inventory sources: name/type/as-of/reliability/coverage/limitations; retrieve current price and basic public market context when accessible; show missing or stale consensus, model, portfolio, and tracker data.
3. Preserve original underwriting: thesis, variant perception, market setup, valuation anchor, scenarios, catalysts, KPIs, risks, kill criteria, position implication, open diligence.
4. Decompose into prioritized falsifiable pillars with baseline, expected path, confirm/warning/break thresholds, timing, model linkage, action linkage, and next proof point. Use numeric weights only when source-backed or requested, and label their origin.
5. Append evidence ledger rows with fact, source/date, pillar, confirm/disconfirm signal, magnitude, quality, model/valuation/confidence/action impact, follow-up, and owner.
6. Update KPIs, catalysts, estimate revisions, and market-implied setup versus house view, guidance, consensus, buyside expectations if supplied, thresholds, peers, and prior periods.
7. Translate into model/valuation/risk-reward: near-term vs structural changes, affected model lines, fair value/target/downside/spread or recovery read-through where relevant to common equity, and hurdle clearance. If current price or valuation inputs remain unavailable, label the security thesis not decision-grade rather than inferring risk/reward.
8. Assess company-thesis status separately from security-thesis readiness: strengthening, intact, watch, impaired, broken, changed, untested, or retired for fundamentals; ready, conditional, re-underwrite, or not decision-grade for the security call. Explain movement with evidence, not price action alone. Reconcile aggregate status to core pillars: do not label the company thesis `Watch` when an inherited core pillar is `Impaired` without an explicit evidence-supported override rationale; when multiple core pillars are `Impaired`, default aggregate company-thesis status to `Impaired`.
9. Recommend action: add/press, hold, trim, exit/cover, upgrade/downgrade, hedge/pair, wait, re-underwrite, update model, diligence, or escalate. For every proposed hold/trim/exit threshold, show threshold origin and approval status.
10. Red-team: strongest opposing view, evidence for it, what would make it right, what changes the recommendation, open questions, next review date, changelog.
11. For XLSX delivery, keep the cover and key monitoring sheets readable at ordinary zoom: prefer compact decision-facing columns, move detail into the evidence ledger, freeze key identifier columns, render every sheet before delivery, and repair excessively wide or clipped tables. Keep full action-rule matrices and full diligence/gap registers on their dedicated tabs; the `Cover` tab should summarize action posture, top blockers, and next gate rather than duplicate them. Do not include a scored pillar chart unless the scoring method is inherited or explicitly requested.

## Sub-agent decomposition

For complex medium/large requests, use sub-agents where available; otherwise emulate the split as named workstreams. Suggested lanes: prior thesis extraction, evidence/KPI updates, valuation impact, action log, and red-team review. Keep this skill as the lead: reconcile conflicts, source labels, assumptions, open items, final QA, and the user-facing answer.


## Default Output

Unless the user explicitly asks for a short summary or one section, produce a full decision-grade thesis update:

1. Thesis status and recommendation.
2. Company-thesis status versus security-thesis readiness, including missing inputs that limit the stock call.
3. What changed versus prior house view, consensus, and market setup.
4. Pillar tracker with priority or inherited weight, status, latest evidence, signal, next test.
5. KPI / estimate / catalyst update.
6. Model, valuation, downside, and risk/reward impact.
7. Action thresholds with origin/approval status and decision log/changelog.
8. Red-team, kill criteria, open questions, sources/as-of dates.

For tracker builds or updates, lead with a polished XLSX thesis tracker workbook when XLSX is available; use an HTML report only when the user requests it or the task is a presentation-oriented review package rather than a live tracker update. Run `python scripts/materialize_thesis_tracker.py [tracker_input.json] --output-dir output` when its structured CSV/XLSX scaffold is useful, then apply workbook formatting and render-and-inspect QA for the final workbook. The helper writes a new CSV support bundle and optional XLSX when `openpyxl` is installed; it does not edit existing trackers in place. XLSX outputs should start with a compact `Cover` tab separating company-thesis status, security-thesis readiness, position action, market-data as-of, next catalyst, evidence gaps, and action thresholds. CSV/JSON support files should not be the lead user-facing artifact unless explicitly requested.

For optional dashboard handoffs requested by the user or needed for a reusable presentation view, use `references/DASHBOARD_PACK.md`. `thesis-tracker` owns thesis status, evidence ledger, KPI/catalyst monitoring, decision log, and update cadence; `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.

## Adjacent Routing

Use or recommend adjacent public-equity-investing skills rather than duplicating work when the primary need is source hierarchy, financial normalization, model tie-out/update, scenario sensitivity, earnings preview/deep dive, new pitch, hedge/sizing, event/credit/macro analysis, or memo/deck QC.

## When To Invoke Support

Load `shared/support-layer-routing-contract.md` when support services are needed. Use `financial-source-of-truth` before changing pillar status based on new evidence. Use `financials-normalizer` or `excel-data-cleaner` before tracker updates rely on messy KPI, consensus, ownership, market-data, or model-output tables. Use `equity-model-update` and `model-audit-tieout` for estimate/model changes. Use `deck-report-qc` and `style-guide-adapter` only for circulation packets. Support files stay secondary to the tracker workbook, HTML dashboard/report, or decision-grade update.

## Language Standard

Write like a top PM or research MD: concise, evidence-weighted, and action-oriented. Call out when the business thesis improved but the security thesis worsened because expectations rerated, and when headline results look good but evidence quality or cash conversion is poor.

## Public Equity PM Judgment Layer

For substantial thesis updates, load `shared/pm-judgment-heuristics.md` before finalizing. Audience modes: `long_only_pm`, `long_short_hf`, `sell_side_research`, `etf_index_diligence`, `public_equity_diligence`.

Portfolio Monitoring Mode is first-class. Every update should classify the stock as `add`, `press`, `hold`, `trim`, `exit`, `hedge`, `wait for proof`, or `re-underwrite`.

Required PM judgment:
- Separate company-thesis status from security-thesis readiness, stock action, and portfolio role.
- Make the operating model explicit: PM owner, analyst owner, evidence owner, KPI owner, model owner, decision authority, review cadence, post-catalyst update SLA, escalation triggers, next review gate, active weight, portfolio role, status, action threshold, and append-only decision log.
- Include benchmark weight, active weight, sector/factor exposure, ETF ownership, passive-flow sensitivity, index inclusion/deletion/rebalance risk, liquidity, crowding, and priced-in status when relevant.
- Strengthen market setup into consensus, buyside whisper, what is priced, what is ignored, and where the PM edge sits.
- Maintain a diligence ladder: filings/transcripts, KPI history, competitor checks, customer/channel checks if supplied, management credibility, accounting quality, ownership/flow setup, sell-side consensus, and variant debate.

Referenced files: 13

View saved version →

---
name: three-statement-model-builder
description: Use when building public-equity three-statement operating model workbooks. Default to the banker formula workbook path for new model builds; use deterministic exports only for controlled support calculations or explicit lightweight runs. Do not use for standalone workbook audits.
---

# Three Statement Model Builder

## Skill Configuration

### Common Skill Instructions

MANDATORY: Before searching connectors, retrieving evidence, or drafting output, read and apply the shared runtime contract in `../public-equity-investing/SKILL.md## Cross-Skill Runtime Contract`. Then check the router skill map and `../../shared/plugin-routing-playbook.md` for adjacent skills that should be sequenced with this workflow. Do not run user-context setup or inspection during ordinary workflow work; route only explicit saved-context, source-setup, onboarding, or automation-setup requests to `../user-context/SKILL.md`.

## Relevant Dependency Categories

These are the source categories most likely to matter for this workflow. Use the router contract to resolve only the categories the task actually needs, prefer user-named sources first, and state any material source limitation.

- `Company Filings & IR`
- `Portfolio Models & Trackers`
- `Market Data & Estimates`

## Deliverable Intake

Before source gathering or analysis for a new substantive 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.

Own formula-first public-company operating model builds: integrated IS/BS/CF, working capital, PP&E and D&A, retained earnings, debt, revolver-style draws, cash sweep, equity-relevant liquidity/headroom metrics, scenarios, sensitivities, machine checks, and senior-review reporting.

## Hard Contract

- Default model-build artifact level is `banker_formula_workbook`; use the formula workbook path for normal public-equity 3-statement build, refresh, forecast, and operating-model-package requests.
- Formula mode is executed through `scripts/build_banker_formula_workbook.py` and must be labeled `banker_formula_workbook` only when its run log, workbook inspection, and `model_citations.json` prove the formula builder ran successfully.
- Deterministic scripts remain available for controlled computed values, smoke tests, or explicit lightweight support exports. They produce `output/model.xlsx`, `output/plan.json`, `output/run_log.json`, `output/manifest.json`, and optionally `output/support_note.md`. Legacy `output/report.md` is written only with `--write-report-md`.
- Formula scripts produce `banker_formula_workbook.xlsx`, `banker_formula_workbook_run_log.json`, `model_citations.json`, and `manifest.json` in the selected output directory. The workbook is the hero deliverable; citation JSON, run logs, and manifests are support artifacts.
- `output/model.xlsx` must start with a `Cover` tab that functions as a dashboard: model status, scenario outputs, revenue/EBITDA/FCF/cash, liquidity trough, leverage/headroom, source posture, warnings/hard failures, workbook map.
- `run_log.json` and `manifest.json` are required reliability artifacts; hard failures force `not-decision-ready`.
- Never delete, overwrite, or mutate source data unless explicitly requested. Preserve raw tabs/files and write new outputs under `output/` or a clearly named copy.
- Material inputs must be evidence-labeled: `source_reported`, `company_provided`, `connector_sourced`, `public_filing`, `web_verified`, `management_guidance`, `analyst_estimate`, `benchmark`, `assumption`, or `placeholder`.
- If placeholders, stale data, unsupported assumptions, or failed tie-outs remain active, mark the model no higher than `screen-grade`; hard failures mean `not-decision-ready`.

## Routing

Use this skill when the deliverable is a 3-statement build, refresh, rerun, operating model package, or integrated forecast rebuild. Route away when the primary ask is workbook audit/debug (`model-audit-tieout`), source hierarchy (`financial-source-of-truth`), raw financial normalization (`financials-normalizer`), spreadsheet cleanup (`excel-data-cleaner`), valuation (`dcf-model-builder`, `comps-valuation`), public estimate update (`equity-model-update`), Credit Markets research, or memo/deck polish.

For complex builds, split the work into source/evidence, historical normalization, operating drivers, balance sheet and cash, QA, and executive output workstreams. If sub-agents are unavailable, emulate those workstreams and reconcile them into one plan before running scripts.

## When To Invoke Support

Load `shared/support-layer-routing-contract.md` when support services are needed. Use `financial-source-of-truth` for filings, releases, guidance, consensus, market data, and assumption labels; use `financials-normalizer` before building the plan from messy financials, KPI schedules, segment tables, share count, net debt, capital allocation, or provider exports; use `excel-data-cleaner` before relying on malformed workbook tables; use `model-audit-tieout` for workbook logic, external links, recalc/cache posture, and final tie-out. Support artifacts stay secondary to the formula workbook or owning dashboard/report.

## Input Handling

- Preferred input is a `plan.json` matching the schema.
- No context: run `assets/plan_template.json` as illustrative, label placeholders, and cap status at `screen-grade`.
- Partial context: preserve user facts, retain template defaults only when necessary, and label unsupported inputs.
- Full financial package: normalize IS/BS/CF, reconcile the balance sheet, preserve source data, fill the plan, validate, run, then report checks and caveats.

## Required Workflow

1. Build or receive a valid `plan.json`.
2. Validate with `python3 scripts/validate_plan.py path/to/plan.json`.
3. Fix validation errors before running; do not silently default conclusion-changing assumptions.
4. Default path: run `python3 scripts/build_banker_formula_workbook.py path/to/plan.json --output-dir output` and inspect `banker_formula_workbook_run_log.json`.
5. Use `python3 scripts/run_pipeline.py path/to/plan.json` only for controlled computed values, smoke tests, explicit lightweight support exports, or when formula mode fails and the fallback is clearly labeled `deterministic_export`.
6. Verify the relevant workbook, run log, manifest, and, in formula mode, `model_citations.json`.
7. Read the run log; hard failures require `not-decision-ready`.
8. Present the workbook as the hero artifact, with the `Cover` tab carrying the decision read-through, and link the normalized plan, run log, manifest, citation ledger, and optional support note as audit files.

Smoke test:

```bash
python3 scripts/validate_plan.py assets/plan_template.json
python3 scripts/build_banker_formula_workbook.py assets/plan_template.json --output-dir /tmp/public-equity-investing-3s-formula
python3 scripts/run_pipeline.py assets/plan_template.json
```

## Formula Mode Guardrail

Load `references/banker-formula-workbook-contract.md` before using formula mode. If the formula builder fails, the template is missing, required tabs/formulas/styles are not present, external links appear, or `model_citations.json` is absent, do not describe any fallback artifact as a banker formula workbook.

## Status Labels

Use exactly: `decision-grade`, `senior-review-ready`, `screen-grade`, `not-decision-ready`, `blocked`. Use `blocked` only when no reasonable run can be produced before execution.

## Senior Standard

Explain what drives the forecast, what must be true, where cash is consumed, what breaks first in downside, whether EBITDA converts to cash, and which assumptions deserve diligence. Balance-sheet integrity, retained earnings, cash flow linkage, debt roll-forward, PP&E roll-forward, and working-capital roll-forward are non-negotiable.

## Deferred Reference Router

Load `references/reference-router.md` only when deeper schema, math, QA, integration, industry, or forecast judgment guidance is needed. The router preserves the detailed reference map without loading every reference during invocation.

## 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.

Referenced files: 23

View saved version →

---
name: user-context
description: Initialize, inspect, save, update, forget, export, or explicitly reset the Public Equity Investing plugin's local user context, source setup, or optional automation setup. Use only when the user explicitly asks to manage Public Equity Investing saved preferences, source pointers, context storage, or recurring automation.
---

# Public Equity Investing User Context

This skill owns the Public Equity Investing plugin's local user-context storage foundation and explicit-only onboarding contract. It is intentionally narrow: it can initialize, inspect, save, update, forget, export, or explicitly reset local context, interpret the next onboarding action, guide the four-step intro/defaults -> connectors/plugins -> automation -> hero-workflow flow, and configure user-approved automations. Ordinary Public Equity Investing workflows do not invoke this skill by default; saved context and source setup are optional accelerators, not a pre-answer gate.

## State Files

Store Public Equity Investing state under:

```text
$CODEX_HOME/state/plugins/openai-monorepo/public-equity-investing/
```

The storage foundation owns only:

```text
user-context.md
onboarding-state.json
```

Do not create `category-state.json`.

## Initialize

When the user explicitly asks to initialize Public Equity Investing user context, run `python3 skills/user-context/scripts/init_user_context_state.py` with the shell working directory set to this plugin's root. Set the working directory before the first attempt; do not probe alternate relative paths.

The initializer creates missing state files from bundled templates and preserves existing files unless the user explicitly requests overwrite behavior.

## Inspect

When the user explicitly asks to inspect saved Public Equity Investing context, run `python3 skills/user-context/scripts/user_context_preflight.py` with the shell working directory set to this plugin's root. Set the working directory before the first attempt; do not probe alternate relative paths.

Use the returned read-only JSON envelope to summarize initialization status, onboarding status, the deterministic `next_action`, the lightweight `onboarding_progress`, and empty memory categories. Treat `user-context.md` as user-editable durable context and `onboarding-state.json` as operational scaffolding.

## Save Update Or Forget

When the user explicitly asks to remember, save, update, forget, export, or apply durable Public Equity Investing preferences or source pointers, follow `skills/user-context/references/plugin-memory.md` from the plugin root. Store reusable user-approved context in `user-context.md`; keep live company updates and operational connector state out. Initialize missing state only when a save needs persistence.

## Onboarding

When the user explicitly asks to set up, resume, defer, quiet, or complete Public Equity Investing onboarding, follow `skills/user-context/references/onboarding.md` from the plugin root. Use the inspection helper's `next_action` as the current step and render its `copy_ref` template substantially verbatim. Keep the visible flow to four steps: intro and lightweight defaults, connectors and plugins, one optional automation, then a three-option hero-workflow chooser. Capture broader durable preferences only when the user explicitly asks or supplies them naturally.

## Source Category Vocabulary

`skills/user-context/plugin-author-config/source-category-config.json` reserves static Public Equity Investing source category ids, labels, and preference hints for explicit setup/status work. The inspection helper exposes those categories as `source_category_plan` and echoes any setup-owned routes already saved under `onboarding-state.json` `connector_confirmation`. Ordinary workflow skills use the router's cross-skill runtime contract and `.app.json` categories instead of reading this helper first. Use `skills/user-context/references/source-category-runtime.md` from the plugin root for the source-setup boundary. Inspection does not prove source readiness, select routes, inspect connectors, or create `category-state.json`.

## Optional Automations

`skills/user-context/plugin-author-config/automation-config.md` defines the small author-owned automation menu. When the user explicitly asks for a recurring Public Equity Investing workflow or accepts the optional onboarding automation step, follow `skills/user-context/references/automation.md` from the plugin root. Do not create, update, pause, resume, or remove automations during ordinary workflow work.

## Reset

When the user explicitly asks to reset Public Equity Investing user context, run `python3 skills/user-context/scripts/reset_user_context_state.py` with the shell working directory set to this plugin's root. Set the working directory before the first attempt; do not probe alternate relative paths.

The reset helper moves active state files into a timestamped sibling backup directory before clearing them from the active state directory.

## Current Boundary

- The Public Equity Investing router and focused workflow skills do not run `scripts/user_context_preflight.py` during ordinary workflow work.
- Do not initialize state merely because another Public Equity Investing skill runs.
- Do not mutate state when running the read-only inspection helper.
- Do not inspect apps, connectors, plugins, `.app.json`, or source readiness during saved-context inspection.
- During user-approved explicit Source Setup, follow `skills/user-context/references/source-category-runtime.md` from the plugin root.
- During user-approved explicit automation setup or maintenance, follow `skills/user-context/references/automation.md` from the plugin root.
- Do not invoke onboarding unless the user explicitly asks for saved-context setup or management.
- Do not create or modify automations unless the user explicitly asks or accepts the optional automation setup step.
- Do not add, read, or migrate `category-state.json`. The reset helper may back up and clear an older copy during an explicit reset.

Referenced files: 14