α
AlphaSteve
← Brain index

EDGAR Fundamentals Standard — uniform, structured, free

Adopted 2026-06-10. Companion to the data-integrity-gate; this file defines how Rule 2 routing is executed now that the kit is EDGAR-only (no paid connectors). See changelog-2026-06-10-edgar-pipeline for the adoption record.

The problem this fixes: the audit-log failure pattern (#001, #012, #013) is fundamentals reconstructed from web text. The fix is a single mechanical pipeline that turns SEC EDGAR's structured XBRL APIs into one uniform format that every thesis, scan, and calibration checkpoint cites. The data is consolidated, point-in-time, filing-linked, and free.

The pipeline (three steps, in order)

Step 1 — Resolve the entity (mandatory before any figure is touched)

Fetch https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&ticker=<TICKER>&type=10-K&output=atom&count=1 via web fetch (NOT bash — the shell sandbox cannot reach sec.gov; web fetch can).

This one call returns the full entity-confirmation block: CIK, conformed legal name, fiscal-year-end, former names, and recent 10-K accession numbers. Record it in _Tools/edgar/cik-registry.json. The registry entry is permanent; resolve each ticker once.

The fiscal-year-end field alone kills the audit #012 class of error: a "Q3 print" that doesn't fit the issuer's fiscal calendar is now visible at resolution time.

Step 2 — Fetch raw structured facts

For each tag in _Tools/edgar/concept-map.json, fetch: https://data.sec.gov/api/xbrl/companyconcept/CIK<10-digit-CIK>/us-gaap/<TAG>.json

Save each response verbatim to 09-Theses/<TICKER>/_data/raw/<TAG>.json. Tags with no data (404/empty) are skipped — the concept map carries fallback tags per concept. These responses are consolidated XBRL facts only; segment data structurally cannot enter this pipeline (kills the audit #013 class).

Step 3 — Normalize

python3 _Tools/edgar/edgar_normalize.py <TICKER> --vault <vault-root>

The normalizer:

  • Hard-fails on entity mismatch — every raw file's CIK must match the registry, or no output is produced.
  • Dedupes point-in-time — one value per fiscal period, latest filing wins; if an earlier filing reported a different value, the figure is flagged RESTATED with both values and both accession numbers shown.
  • Cites at figure level — every number carries form, accession number, filed date, and XBRL tag. This satisfies data-integrity-gate Rule 1 automatically.
  • Labels derived metrics — EBITDA (= operating income + D&A), total debt, net debt, FCF are computed and marked DERIVED. They are GAAP-derived cross-checks, never substitutes for company-adjusted figures.

Output, the uniform format all downstream work cites:

  • 09-Theses/<TICKER>/_data/<TICKER>-fundamentals.json — machine-readable (schema alphasteve-edgar-fundamentals-v1): entity block, 6 annual periods, 8 discrete quarters, each figure {value, unit, tag, form, accession, filed, restated?}.
  • 09-Theses/<TICKER>/_data/<TICKER>-fundamentals.md — citable tables plus a figure-level citation list ready to paste into a thesis.

The underscore prefix on _data/ keeps these files out of the published site's content collections.

What still requires reading the filing itself

The XBRL pipeline covers GAAP line items. It does not cover:

  • Non-GAAP / adjusted figures (adjusted EBITDA, adjusted EPS, organic growth) — read from the 10-K/10-Q/8-K directly, cited to page/exhibit, and cross-checked against the pipeline's GAAP-derived equivalents. A company-adjusted EBITDA wildly above the DERIVED ebitda line is a finding, not a nuisance (MP FY2025: adjusted EBITDA reported positive vs. GAAP-derived −$60.1M — the gap is the adjustments, and the thesis must name them).
  • Segment detail — intentionally excluded here; pull from the filing with explicit segment labels per gate Rule 3.
  • Guidance, commentary, footnotes — read the document.

Refresh discipline

  • Re-run Steps 2–3 for a name after each new 10-K/10-Q (the thesis-builder and calibration checkpoints check generated: in the fundamentals file frontmatter; stale = older than the latest filing in Step 1's atom feed).
  • Never edit the generated files by hand. Fix the inputs or the script, then regenerate.

Failure handling

  • Web fetch truncates very large responses to a saved file — copy the saved file into _data/raw/ before running the normalizer (the script strips the fetch header automatically).
  • The bulk company_tickers.json is known to truncate; per-ticker atom resolution (Step 1) is the supported resolver.
  • If EDGAR is unreachable, the work stops — figures are not backfilled from search results. data_integrity_gate: pending until the pipeline runs.

Linked