Financial Data Sourcing

Financial data sourcing

Every number in a valuation comes from somewhere, and the analysis is only as good as the worst-sourced number in it. This skill is the input contract. It says what to fetch, from which source, in what units, how stale it may be, whether a user may hand it over directly, and what to substitute when it cannot be found.

Two consumers depend on it. The financial-data-collector agent uses it to fill four artifacts. The orchestrator's gates G1_data, G3_financials, G4_discount_rate and G5_forecast are predicates over the fields defined here.

This skill does not carry method. It says what must be in hand before a procedure can run. For how a number is used, follow the concept path cited beside it.

When to Use

• When gathering data for a valuation and each input needs a source, units, a vintage and a freshness limit.
• When an input is missing and a substitute is needed: walk the fallback ladder for that field and record where you stopped.
• When deciding whether a user-supplied figure can be accepted at face value.
• When checking that figures are internally consistent: currency, claimholder, basis, vintage and debt convention.
• Before gate G1_data, to write raw-financials.json, market-data.json, sources.md and gaps.json.

What you produce

Collect. Do not compute. Derived quantities belong to the downstream skills: financial-statement-normalization for lease and R&D capitalization, invested capital and cash flows, and cost-of-capital-toolkit for ratings, spreads, betas and WACC. A collector that quietly computes a ratio has erased the provenance the report needs.

Source classes

Every field carries exactly one class. The class decides caching, refresh policy and where blame lands when the number is wrong.

Fetch CO, MK and RT. Never fetch DV. Where a DV field is listed anywhere below, it is because a later stage treats it as an input and must be able to name its provenance.

The source identifiers used throughout — F-10K, F-LEASE, M-PX, M-RATING, D-ERP, X-FRED and the rest — are defined in references/source-registry.md.

Status vocabulary for gaps.json

Every field you attempt resolves to exactly one status.

One entry per attempted field, shaped like this:

{"field": "lease.commitments", "status": "fallback", "source": "F-LEASE",
 "as_of": "2024-12-31", "applied": "reported IFRS 16 liability used in place of the PV of commitments",
 "constrains": ["B2 lease capitalization", "B4 cost of debt"]}

The constrains list is what makes the file useful. A gap nobody traced to a stage is a gap nobody will remember at the point where it bites.

What a user may supply

Three answers per field, recorded in the tables in the resource files.

• Y — accept the user's value as authoritative and record source: "user".
• Y* — accept it after the stated validation runs.
• N — never accept a bare value. It is derivable, or it must trace to a source.

Some fields are freely user-suppliable. These are the judgments the pipeline cannot make for itself.

• Mode, company identity, valuation currency, valuation date
• Target operating margin, market size, market-share path, sales-to-capital
• Growth-period length; terminal growth and terminal return on capital, subject to the cap
• Failure probability, recovery rate, bankruptcy-cost percentage, distress severity
• Buyer type, lambda, debt-allocation key, illiquidity route
• Synergy assumptions, rating constraints, peer-set definitions

Seven things are never accepted bare. A statement line with no filing reference. A rate-table row with no vintage. A WACC, cost of equity or beta given as a single number without its components. A normalized riskfree rate. A control premium expressed as a bolt-on percentage. A terminal growth rate above the riskfree rate. A growth rate and a reinvestment rate set independently of each other.

The rules that bind every stage

These hold across all sources. A violation is a failure, not a warning.

Matching

R4 stated as a predicate: across {D-ERP, D-CTRY, D-SOVSPR, D-RATE1, D-RATE2, D-RATE3, D-SPREAD, D-MULTREG, D-DISTRIB}, max(as_of) − min(as_of) ≤ 3 months and valuation_date − min(as_of) ≤ 12 months.

Concepts, each loaded with skill_view("valuation-playbooks", file_path="references/<name>.md"): cost-of-equity-assembly.md, hurdle-rate-choice.md, net-debt-vs-gross-debt.md.

Single count

Ten versions of one error. Each names a quantity that may enter the valuation exactly once.

N2 is the one that bites hardest during collection. If the sovereign spread was stripped out of the riskfree rate, it may not also sit inside the equity risk premium build.

Units and signs

• Percentages are decimal fractions in every artifact. Store 0.0472, never 4.72. This covers growth, margins, tax rates, payout ratios, debt ratios, returns and spreads.
• Currency fields carry an explicit {value, currency, scale} triple. Never mix scales inside one table.
• Cash-flow-statement lines arrive already signed. Capital expenditure and working-capital changes are added, not subtracted.
• A positive change in non-cash working capital is a cash outflow.
• Balance-sheet items are point-in-time; income and cash-flow items cover a period. Any ratio that mixes them declares whether it uses beginning-of-period or average balances. Return on invested capital and return on equity use beginning-of-period capital.
• Interest-rate and inflation changes are absolute changes in the rate. GDP and currency changes are percentage changes.

Collect in stages

Run A1 first, because it parameterises every later fetch. A2 through A8 then run in parallel except where a dependency is named. Full field tables, with units, source, user rule and fallback for each, live in the resource files.

A1 — Mandate, identity and routing

Fixes the frame: mode, company name, ticker and exchange, country of incorporation, valuation currency, valuation date, fiscal year end, industry keys, public or private, reporting standard. Mode, identity, currency and valuation date block everything when absent. The rest have inference fallbacks.

Two judgments here shape the whole run. First, map the industry by the business the firm actually operates, not by its listing classification. A firm in several businesses gets a list of industries with revenue weights, not one label. Second, if the valuation currency differs from the filing's reporting currency, flag every downstream stage as needing a conversion and record which route will be used. The routes are differential-inflation conversion of a finished rate, or a rebuild from the local riskfree rate.

Reporting standard matters more than it looks. An IFRS or Ind-AS filer often groups expenses by nature rather than by function, so there may be no cost-of-goods line at all. See skill_view("valuation-playbooks", file_path="references/accounting-standards-gaap-ifrs.md").

Fields: references/company-inputs.md.

A2 — Financial statements

Pull ten fiscal years where available, five as the working minimum, one as the absolute floor. One year makes normalization impossible and blocks several routes.

Income statement, balance sheet and cash flow statement, from F-10K plus F-10Q whenever the last annual report is more than a quarter old. The quarterly filing is what lets you rebuild trailing twelve-month figures.

Three collection habits decide whether this stage is usable. Take the cash-flow statement's build-up lines, not just the section totals — free cash flow to equity cannot be built from a total. Take gross interest expense; a netted figure is not enough, so go to the debt footnote when the filer nets it. Label special items year by year over five to ten years, because the recurrence test needs the frequency and the variability, not this year's headline.

Six reconciliation ties run before the stage is marked complete. The balance sheet balances. Net income ties into the first line of cash flow from operations. The retained-earnings roll-forward closes. Income-statement depreciation ties to the cash-flow add-back. The cash tie closes. Segment third-party revenues plus eliminations reconcile to consolidated revenues. Failures of the first, second and fifth block the run; the rest flag.

Fields and ties: references/company-inputs.md.

A3 — Footnotes and structured disclosures

Everything the face of the statements leaves out. This is the stage that separates a usable valuation from a plausible-looking wrong one.

Lease footnote for the commitment schedule and the reported liability. Debt footnote for the instrument list and the maturity schedule. Segment footnote for business and geographic splits. Stock-compensation footnote for options. Investments footnote for cross-holdings. Tax footnote for the effective rate and loss carryforwards. Pension, contingencies and acquisitions notes for the bridge.

The defaults here carry real cost, so record each one you use. Weighted-average debt maturity defaults to three years. Option life defaults to four years and the strike to the current price. Geographic weights default to one hundred percent in the country of incorporation, which is the single most common cause of a wrong equity risk premium — flag it loudly and carry a sensitivity. R&D history padded with zeros understates the research asset, so say so.

Use third-party segment revenue for geographic weights, never revenue including intersegment sales. For a natural-resource firm prefer production location. For a manufacturer, ask where the plants are. See skill_view("valuation-playbooks", file_path="references/operation-weighted-erp.md").

Fields: references/company-inputs.md.

A4 — Company market data

Price, actual shares outstanding, return series, traded bonds, ratings, volatility, dividend history, preferred stock and convertibles.

Two flags decide later stages. Tag every rating as global-agency or local-scale: a local-scale rating does not embed sovereign risk, a global one does, and that single flag decides whether the country default spread gets added. Tag every bond for usability: a yield is a usable cost of debt only when the bond is straight, long-term and liquid. Anything else has option value inside its yield.

Record the beta regression's parameters even though the regression beta is a diagnostic rather than the production input. Five years of monthly returns is the default. Index choice can move a beta by half a point on identical data, so name the index and justify it by the marginal investor's portfolio.

Fields: references/market-and-macro-inputs.md.

A5 — Macro and currency

Fetched per currency and per operating country, keyed to the valuation date. Government bond yields, sovereign ratings and spreads, expected inflation, expected real growth, the Baa spread for the premium cross-check, and spot and forward exchange rates.

The riskfree rate has a four-rung ladder. A sovereign rated Aaa in its own currency gives its ten-year bond rate directly. Where several sovereigns issue in one currency, take the minimum ten-year rate across them, not the average and not the home sovereign. Below Aaa, subtract the sovereign default spread from the local ten-year rate, preferring a market measure of that spread over a rating lookup, and report the range across every route available. With no trustworthy local rate, build up from expected inflation and a real rate, or convert from the US dollar rate by the inflation differential, or switch the whole valuation to a major currency and restate every other input.

Never substitute a normalized historical riskfree rate for the observed one. If a user insists, normalize the riskfree rate, inflation, real growth and the equity risk premium together, and label the result a valuation of a hypothetical economy. Take negative rates as observed rather than flooring them at zero, and check that the growth and inflation assumptions in that currency are correspondingly low. See skill_view("valuation-playbooks", file_path="references/riskfree-rate-fundamentals.md") and currency-riskfree-rate.md in the same skill.

Fields: references/market-and-macro-inputs.md.

A6 — Reference-table load

Load every reference dataset at one consistent as_of and record the vintage on the snapshot you write into market-data.json. Details in the next section.

A7 — Ownership, governance and marginal investor

Required for mode = corporate-finance, and for any run where the marginal-investor question is live: private firms, closely held firms, family groups.

Institutional and insider percentages, the largest holders with their type, the board table, executive compensation, charter provisions, and a governance score if one is available.

The reading matters more than the numbers. A high institutional share of float with a low insider percentage means a diversified marginal investor, so a market beta is right. Low institutional ownership with a founder or family who does not trade means an undiversified marginal investor, which requires a total beta even for a listed firm. A controlling stake held through a partnership or holding company is undiversified even when it is classified as institutional. Institutional ownership above one hundred percent of float is a reporting artifact; leave it alone.

Fields: references/context-and-peer-inputs.md.

A8 — Comparable firms

Two peer sets, and they are not interchangeable.

Beta comparables serve the bottom-up beta, one set per business the firm operates in. Cast the net wide — global, with a size floor — because business risk travels across borders while country risk belongs in the premium. Ten to several hundred firms is normal, and the standard error falls with the square root of the count. Use the median, never the mean: one comparable with a debt-to-equity ratio in the hundreds of percent destroys an average. Do not unlever bank betas; use median levered betas weighted by net revenues.

Pricing comparables serve relative valuation and are defined by risk, growth and cash-flow characteristics, not by sector code. Record the screen explicitly — sector, geography, size floor, growth band — because it is the most challengeable part of the analysis. When a multiple is not computable for a firm, drop the firm and record the count. If most of the universe drops out, the survivors are profitable survivors and any conclusion says so.

Fields: references/context-and-peer-inputs.md.

Conditional branches

Classification adds inputs on top of the standard stages. Financial-service firms need regulatory capital and risk-weighted assets. Young firms need a market size and a target margin. Distressed firms need a traded bond or a default table. Cyclical firms need a full cycle of history. Emerging-market exposure needs country weights. Private firms need owner compensation and a buyer type. Multi-business firms need the segment table. More than one branch can be live at once, and their input sets compose.

Per-branch fields: references/branch-inputs.md.

The Damodaran reference datasets

These are the named lookup tables the pipeline reads. They are published annually — the country and premium tables twice a year, in January and July — so each one must be tagged with the vintage it came from. A table without an as_of is not usable.

Three rules govern their use.

All vintage-critical tables share one as_of. Mixing a current riskfree rate with a decade-old country premium table, or a current premium with stale spreads, is a hard failure. Spreads are the most volatile of the group: they roughly doubled to tripled at every rating between January 2008 and January 2009, and spiked and reverted inside 2020. See skill_view("valuation-playbooks", file_path="references/default-spreads-over-time.md").

When a vintage-critical table is more than a year older than the valuation date, attempt a refresh from the publisher. On failure, continue with status: stale and disclose the vintage in the report.

Reproduce a shipped table verbatim. Some published synthetic-rating tables carry non-monotonic labels or spreads below the B3 bracket. Flag the anomaly rather than quietly correcting it, because a silent fix cannot be reconciled against the source. See skill_view("valuation-playbooks", file_path="references/synthetic-rating.md").

The bundled snapshots live in cost-of-capital-toolkit, under ${HERMES_SKILL_DIR}/../cost-of-capital-toolkit/scripts/data/, each carrying its own as_of, source and refresh fields. Read them through its reference_data.py lookup subcommand, or from the path passed in, so a refreshed table can be swapped without touching code.

Column detail and freshness limits: references/reference-datasets.md.

When an input is missing

Walk the ladder for that field and record where you stopped. Every rung costs something, and the cost is the thing the report has to disclose.

The ladders that matter most, best rung first:

• Riskfree rate. Aaa sovereign ten-year, then the minimum across same-currency sovereigns, then the local rate less the sovereign spread, then an inflation-plus-real build-up, then differential inflation from the US dollar, then a currency switch. The last rung forces every other input to be restated.
• Mature-market equity risk premium. Current implied, then the average implied premium over a stated window, then the historical geometric premium over bonds, longest window.
• Unlevered beta. Comparable median, cash-corrected, then the industry table, then a regression beta unlevered at the window-average debt-to-equity ratio.
• Cost of debt. Straight-bond yield, then a global rating spread, then a recent bank loan rate, then a synthetic rating, then a local rating plus lambda times the sovereign spread.
• Lease debt. Present value of disclosed commitments at the pre-tax cost of debt, then the reported lease liability, then zero. Zero understates debt and overstates both return on capital and the equity weight.
• Market debt-to-equity. Market equity and market debt, then the industry median. Book debt-to-equity is never acceptable.
• Failure probability. Bond-implied, then the rating default table, then sector survival rates.

The full ladder table, with the cost of the last rung on each: references/fallback-ladders.md.

Before handing off

G1_data passes when the universal minimum is present, the mode-specific additions are present, and no blocking rule fires.

The universal minimum, for every mode:

• Identity, valuation currency, valuation date, industry key
• One full fiscal year of statements, with a balance sheet that balances
• The debt boundary: short-term debt, long-term debt and the current portion, plus either a lease schedule or a reported lease liability
• Cash and marketable securities
• An actual share count, or a private-firm equity-value proxy
• A ten-year riskfree rate in the valuation currency
• A mature-market equity risk premium at a stated vintage
• A beta path: either a comparable set or an industry unlevered beta
• A marginal tax rate for the domicile
• Every vintage-critical table loaded at one as_of

Five things block outright. The balance-sheet, net-income and cash ties must hold. A vintage-critical table missing with no fallback blocks. A live requirement for a failure probability with no source blocks. A live requirement for a total beta with no comparable R² blocks. Statements older than eighteen months with no interim filing block a valuation, and degrade to stale for corporate-finance work.

Geography weights defaulted to the country of incorporation do not block a firm with country risk above zero, but they carry a mandatory disclosure and a required sensitivity.

Mode-specific minimums, the consolidated validation catalogue and the non-blocking diagnostics: references/gates-and-validation.md.

Reference files

• references/source-registry.md — every source identifier, what it yields, and the trust rule for estimates
• references/company-inputs.md — A1 to A3 field tables: identity, three statements, footnotes
• references/market-and-macro-inputs.md — A4 and A5 field tables: prices, ratings, bonds, rates, inflation, currency
• references/reference-datasets.md — A6: the reference tables, their columns and their freshness limits
• references/context-and-peer-inputs.md — A7 and A8 field tables: ownership, governance, both peer sets
• references/branch-inputs.md — extra inputs by company type
• references/fallback-ladders.md — the substitution table and the refresh policy
• references/gates-and-validation.md — the G1 predicate, the validation catalogue, the diagnostics