USStats

• 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.

References

• 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] = { name, category, unit, coverage, goodDirection, partialYear, partialThrough, source, sourceUrl, historicalSourceUrls[], note, data{year: value} }

First-time setup (accounts, keys, files to fill in): Setup.md.

User customizations live at <configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/USStats/ (configRoot is $CLAUDE_CONFIG_DIR when set, else ~/.claude). When that directory exists, its PREFERENCES.md, configurations and resources apply and override the defaults here; when it is absent, the defaults stand.

The live dataset:

• Location: $USMETRICS_DATA_DIR if set, otherwise ~/.claude/LIFEOS/USER/DATA/US-Common-Metrics/ (Tools/UpdateSubstrateMetrics.ts)
• Master Document: US-Common-Metrics.md (counts and fetched sources in the purpose paragraph above)
• Source Documentation: source.md (full methodology)
• Underlying APIs: FRED, EIA and Treasury FiscalData are fetched; the master document's CDC and EPA rows are not
• Seeding: the directory starts empty; copy the four files from the seed named by seed_source in <configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/USStats/Config.md before the first UpdateData run (the tool refuses an unseeded directory with that instruction).
• Why local: the skill keeps its own dataset so it never depends on another system's storage; install-specific notes on any other copy of the same pull live in <configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/USStats/Config.md.

Metric Categories Covered

The master document's ten categories; the updater fetches the first nine.

1. Economic Output & Growth - GDP, industrial production, retail sales
2. Inflation & Prices - CPI, PCE, gas prices, oil prices
3. Employment & Labor - Unemployment, payrolls, jobless claims, quit rate
4. Housing - Home prices, mortgage rates, housing starts
5. Consumer & Personal Finance - Sentiment, saving rate, credit
6. Financial Markets - Interest rates, Treasury yields, volatility
7. Trade & International - Trade balance, USD index
8. Government & Fiscal - Federal debt, budget deficit, spending
9. Demographics & Social - Population, inequality, poverty
10. Health & Crisis - Deaths of despair, air quality, life expectancy

API Keys Required

For live data fetching:

• FRED_API_KEY - Federal Reserve Economic Data
• EIA_API_KEY - Energy Information Administration

Tools

bun ~/.claude/skills/USStats/Tools/UsStats.ts summary            # dataset shape
bun ~/.claude/skills/USStats/Tools/UsStats.ts search crime       # find series keys
bun ~/.claude/skills/USStats/Tools/UsStats.ts trend income       # direction-aware verdict
bun ~/.claude/skills/USStats/Tools/UsStats.ts movers --window 20 # biggest changes
bun ~/.claude/skills/USStats/Tools/UsStats.ts correlate debt gdpGrowth
bun ~/.claude/skills/USStats/Tools/UsStats.ts sync-check --fresh # vs upstream source of record

All commands take --json (machine output) and --fresh (bypass the 6h cache).

• Partial years are YTD, not annual. A series' partialYear value (e.g. a July year-to-date figure) is excluded from all math and flagged ← YTD in output.
• Percentage change is base-sensitive. Movers rank by percent change; a series moving off a tiny base (CPI inflation 0.1 → 2.8) posts a huge percentage. Sanity-check the absolute values shown next to the rank before quoting a headline number.
• Read note before comparing across years. Several series have methodology breaks (survey redesigns, definition changes) disclosed in note; a naive 1970-vs-today comparison can cross one.
• Correlation is not causation. correlate prints the warning and the live report's cross-metric patterns are suggestive only; keep the caveat in any analysis you hand over and never claim one metric caused another.
• Each of the three fetched APIs (FRED, EIA, Treasury FiscalData) has its own rate limits and data freshness; the series FRED carries keep their originating agency's release lag.
• Economic data has publication lag. GDP is quarterly with revisions. Jobs data is monthly. Don't present preliminary data as final.
• A seed dataset can carry corrupted rows from an old string-replacer bug (dollar-led values read as $2 group patterns). UpdateSubstrateMetrics.ts now repairs widened rows and uses function replacers; its tests pin both.
• Cache lives in the user cache dir (${XDG_CACHE_HOME:-~/.cache}/usstats-skill/, owner-only), never in the skill tree. Deleting it is always safe.

Example 1: "Is crime getting better or worse?"

User: "What's the long-run crime trend in the US?"
→ Analyze intent (search crime, then trend on each hit: violentCrime, propertyCrime, …)
→ Direction-aware verdicts with sources, YTD caveats surfaced

Example 2: "What's improved most in the last 20 years?"

User: "Biggest US improvements since 2005?"
→ Analyze intent (movers --window 20)
→ Improving/worsening lists, direction-aware, absolute values alongside

Example 3: Full analysis of the current economy

User: "How is the US economy doing? Give me a full analysis."
→ GetCurrentState intent (GenerateAnalysis.ts fetches its own history; no UpdateData run needed)
→ The US Economic State Analysis report GenerateAnalysis.ts writes (Intents/GetCurrentState.md § Output format), saved under MEMORY/RESEARCH

Example 4: Refresh only

User: "Pull the latest economic data"
→ UpdateData intent
→ The three dataset files refreshed, with any failed fetch or skipped source named

Example 5: "Does household debt track income?"

User: "Correlate median income with revolving debt"
→ Analyze intent (correlate income debt)
→ Pearson r, N, overlap window, causation caveat