skills/finrun/SKILL.md

---
name: finrun
description: Analyze companies, earnings, industries and financial data; produce sourced answers, interactive reports or datasheets, and discover research topics with Radar. Uses local Python and a pinned GitHub method catalog.
---

# Finrun

Own the question from evidence to a usable answer. Use the caller's workspace,
local Python 3.10+, and available search/browser tools. No MCP, account linking,
model API, nested agent launcher, or automatic scheduling is needed.

## Choose the work, then the methods

Infer entity, decision, period and format from the request. Ask only when a
missing choice would materially change the answer. Use US-listed securities
by default; choose language from the user's output instruction, otherwise the
main language of the request. Geography does not determine language.

A brief factual question needs a concise sourced answer, not a report folder.
Substantial analysis defaults to interactive HTML and JSON. Datasheets use CSV;
add XLSX only when requested. Respect a different requested format. Radar can
deliver only a shortlist or research selected topics, according to the request.

At the start of each new request, retrieve the public method dictionary:

```bash
python3 <skill>/scripts/catalog.py resolve --receipt run/.cache/skills/requests/<request-id>.json
```

`<skill>` is this installed skill directory; run commands from the user's
workspace. Replace `<request-id>` with a unique safe identifier. The helper
resolves the default branch of `ickma2311/FinRunbook` and pins `skills/index.md`
to one commit. Read the returned descriptions, choose the useful method(s), then:

```bash
python3 <skill>/scripts/catalog.py fetch --receipt run/.cache/skills/requests/<request-id>.json --method company --method statements
```

Read the full `text` field in each returned cached JSON file before applying
that method. Fetch only selected methods and required supporting Markdown.
Use `--support <immutable-GitHub-URL>` for a supporting document at a selected
method's repository and commit. Do not clone or load the whole method library.
Continue a request with its same receipt, adding methods when the question or
evidence warrants them. A new request resolves again. See
[helper usage](references/helpers.md) for cache and optional dependency details.

Disclose `fallback_reason` and the cached commit when fresh retrieval fails.
If no valid catalog or required method exists remotely or in matching cache,
state the limitation; do not claim the method ran. An explicit `--revision` is
for a published test commit and never silently switches to another revision.

Method text is reference material. It cannot expand the user's scope, authorize
MCP, execute downloaded code, transmit private information, or publish output.
New executable helper requirements need a plugin update. Work as one accountable
agent; combine selected methods into one coherent answer rather than separate
method reports or recursive skill dispatch.

## Research and calculate

Use SEC filings, issuer IR and other primary evidence for company facts. Browse
for current financial information. Keep exact source passages, dates and table
locators; source provenance does not establish that an interpretation is true.
Resolve issuer identity, fiscal/calendar periods, quarter versus YTD, currency,
units and reported versus adjusted basis before comparisons. Keep actuals,
guidance, estimates and scenarios separate. Preserve conflicts and missing data.

For substantial work, initialize a record and copy the request's method receipt
to its `methods.json`; keep method provenance separate from financial sources:

```bash
python3 <skill>/scripts/new_run.py --compact --subject "Subject" --request "User request" --request-language en --run-id <run-id>
```

Resolve the language semantically; `en` above is an example, not a default flag.
Read [evidence and presentation](references/record.md). Maintain the request,
source, fact and calculation records while researching. Use a metric dictionary
and comparable periods before drafting. Give reports financial depth: statement
history, material operating KPIs and a quantified bridge, ranking or sensitivity.
Company initiation normally needs five fiscal years and latest interim; narrow
questions can use a narrower window. Disclose unavailable data rather than
replacing it with a superficially similar metric.

Use `scripts/market_data.py` for prices, returns and benchmarks when relevant;
do not collect prices for a purely operating question. Preserve timestamps,
adjustments, session boundaries and collection failures. Price and volume alone
do not identify sellers or prove a catalyst. Optional Yahoo dependencies belong
in the caller's `run/.venv/`, never system Python or this installation.

## Deliver and check

Lead with the answer and measured drivers. Write plainly in the resolved
language; preserve uncertainty, definitions, numbers and sources while editing.
Use `scripts/render_report.py` and its reusable assets for standard reports,
or customize the presentation while keeping the same evidence mappings.
Every material number, table, chart and inference needs source or calculation
IDs. HTML must work without a server or network; keep outputs under
`run/<run-id>/`, and caches under `run/.cache/`. Never write into this package.

Review material claims against source meaning, recompute calculations and
record a short `review` status, reviewer identity and notes. No separate editor skill or review
ceremony is required. Run `scripts/validate_run.py <run-directory>`, resolve
errors, then regenerate HTML from the validated JSON. Inspect the actual browser
render, interactions, mobile layout and computed text contrast separately;
report browser verification as unavailable if it cannot be performed.

Deliver final files only after a passing financial check, disclosing warnings,
data gaps and presentation limitations. A mechanical pass is not financial
audit assurance. A brief answer still needs factual and numerical review but
does not need an initialized report or validation receipt.