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.