earnings-preview

# Disclaimer requirement (Q139/T137) — full text

The body of SKILL.md carries only the binding rule; the reasoning lives here, so the
skill body stays inside its context budget (the `ctx-gate-body-size` gate caught this
at 1358 words against a 1300 limit — its own advice was "move detail to references/").

## The rules

1. Include the canonical block from `scenarios/templates/disclaimer.md` as authored.
   Do not write your own, restate it, or paraphrase it.
2. `[WORKSPACE]` / `[AS_OF]` / `[GENERATED]` are FILLED, never shipped. An unfilled
   placeholder fails the output gate (the same structural, case-insensitive check as
   Q108).
3. **Language follows the workspace** (Q126). The canonical file is English; a
   workspace declaring another language supplies its own rendering of the SAME
   clauses. The clause SET is the contract — every `<p>` carries `data-clause="…"`,
   and a rendering that drops one is not a translation, it is a different disclaimer.
4. The disclaimer states what the document IS; the badges, `epistemic_state` and
   coverage-gaps sections state what each claim IS. Do not let the disclaimer carry
   a burden the body should.

## Why this is written down at all — this skill has no template and no producer

Measured 2026-09-18: `scenarios/templates/` holds neither a pitch-deck nor an
earnings-preview template, and no producer script exists. So there is nothing yet to
mount the disclaimer ON, and `check_disclaimer.py` reports both as `nothing to gate
yet` rather than as compliant.

Recording the requirement in the output contract means it is already binding when a
template or producer is written, instead of being rediscovered afterwards — which is
how the thesis report's own disclaimer came to be retrofitted rather than designed in.

## Additional requirement — the footer of every slide carrying a price target

`earnings-preview` is the one presentation-shaped output that repeats a **price
target** across slides, so it carries the disclaimer **twice**: once as the closing
block, and once as a **footer on every slide that states a price target**.

The reason is not redundancy. A deck is read OUT of order and in fragments — a reader
can meet the price-target slide without ever reaching the closing disclaimer, and a
price target is exactly the thing a reader acts on. A disclaimer a reader never
reaches does not discharge the obligation it exists for. `thesis-report.html` needs no
such rule because it is a single continuous document with one ending.

# Formula Sheet

Canonical formulas for this model. All figures must tie to XBRL facts or cited filing pages.

- Revenue growth = (Rev_t / Rev_{t-1}) - 1
- Gross margin = GrossProfit / Revenues
- Operating margin = OperatingIncomeLoss / Revenues
- FCF = OperatingCashFlow - CapEx

# Institutional Defaults

- Lookback: per skill `temporal_scope`.
- Currency: reporting currency from the first XBRL fact `unit` (no conversion at v1.0).
- XBRL: `is_primary = true` default; `?include_all_sources=true` only for audit/reconciliation.
- Dedup: API-side; do not re-implement client-side.

# earnings-preview — Methodology Detail

Extracted from SKILL.md for progressive disclosure (US5).

## Retrieval Strategy

Follow the retrieval strategy decision tree in `contracts/retrieval.md`. This skill uses:
- Branch (a) for structured financial metrics via `search_xbrl_facts` with `list_xbrl_concepts` pre-condition for unfamiliar concepts.
- Branch (d) for simple lookups via `search_earnings_calendar` / `get_company_profile` / `search_companies`.

## Protocol

1. **Earnings calendar lookup**: call `search_earnings_calendar(ticker, fiscal_year=current)` to get the most recent reported quarter, next earnings date, and consensus estimates.
2. **Financial highlights**: call `search_xbrl_facts(ticker, concept=["Revenues","NetIncomeLoss","OperatingIncomeLoss","EarningsPerShareDiluted"], fiscal_period=["Q1","Q2","Q3","Q4","FY"], fiscal_year=[current, current-1])` for trailing data.
3. **Company context**: call `get_company_profile(ticker)` for company name, sector, industry.
4. **Peer discovery**: call `get_peer_comparison(ticker, metric)` (note: `search_companies` has no `sector`/`limit` params — pagination is `page`/`page_size`) for peer comparison slide.
5. **Slide-spec construction**: structure a 4–6 slide `.md` slide-deck specification (one section per slide, with title, bullets, and a source footer).
6. **Build**: write the polished `.md` slide-deck specification per `## Output Structure`.
7. **Review**: self-review the slide spec against the `## Validation Gates` below.
8. **Output**: write the artifact path per `## Output File`.

# earnings-preview — Analyst Mode Definitions

Derived from the skill's own methodology structure (scripts/mode_backfill.py, spec 046 M1).

### Mode: preflight

**Objective**: Preflight analysis per the skill's methodology (see SKILL.md sections).

### Mode: triggers

**Objective**: Triggers analysis per the skill's methodology (see SKILL.md sections).

### Mode: defaults

**Objective**: Defaults analysis per the skill's methodology (see SKILL.md sections).

### Mode: methodology

**Objective**: Methodology analysis per the skill's methodology (see SKILL.md sections).

### Mode: retrieval-scope

**Objective**: Retrieval Scope analysis per the skill's methodology (see SKILL.md sections).

# earnings-preview — Output Structure (full template)

Extracted from SKILL.md for progressive disclosure (US5). The skill body keeps a compact summary under `## Output Structure`.

1. **Slide 1 — Title**: Company name, ticker, "Earnings Preview — Q<N> FY<YYYY>", report date
2. **Slide 2 — Company Overview**: Business description, sector, market cap, key products/segments (from `get_company_profile`)
3. **Slide 3 — Consensus Estimates**: Table with consensus/high/low for Revenue, EPS, EBITDA; YoY comparison; estimate count (from `search_earnings_calendar`)
4. **Slide 4 — Historical Surprises**: Table of last 4 quarters: estimate vs actual, surprise %, direction (from `search_earnings_calendar` + `search_xbrl_facts`)
5. **Slide 5 — Peer Comparison**: Peer table with ticker, EV/EBITDA, P/E, Revenue growth (from `search_companies` + `search_xbrl_facts`)
6. **Slide 6 — Catalysts & Outlook**: Forward catalysts from the latest earnings call transcript (`search_documents(form_type="earnings_call_transcript")` → `read_source_pages` on the guidance/forward-looking pages), upcoming events, guidance summary (from `search_earnings_calendar`)

Slide 6 is optional (4–6 range). If peer data or catalyst data is unavailable, merge into fewer slides.

**Citations & memory**: follow `contracts/citation-and-memory.md` — ≥1 citation per 200 words; every material fact, table row, and metric is immediately followed by its inline clickable `https://agentii.ai/v/{ticker}/{citation_id}/{N}` link; a bottom **Citations** section provides a non-duplicative roll-up index; the closing TUI reply includes a compact **Key Citations** list (headline 5–10 facts) of clickable `/v/` URLs; and append the run to `agentii.md` per `contracts/agentii-md-schema.md`.

# earnings-preview — Tool Fallbacks

Extracted from SKILL.md for progressive disclosure (US5).

| Tool | Failure Mode | Fallback Action | Coverage Annotation |
|------|-------------|-----------------|---------------------|
| `read_source_pages` | SQL error / PROXY_ERROR | Use `search_keyword_in_source(document_id, keyword)` if document_id known; otherwise `search_documents` with same query | "source file unavailable; used keyword search instead" |
| `read_source_deep_outline` | PROXY_ERROR / 404 | Use lightweight `read_source_outline` and flag `deep_outline_degraded: true` | "deep outline unavailable; used lightweight page map instead" |
| `read_source_outline` | PROXY_ERROR / 404 | Use `list_sources` for document-level metadata | "page map unavailable; used document listing instead" |
| `list_xbrl_concepts` | Timeout / 503 | Use direct `search_xbrl_facts` with standard US-GAAP concepts (Revenues, NetIncomeLoss, EarningsPerShareDiluted, OperatingIncomeLoss, Assets) | "concept discovery skipped due to timeout; using standard US-GAAP concepts" |
| `get_company_fiscal_calendar` | Cross-validation failed | Use XBRL-derived period grid from `search_xbrl_facts` `period_end` dates | "fiscal calendar mismatch; using XBRL-derived period grid" |
| `search_unified` | Intermittent error | Use parallel `search_documents` + `search_xbrl_facts` with the same query | "unified search unavailable; used parallel document + XBRL search" |
| `batch_search` | PROXY_ERROR | Use sequential individual calls (one per sub-query) | "batch search unavailable; used sequential calls" |

Tool errors are retried ONCE with the fallback action before escalating to the retrieval gaps failure policy. If both Layer 2 and Layer 3 tools are unavailable, enter document access degradation mode (structured data + metadata only, flag output as degraded).

11. **tool diversity**: distinct MCP tools used in this invocation >= `min_tool_diversity` (5). *If failed*: flag as depth-insufficient in Coverage Gaps, listing which tool categories were unused (structured data / document retrieval / company metadata / earnings calendar / coverage). This gate does NOT block analysis completion — it is a quality signal for your review.

# Validation Checklist

- [ ] Every input figure cites a filing page or XBRL accession.
- [ ] Recalc/audit returns no hardcoded-over-formula cells.
- [ ] Statement identities balance within rounding.
- [ ] Period labels match `get_company_fiscal_calendar`.
- [ ] Coverage gaps are surfaced, not silently dropped.