lyndonkl/claude/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.

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 resources/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: knowledge/concepts/cost-of-equity/cost-of-equity-assembly.md, knowledge/concepts/cost-of-debt-capital/hurdle-rate-choice.md, knowledge/concepts/cost-of-debt-capital/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 knowledge/concepts/accounting-statements/accounting-standards-gaap-ifrs.md.

Fields: resources/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: resources/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.