docs/LIVEBOARD_HANDOFF.md

# Liveboard Quality — Handoff Note

**Status:** NOT started. This is groundwork/diagnosis only. The current "data upgrade"
session focused on DATA quality (see `origin/develop_dg` @ `e769a68`); liveboard is the
next lever and untouched. Fix the **generation system** for any prospect — never tune to
the test companies or reverse-engineer the grader (see memory `fix-system-not-grader`).

## The problem
In `tests/e2e_quality.py`, every successful demo scores the liveboard **exactly 72/100
(18 pts)** — identical across 6+ very different companies. A constant like that is a
structural ceiling, not chance. The grader's critiques are consistent and *correct* (real
defects, not grader quirks). Per-defect detail lives in the latest
`tests/quality_results/*_quality_run.json` under `tests[].ai_grading.liveboard_weaknesses`.

## The 5 systemic defects (recurring across every run)
All live in the MCP + `enhance_mcp_liveboard()` flow — `liveboard_creator.py` ~line 4083,
the single supported liveboard path (MCP creates the board, this function post-processes
the exported TML and re-imports).

1. **Single-letter intro heading.** The intro tile's H1 is just the company's first letter
   ("C" Chipotle, "D" Dynatrace, "W" Wells Fargo). Gotcha: `enhance_mcp_liveboard` *already*
   removes note tiles (Step 2.5, ~line 4220) yet this one survives — so the MCP intro tile
   does NOT match the code's `note_tile` detection. Its real structure must be inspected in
   an actual exported TML. `create_branded_note_tile()` (~line 663) renders the full name
   correctly and is the intended replacement.
2. **Rate/average measures aggregated as SUM.** "Avg Selling Price", "CTR", "Revenue Per
   Billable Head" get summed → semantically wrong. Fix: detect rate/avg/ratio measures
   (fmt=`pct`, or name ∋ RATE/AVG/PCT/MARGIN/PER/PRICE) and set aggregation to AVERAGE.
3. **Raw/doubled display names.** "Total Total Order Revenue Usd", "Dim Region Name",
   "Fact Month Date_2". Needs a display-name cleanup pass.
4. **TABLE_MODE where a chart is intended.** Some trend/breakdown vizzes render as tables.
   Force CHART_MODE for those.
5. **No dedicated time-series line + inconsistent time windows** (last 12 / 18 / 24 months /
   none, mixed across vizzes). Add one explicit trend line and one consistent default window.

## The golden standard: `goldendemo/Vizio.com.liveboard.tml`
This is the gold standard to make `enhance_mcp_liveboard` output resemble. 48 vizzes. It
confirms every fix above:
- **Clean measure names** — `GrossSales`, `NetSales`, `UnitPrice`, `GrossMarginPct`,
  `CostAmount`, `DiscountAmount`, `ReturnAmount` (CamelCase; no Dim/Fact/Total-Total).
- **Correct aggregation** — `average [UnitPrice]`, `sum [GrossSales]` (per-measure semantics).
- **Rich time hierarchy** — `[FullDate].monthly/.weekly/.quarterly/.yearly/.'day of week'/
  .'month of year'`.
- **47 formula columns** — running totals, 3-month moving averages, growth, YoY (this year
  vs last year), forecasting (next 6 months).
- **Chart variety** — KPI, LINE, COLUMN, BAR, PIE, HEATMAP, SANKEY, BUBBLE, STACKED_*,
  ADVANCED_*, LINE_COLUMN, CUSTOM_CHART.
- **Consistent windows** — 'last 12 months', 'last 6 months', YoY. `display_mode: CHART_MODE`.

## How to do it right (constraints)
- **Work against a REAL exported TML.** The aggregation / display-name / display-mode fields
  live inside viz `answer` internals (`answer.columns`, `search_query`, `display_mode`) — NOT
  the outer schema. Editing against guessed paths will silently no-op or corrupt a working
  board. Export a recent graded board via `POST /api/rest/2.0/metadata/tml/export`, or use the
  goldendemo file for the target shape.
- **Add the fixes as guarded passes inside `enhance_mcp_liveboard`** (it already exports →
  post-processes → re-imports). Wrap each so a mis-fire degrades gracefully — liveboard
  creation currently WORKS; do not break it.
- **Verify each fix by export→modify→re-import against a live board.** Don't claim fixed
  without testing.

## Pointers
- Entry: `create_liveboard_from_model_mcp()` → `enhance_mcp_liveboard()` in `liveboard_creator.py`.
- Data-upgrade work (already done, for context): `origin/develop_dg` @ `e769a68` — added
  `share_of` (bounded parts), `per` (per-entity stable prices), dimension-richness + cost
  prompt guidance. Same "fix the system" philosophy applies to liveboards.