1 files changed, 51 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-05-17-reference-card-adaptive-design.md b/docs/superpowers/specs/2026-05-17-reference-card-adaptive-design.md
new file mode 100644
index 0000000..b819e5e
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-17-reference-card-adaptive-design.md
@@ -0,0 +1,51 @@
+# Reference Card — Adaptive Row Filtering
+
+**Date:** 2026-05-17  
+**Status:** Approved
+
+## Problem
+
+The `StatsCard` component (the "Reference" card in the right rail) always renders all 17 ratio rows. For partial tickers — ETFs, tickers with no income statements, or symbols resolved only through fast-info — most ratio fields are null. This produces a wall of muted "Unavailable" text that adds no information and degrades readability.
+
+## Goal
+
+Make the Reference card adaptive: show only rows that have values, and replace suppressed rows with a single brief note so the user understands why data is missing.
+
+## Approach
+
+Filter, don't hide. Keep the full 17-row definition intact in code (it documents what fields the card tracks). At render time, split into visible and suppressed lists. Only render visible rows; show one fallback line if anything was suppressed.
+
+## Design
+
+### Scope
+
+Only `StatsCard` in `frontend/app/page.tsx` changes. No backend changes, no schema changes, no CSS additions.
+
+### Logic
+
+1. Build `referenceRows` as today — 17 rows with `{ label, value, missing }`.
+2. Derive `visibleRows = referenceRows.filter(r => !r.missing)`.
+3. Compute `suppressedCount = referenceRows.length - visibleRows.length`.
+4. Render `visibleRows` via `StatRow`.
+5. If `suppressedCount > 0`, append a muted line after the list:  
+   `· Statement data incomplete`  
+   Use existing `psm-muted-copy` class — no new CSS needed.
+6. Edge case: if `visibleRows` is empty, render only the fallback line (no empty `psm-stat-list`).
+
+### What stays the same
+
+- Backend payload shape (`ratios`, `stats`, `meta`) — unchanged.
+- All other cards (`ShortInterestCard`, `ProfileCard`, `DataStatusCard`) — unchanged.
+- Watchlist, chart, KPI strip, signals — unchanged.
+- CSS — no additions.
+
+### Acceptance criteria
+
+- Partial ticker: Reference card shows only available rows + one fallback note at bottom.
+- Full ticker: all 17 rows render as before.
+- Empty ticker (no rows): fallback note only, no empty list element.
+- `npm run lint`, `npm run build`, `pytest` all pass.
+
+## Files changed
+
+- `frontend/app/page.tsx` — `StatsCard` function only (~5 lines)