/USStats

name: USStats
evals:
  manual:
    reason: "an answer about a live public dataset must be reviewed for whether its cited series and conclusion answer the supplied question; a live refresh across all government providers is outside the offline fixtures"
    falsifier: "the reviewer finds the response uses the wrong series, misstates a cited value, or overclaims beyond the available data, or a supervised refresh produces a provider or persistence failure"
metadata:
  short-description: "Query a long-run US indicators almanac, and pull current FRED/EIA/Treasury metrics into a 10y/5y/2y/1y read of the economy. Excludes publishing the almanac site."
version: 1.2.2
description: "Query the configured long-run US almanac (90+ annual series on economy, debt, cost of living, health, crime, family, trust, energy, many back to the 1940s: trends, verdicts, movers, correlations, freshness vs source datasets), and pull 66 current indicators from FRED, EIA and Treasury into the local US-Common-Metrics dataset for a 10y/5y/2y/1y read of the economy now. USE WHEN usstats, US stats, US indicators, long-run US trends, is X getting better or worse in America, US crime trend, wage trend, inflation history, correlate US indicators, compare decades, is the usstats data fresh, how is the economy, economic overview, economic metrics, economic trends, GDP, inflation, unemployment, gas prices, mortgage rates, FRED, US metrics, refresh data, refresh the economic data, refresh US-Common-Metrics. NOT FOR pathogen surveillance, personal finances or investments, rebuilding or publishing the almanac site itself, refreshing our data sites (DataRefresh)."

USStats

**Contents:** Ideal State · Intent Routing · Data Contract · Data & Config · Quick Reference · Gotchas · Examples

Query and analyze the annual US indicator dataset at the almanac endpoint named by `data_url` in the install config (`<configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/USStats/Config.md`) — read-only, keyless, no local repo dependencies. Every series carries publisher provenance (`source`, `sourceUrl`, `note`) and a `goodDirection` flag that lets the tool answer "better or worse?" deterministically.

It also reads the current US economy straight from the government APIs (ported from the retired USMetrics skill, 2026-10-10). The one count and source list for that side, read from the updater's `METRICS` config in `Tools/UpdateSubstrateMetrics.ts` on 2026-10-11: UpdateData fetches 66 indicators in 9 categories (Economic Output, Inflation, Employment, Housing, Consumer, Financial, Trade, Fiscal, Demographics) through three APIs, FRED (64 series, carrying BLS, BEA, Census, Fed and Treasury data), EIA (gas price) and Treasury FiscalData (total public debt), into the local US-Common-Metrics dataset (`US-Common-Metrics.md`, `us-metrics-current.csv`, `us-metrics-historical.csv`). The master document lists 68 metrics in 10 categories; its Health & Crisis rows (CDC WONDER, EPA AQS) have no fetcher and stay placeholders, and a master row the updater did not fetch is named, never silently counted. GetCurrentState produces a multi-timeframe (10y/5y/2y/1y) trend report with cross-metric analysis, pattern detection, and research recommendations from its own FRED and EIA fetch, so it does not depend on an UpdateData run. The almanac answers "over decades, annually"; the live side answers "right now, monthly and weekly".

Ideal State

• Every answer about a US indicator rests on this session's tool output from the live dataset, names the publisher of each quoted series, and judges better or worse only through `goodDirection`.
• Year-to-date values, methodology breaks in `note`, base effects behind large percentage moves and the correlation-is-not-causation caveat reach the reader whenever they touch the numbers quoted.
• A freshness question gets a per-upstream fresh or stale verdict from a `--fresh` run, and nothing in the skill ever writes to the site or its upstream datasets.
• Every live-economy number reported is current and carries its period and source, whether it came from GetCurrentState's own FRED and EIA fetch or from the dataset UpdateData refreshed, and preliminary or stale figures are labelled as such, never presented as final.
• A "how is the economy" answer covers the report's eight categories across the four timeframes, names the categories it does not cover (Demographics, Health & Crisis), and ends with what deserves a closer look, without claiming that one metric caused another.
• A failed source or missing key degrades the result visibly (the affected metrics named) instead of aborting it or hiding the gap.

Intent Routing

| Intent | Trigger | File | |----------|---------|------| | **Analyze** | "US trend", "better or worse", "movers", "correlate", any indicator question | `Intents/Analyze.md` | | **SyncCheck** | "is the data fresh", "synced with the source datasets" | `Intents/SyncCheck.md` | | **UpdateData** | "Update metrics", "refresh data", "pull latest", "refresh the US metrics": fetch live data from APIs and update the local US-Common-Metrics dataset | `Intents/UpdateData.md` | | **GetCurrentState** | "How is the economy?", "economic overview", "get current state", "US metrics analysis", "economic metrics", "GDP", "inflation", "unemployment", "gas prices", "economic trends": multi-timeframe trend overview from live government data | `Intents/GetCurrentState.md` |

References

| File | Read when | |------|-----------| | `Setup.md` | first-time setup: FRED and EIA keys and seeding the US-Common-Metrics dataset folder |

Data Contract

• Endpoint: `data_url` in `<configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/USStats/Config.md`, or env `USSTATS_DATA_URL` (`Tools/UsStatsConfig.ts`; the tool stops naming the file and key when neither is set). CSV siblings are listed in `_meta.siblings`.
• License: public-domain government and published survey data; cite the publisher in each series' `source` field
• Schema: `series[key] = { n