jefrnc Lookahead Safety
The single most common bug in quant research with LLMs: using data that was not yet known at the moment you claim to have known it. This skill defines the rules to keep historical analysis honest.
The core rule
The known-date is the date a piece of information was PUBLISHED, not the date the information is ABOUT.
- A 10-K covering fiscal year 2023 may be filed in March 2024. In January 2024, that 10-K did not exist.
- An S-3 effective on 2024-04-15 was unknown on 2024-04-14.
- An XBRL
SharesOutstandingdatapoint withperiod_end: 2023-12-31is known only after the filing that contains it is published.
When asked to compute or recommend anything as of a date D, only data
where filing_date <= D is admissible.
Field-by-field reference for SEC data
| Field | Use as known-date? | Notes |
|---|---|---|
filing_date / acceptedDate |
✅ YES | The publication moment |
period_end / periodOfReport |
❌ NEVER | The accounting period the data covers |
effectiveDate (S-3, etc.) |
✅ YES | When the registration becomes usable |
reportDate on XBRL facts |
❌ NO | Period covered, not publication |
accepted timestamp |
✅ YES | Most precise — use when intra-day matters |
Common traps
The XBRL trap.
companyfacts.jsonreturns datapoints keyed byperiod_end. Naively iterating these as a time series leaks future information — the datapoint withperiod_end: 2023-12-31was first published months later. Always join with the originating filing'saccepteddate and treat THAT as availability.The amendment trap. A 10-K/A (amendment) supersedes the original 10-K but is filed later. At time
Dbetween the original and the amendment, only the original was known. Don't apply restated numbers to dates before the amendment'sfiling_date.The "as of today" trap in backtests. When using current data (e.g.,
current_shares_outstanding), confirm whether the source provides a point-in-time history or only the current snapshot. A snapshot is unsafe for any historical query.The price-data trap. Adjusted prices are computed using SPLIT factors from splits that may not have happened yet at date
D. Use raw OHLC + a split history table where each split has its own ex-date as the cutoff.The earnings-revision trap. Restated earnings (a later 10-K/A correcting a previous 10-K) were unknown until restatement. Backtests that use the latest version of earnings for old dates are fictional.
Workflow when the user asks "what was X on date D"
- Identify the data source (XBRL, filings, prices, derived metrics).
- Determine the source's publication semantics (when did this datapoint become observable to a market participant?).
- Filter by
publication_date <= D. If publication is unknown, stop and tell the user the query is unsafe. - State explicitly which
as_of_datewas used and which records were excluded for being future-dated.
Workflow when writing backtest code
- Every read of historical state must take a
query_dateargument and filter onfiling_date <= query_date(or equivalent). - Never store "current" values in a structure used for historical lookup.
- When in doubt, prefer the EARLIEST plausible publication date over the latest — bias toward under-claiming what was knowable.
- Tests: include a "future-data leak" test that fails if any record with
filing_date > query_dateis returned by a historical query.
Phrases that should trigger this skill
- "what was the float of X on [past date]"
- "backtest this strategy"
- "shares outstanding at [past date]"
- "compute [metric] historically"
- "build a point-in-time database"
- "as of [date]"
- "lookahead-safe"
- "survivorship bias" / "look-ahead bias"
What this skill is NOT
This is not a forecasting or prediction skill. It does not tell you what will happen. It tells you what you were ALLOWED to know at a moment in time. Use it before any historical reasoning. Combine with domain skills (SEC filing types, dilution events) for full coverage.