# BI "Ledger Room" v3 — Gap Analysis & Feature Backlog

**Method:** every feature the R2 v2 mockups (`variant-A-v2-desktop.html`, `variant-A-v2-mobile.html`), `master-register.html`, and `SYNTHESIS-BRIEF.md` DEPICT, classified against the ground-truth inventory (`ground-truth-inventory.md`) into exactly one bucket:

- **REAL** — exists today, mockup showed it → keep in v3.
- **REAL-BUT-OMITTED** — exists today, mockup did NOT depict it → **must be added back to v3.**
- **NEW / INVENTED** — does NOT exist in the product → **excluded from v3, goes to backlog.**

> **CORRECTION NOTICE (this revision).** The prior backlog read a STALE worktree and wrongly classified four shipping features as NEW/INVENTED. They are REAL (verified in `/home/stevan/dev/lore-consolidate` @ `main` `5e19772`) and have been **MOVED to the REAL section** (see §1, marked ⟲MOVED):
> - **Customize-columns chooser** (was B3) → REAL (Group H).
> - **Row-limit segmented control** 100/500/1k/All (was B9) → REAL (D3).
> - **Full-result CSV export** (the CSV part of the export menu, was inside B8) → REAL (D2).
> - **Facebook ads-vs-source clarification** and **proportion/denominator clarification** (prior inventory's "does NOT exist" note) → REAL (C6/C7).
>
> Still genuinely NEW (the founder explicitly flagged these): the **in-place editable-assumptions re-runner ("Re-run with changes")** and the **"all Facebook is ads" single-channel AI WARNING**. They remain in §3.

---

## 1. REAL — keep in v3 (mockup got these right)

| Feature | Mockup label | Ground-truth |
|---------|--------------|--------------|
| Nav rail / icon rail | "Insights" + Home/Compose/Connect/Settings | A1 |
| Memory Stack / memory drawer | "Memory" / "Past inquiries" | A2 |
| Theme toggle light/dark | sun/moon | A4 |
| Vault switcher | "Switch vault" / "CT ▾" | A5 |
| User menu + logout | avatar "ST" menu | A6 |
| Mobile nav (hamburger → left sheet) | nav sheet | A7 |
| Ask box / "command desk" | "Ask the ledger…" | B1-B3 |
| Starter prompts (empty room) | help examples / departments | B4, G:Editorial-Index |
| Clarify chips (source-tagged, CT/PD) | `.cchip` "Reading" | C2, C4 |
| Read-only trust badge | "read-only verified" shield | (real posture) |
| Confidence chip + explainer popover | "Medium confidence" + gauge | D1 |
| View toggles table/chart/SQL | view segment | D4 |
| SQL view + Copy/download | "View SQL" | E1 |
| Insight headline / verdict | "headline" + `.fig` | F1 |
| Metric strip | 5-metric strip | F2 |
| Assumptions (read-only disclosure) | "Assumptions (N)" | F3 (read-only; the EDITABLE re-run is INVENTED B1) |
| Analyst notes | "Analyst notes" | F4 |
| Chart (with advisory) | dominant bar chart | F5-F6 |
| Disclosures deck | "Disclosures" accordions | F8 |
| Follow-up encouragement | "Ask a follow-up…" | F10 (partial — see OMITTED O5) |
| Dateline-as-loader | "LONDON 14:32 — querying…" | G:loading |
| Result states | states legend | G |
| Scope chip bar (constant-column collapse) | "All rows share: …" | reasonable rendering |
| **⟲MOVED Customize-columns chooser** | "Columns" checklist / "Customize columns" | **H1-H3** — REAL: the live Ledger Modal + 33-col catalog + server endpoints. Mockup got the concept right; v3 should match the real grouped catalog (Identity/Attributes/Marketing/Pipedrive/Measures), search, staged→Apply, added-locked rows, server-side PII. |
| **⟲MOVED Row-limit control (100/500/1k/All)** | segmented `100/500/1k/All` | **D3** — REAL as a raise-cap widget ("Show all · 500/1k/All") shown when truncated; default is 100. v3 should render it as the truncation raise-cap, not a persistent always-on segmented control. |
| **⟲MOVED Full-result CSV export** | "Export ▾ … CSV" | **D2** — REAL: server `/full-result` re-runs at the 10k ceiling and includes non-PII enrichments. (Only the CSV format is real; XLSX/TSV/Copy-SQL multi-format menu stays INVENTED — see B8.) |
| **⟲MOVED Facebook ads-vs-referral clarify** | (mockup's "Facebook" handling) | **C6** — REAL deterministic clarify case `facebook_ads_vs_referral` (paid vs organic). NOTE: this is the *clarification*, not the auto-warning; the "all Facebook is ads" passive WARNING is still INVENTED (B2). |
| **⟲MOVED Proportion/denominator clarify** | (proportion examples) | **C7** — REAL deterministic clarify case `proportion_denominator_scope` (cohort-own vs whole-book denominator). |

---

## 2. REAL-BUT-OMITTED — v3 MUST add these back

These ship today but the R2 mockups under-depicted or dropped them. Putting them back is non-negotiable.

| # | Feature | Why it must return | Ground-truth |
|---|---------|--------------------|--------------|
| O1 | **SQL explanation ("What this query does") — prose + bullets** | Real, generated for every successful non-empty result. Mockups showed raw SQL but not the plain-language explainer beside it. | E2 |
| O2 | **Clarify answer persistence / resolved-answer state** | Real product remembers resolved terms across turns (`✓` resolved vs `?` pending). Mockups showed clarify chips but not the persisted state. | C8 |
| O3 | **Server clarify TURN (mid-run) + "Answering" indicator** | A distinct state from the pre-submit scaffold: the room can come back mid-query asking one thing, option chips, ✕-to-ask-fresh ("One thing before I query"). Mockups only show pre-submit clarify. | C10 |
| O4 | **Bare-currency hard gate (side × source)** | Real, deterministic, high-value (buy/sell × traded-CT/declared-PD). Mockup currency handling doesn't represent this forced 5-option gate. | C5 |
| O5 | **Facebook + proportion clarify cases (FE labels)** | The cases are REAL (C6/C7) but lack curated FE labels (they fall back to humanized strings). v3 should give them proper clarify-card labels/questions. | C6, C7 |
| O6 | **Follow-up suggestion chips ("Next" — tappable)** | Real `insight_follow_ups` (≤3 drill-down chips that submit a new question). Mockup showed a passive "Ask a follow-up…" placeholder only. | F10 |
| O7 | **Follow-up routing: answer-from-context (no new query)** | Real "↑ answered from the previous result — no new query" state. Distinct, trust-building shape; not depicted. | F11-F12 |
| O8 | **Federation "Merged result" banner** | Real, rich (coverage %, unmatched/null-key-dropped, per-source cards, "not summed"). Mockup's "Blended — CT+Pipedrive" chip is a static label, not this disclosure. | F9 |
| O9 | **LLM trace chip (✦) — model + PII posture per step** | Real provenance affordance (which model ran each step, CT-hosted vs tokenised). Trust feature, not depicted. | D5 |
| O10 | **Column-sanity / wrong-source-column banner** | Real guard ("the query likely selected the wrong source column — check the SQL"). High-trust, not depicted. | F8 |
| O11 | **Confidence auto-demotion on 0 rows + warn/confirm-before-run** | Real (HIGH→MEDIUM on 0 rows; LOW shows a "Confirm & Run" card with factors + open SQL). Mockup shows a static pill. | D1, G:warn |
| O12 | **Per-result feedback bar (thumbs + issue taxonomy)** | Real on every turn ("Was this useful?" + issue picker). Not depicted; it's how the system learns. | F14 |
| O13 | **"Ask again" / regenerate per turn** | Real re-run of stored SQL (icon button). Not depicted. | F15 |
| O14 | **Pivot synthesis ("break down by / filter to …")** | Real query-rewrite surfaced as `pivot`. Mockup shows a decorative "Pivot" link only. | F13 |
| O15 | **Empty-room "Editorial Index" (6 departments + answer-shape meta + hot dots)** | Real, substantial empty state. Mockups show generic help, not this department structure. | G:Editorial-Index |
| O16 | **Definition / citation chips under the chart** | Real `definition_refs` chips (shorthand/measure defs). Not depicted (mockup's `[1]` headline cite is a different, invented thing — B7). | F7 |
| O17 | **Inline enrich rail + ghost "+" header + money-override (ENRICH-006/020)** | Beyond the modal: a chips/browse suggestion rail + a ghost "+" table header + the realized-revenue money column with its treat-as-money override. The mockup's "Columns" popover doesn't represent these lighter inline affordances or the money tri-state. | H4, H5, H6 |
| O18 | **Enrichment-aware CSV (non-PII enrichments included; PII excluded)** | The real full-result export re-resolves added non-PII columns and excludes PII labels. A v3 export must honour this server-side behavior, not just dump the visible grid. | D2, H7 |

---

## 3. NEW / INVENTED — exclude from v3 → BACKLOG

The mockups invented these; none exist in the product. They must NOT appear in v3. (Items the prior backlog wrongly listed here that are actually REAL have been removed and moved to §1 — see the Correction Notice.)

| # | Invented feature | Mockup label / file | Value (1 line) | Effort | Adjacent to real? |
|---|------------------|---------------------|----------------|--------|-------------------|
| B1 | **In-place editable assumptions + "Re-run with changes"** ⭐founder-flagged | "Lore made these reads… Change any, then re-run" amber bar | Correct a wrong assumption and re-run without retyping | **L** | Adjacent to real read-only `insight_assumptions` (F3) — today assumptions are a display-only muted line, NOT editable, no re-run. |
| B2 | **"All Facebook is ads" / single-channel concentration WARNING (AI narrative)** ⭐founder-flagged | "lead note" / "Paid social = 100% of the stream" amber ⚠ | Reframes a verdict before the data misleads | **M** | Adjacent to real analyst notes (F4). NOTE: a Facebook *clarification* now ships (C6) — but this auto-WARNING narrative is a different, invented thing. |
| B4 | **Pinned metrics / pin a metric** | (implied by "pin") | Keep a KPI visible across queries | **M** | Net-new. |
| B5 | **Pin Memory drawer open (persist + `aria-pressed`)** | "Pin memory open" `pinBtn`, `lore_mem_pinned` | Drawer reopens on reload | **S** | Adjacent to real Memory Stack (A2); pin is new. |
| B6 | **Recents hovercard (zero-click peek of 3 recents)** | "Recents hovercard" | Hover the Memory trigger to peek/jump | **M** | Adjacent to real thread list (A2); hover-peek is new. |
| B7 | **Headline citation superscript `[1]`** | `.cite [1]` on the verdict | Academic-style citation on the verdict number | **S** | Adjacent to real `definition_refs` chips (F7/O16) but the `[1]` evidence-cite is invented. |
| B8 | **Export menu XLSX + Copy-as-TSV + Copy-SQL** (the non-CSV formats only) | "Export ▾ CSV·XLSX·TSV·SQL" | Multi-format export | **M** | The CSV item is REAL (D2, moved out). XLSX/TSV/Copy-SQL multi-format menu is new. |
| B10 | **"Load N more" progressive pager (mobile)** | "Load 100 more" / "100 / 1,284" | Incremental row loading | **M** | Adjacent to the real raise-cap (D3), but the real control re-runs the full SQL at a higher cap, not progressive append. |
| B11 | **"Allow multiple" disclosures toggle** | switch, "one-open-at-a-time by default" | Let pros open several disclosures at once | **S** | Adjacent to real disclosures deck (F8); the toggle is new. |
| B12 | **Breakdown disclosure as its own paged table/chart** | "Show breakdown (N rows)" + pager | Dedicated drill-into-rows panel | **M** | The live room intentionally REMOVED a separate breakdown drawer (it duplicated the table — `bi.js:7207`). Re-adding it is net-new scope. |
| B13 | **Tap-to-expand mobile row cards + row actions ("Open client", "Trace lineage")** | mobile expandable cards | Mobile row detail + lineage trace | **L** | Net-new; "Trace lineage" has no backend. |
| B14 | **Horizontal-scroll sticky-column table (power view)** | sticky name col + header | Wide-table power browsing | **M** | Adjacent to real table view; sticky impl is new. |
| B15 | **One-time command-desk coachmark** | "You're talking to a read-only ledger" + "Got it" | First-run education | **S** | Adjacent to real read-only posture; coachmark is new. |
| B16 | **Perishable keyboard hint (fades after typing)** | "Enter to ask · Shift+Enter…" fade | Teach the shortcut, then get out of the way | **S** | Adjacent to real Enter/Shift-Enter (B1 row); the fade is new. |
| B17 | **Submit "ticker" loader (dateline ticks + scanning bar)** | "LONDON 14:32 — querying…" progress bar | Branded in-place loader | **S** | Adjacent to real dateline-as-loader (G); the scanning bar is new polish. |
| B18 | **Vault picker menu with multiple vaults (CT/PayPlexo/Sandbox)** | "Switch vault" menuitemradio | Multi-vault switch UI | **S** | Real `vault-switcher` exists (A5); the multi-option styling is a mockup elaboration. |
| B19 | **Keyboard-shortcuts menu item / shortcuts surface** | user-menu "Keyboard shortcuts" | Discoverable shortcuts | **S** | Net-new. |
| B20 | **Confidence popover internals (meter at 58%, "How confidence is scored" link)** | meter + reasons list | Richer confidence explainer | **S** | Adjacent to real confidence drawer (D1) which has factors; the meter/"how scored" link is new chrome. |
| B21 | **"Pivot this result" affordance (as a button)** | minor disclosure "Pivot" | One-click pivot UI | **M** | Adjacent to real text-based pivot synthesis (F13); a UI control is new. |
| B22 | **Editable "Client scope" select (blended / CT-only / matched-deals)** | assumption select #4 | User overrides the data source per query | **L** | Adjacent to real server-side federation (F9); a user-facing source override does NOT exist and is risky (vault/source from session). Keep out. |
| B23 | **Return-to-answer flash animation on inquiry select** | headline flash | Visual cue when switching inquiries | **S** | Adjacent to real Memory Stack select (A2); animation is new. |
| B24 | **Memory drawer search (`/`-bound, instant highlight, day-group sticky headers)** | drawer search + `<mark>` | Find a past inquiry fast | **M** | Adjacent to real thread list (A2); search/highlight/day-grouping are new. |
| B25 | **Saved views / saved named queries** | (not depicted as such) | Persist & reload named analyses | **L** | NOT in mockups and NOT real — listed to keep it explicitly out of v3 scope. |

**Backlog summary by effort:** S = B5,B7,B11,B15,B16,B17,B18,B19,B20,B23 · M = B2,B6,B8,B10,B12,B14,B21,B24 · L = B1,B4(M),B13,B22,B25. Highest-value (later, not v3): **B1** (editable-assumptions re-runner — flagship, L, risky), **B2** (single-channel AI warning — founder-flagged), B24 (memory search).

---

## 4. Cross-cutting flags / ambiguities

- **The biggest correction is now positive:** the customize-columns chooser, row-limit raise-cap, full-result CSV export, and the facebook/proportion clarify cases all SHIP (the prior backlog's central claim — "the column chooser is dead/unreachable code with no endpoint and the modules don't exist" — was reading a stale tree). The modules (`column_enrichment`, `attribute_enricher`, `computed_measure_enrichment`, `pipedrive_enrichment`, `pii_attribute_resolver`, `canonical_columns`, `measure_enrichment`, `enrichment_merge`) all exist and are wired; endpoints `POST …/turns/{id}/columns/{attribute,measure,money,label}` + `GET …/full-result` are live. v3 must DEPICT these as real.
- **The one truly-dead artifact is different:** the Save-as-Segment modal + Pipedrive "Enrichments" fieldset in `renderQuickSegmentAction` (`bi.js:2128`) is reachable only via dead `renderQueryResult` (`bi.js:7747`, zero call sites). Do not confuse it with the live Customize-columns modal — and do not depict the Save-Segment modal in v3.
- **Export honesty:** the real full-result export includes non-PII enrichment columns and excludes PII (O18). A separate legacy `POST /queries/{id}/export`/`download` pair still 501s, but that is not the room's export path.
- **No user source/blended picker exists** — federation is session/server-decided. Any control that lets the user pick CT-vs-PD-vs-blended (B22) is invented AND violates "source from session, never model/user input." Keep out.
- **No feature flag** gates enrichment / customize-columns / row-limit / full-export. Only Federation (default OFF) and the follow-up router (default ON) are flagged — relevant if a v3 state depends on them.
- **"Inquiry" vs "query"/"insight" naming** is a mockup convention, not in code (code says "Run query", route "Insights", rail "Memory Stack"). A naming decision for v3, not a feature.

---

## Files
- Ground-truth inventory: `/home/stevan/.gstack/projects/lore/designs/bi-room-a-polish/ground-truth-inventory.md`
- This backlog: `/home/stevan/.gstack/projects/lore/designs/bi-room-a-polish/feature-backlog.md`
- Source of truth (main @ 5e19772): `/home/stevan/dev/lore-consolidate`