Help Icon Documentation Audit
This audit records the documentation source-of-truth work that should happen before the site-wide structured help migration. It is intentionally documentation-first: page help should summarize the current docs and known gaps rather than become a separate source of truth.
Audit date: 2026-05-10.
Current Findings
The frontend currently has roughly 128 help-related usages across Card.info, PageGuide, HelpLabel, InfoTooltip, and the Model Explorer's custom HelpIcon. The implementation is functional, but inconsistent:
| Area | Current state | Issue to fix in structured-help pass |
|---|---|---|
| Shared card help | Most cards use Card info=... with short strings or ad hoc JSX. | Many tooltips are unstructured paragraphs and do not consistently say how to use the metric, what not to infer, or what source gaps exist. |
HelpLabel labels | Labels inherit local casing such as uppercase section headers, title case form labels, or sentence case page text. | The icon itself is consistent, but label casing around it is inconsistent and makes the help pattern feel uneven. |
Model Explorer custom HelpIcon | Uses a separate implementation from the shared InfoTooltip. | Migrate to the shared structured help system so model-tree help behaves like the rest of the site. |
| Page guides | Probability, Performance, Model Explorer, Model Lab, Data Capture, and Trade Book already use guide cards. | Good pattern to keep, but guide info should use the same sectioned help structure as tooltips. |
| Measurement pages | Performance now has the most complete caveats, including unavailable-is-not-zero and adjusted-contract proxy language. | Use Performance as the model for Data Capture and Trade Book, but keep source-status caveats current. |
| Market setup pages | Many chart cards have concise help. | Add source/freshness limitations and interpretation boundaries only where relevant; avoid bloating simple live-market cards. |
Documentation Refresh Completed For This Audit
The Performance-related docs were stale after the latest production backfill. They now reflect the current production state:
| Topic | Current documented state |
|---|---|
| Alpha execution rows | 751 default Performance population. |
| Opportunity context | 749/751 scored; 2 insufficient. |
| Opportunity headline | 61.5% supportive among 524 decisive rows. |
| Alignment distribution | 322 supportive, 225 mixed/no-edge, 202 opposing, 2 insufficient. |
| Execution benchmarks | 331/751 quoted, 420/751 unavailable. |
| Execution liquidity | 331 partial, 250 unavailable, 170 not sourced; contract volume/OI rows remain 0. |
| 7d forward outcomes | 177/751 available, 1 pending, 573 unavailable. |
| Position coverage | 284 derived positions: 208 closed, 8 open long, 68 open short. |
| Realized P&L | Not sourced; must remain withheld until authoritative accounting/lifecycle data exists. |
The following rules are now current in the docs and should be repeated in high-value help icons:
- Unavailable is not zero.
- Partial coverage is not failure.
- Opportunity context is not P&L.
- BTC proxy context is market backdrop, not MSTR/COIN execution liquidity.
- Execution quality is readable only for rows with sourced MSTR/COIN contract quotes.
- Forward outcome P&L and hit rate are readable only for rows with sourced forward marks.
2MSTRand2COINstandard-root fallback is temporary analysis coverage, not authoritative adjusted-contract valuation.
Page-Level Help Migration Plan
| Page / area | Documentation source | Current help quality | Missing or high-value structured sections | Priority |
|---|---|---|---|---|
| Performance | USER_JOURNEY.md, TRADE_PERFORMANCE_ANALYTICS.md, TRADE_PERFORMANCE_DATA_GAPS.md, TRADE_PERFORMANCE_BUSINESS_ISSUES.md | Good and recently improved. | Convert all remaining one-line cards to structured sections: what it means, how to use it, coverage/gaps, what not to infer. | P0 |
| Data Capture | OPERATOR_RUNBOOK.md, DATA_DICTIONARY.md, snapshot diagrams | Good page guide, but card help is still terse. | Add freshness semantics, schedule expectations, probability-readiness boundaries, and warning/error interpretation. | P0 |
| Probability | USER_JOURNEY.md, CALCULATION_REFERENCE.md, probability diagrams | Strong page guide and chart help. | Standardize vanilla/conditional/CDF/delta help; include stationarity/blend caveats and candidate-screen boundaries. | P0 |
| Model Explorer | USER_JOURNEY.md, SIGNAL_MODEL_FLOWCHART.md, decision tree content | Rich content but separate custom help implementation. | Replace custom help with structured shared help; preserve node-specific source/gap warnings. | P1 |
| Model Lab | USER_JOURNEY.md, model-lab scenario diagram | Good process help and parameter help. | Tighten disabled-roadmap caveats, production-default boundary, and export-only behavior. | P1 |
| Trade Book | alpha-trade-sync.md, trade-feed diagrams | Good sync controls and read-only table help. | Add stronger source-row interpretation and sync-completeness caveats. | P1 |
| Market Setup charts | USER_JOURNEY.md, CALCULATION_REFERENCE.md, screen-to-source map | Mostly concise chart definitions. | Add gaps only where relevant: live-vs-persisted distinction, provider retention/field limitations, and source freshness. | P2 |
| Reference pages | Generated from docs/. | Read-only source of truth. | Keep lighter; do not add heavy tooltip content unless it aids navigation. | P3 |
Structured Help Content Standard
The later implementation should migrate important help items to this shape:
| Section | Purpose |
|---|---|
What this means | Plain-language metric/control definition. |
How to use it | Operator action or interpretation. |
Coverage and gaps | Data availability, source constraints, and current limitations. |
What not to infer | Prevents common misreads such as treating unavailable as zero. |
References | Links to Reference docs where the full methodology lives. |
Not every tooltip needs every section. Simple market charts can stay concise. Measurement, model-confidence, probability, scenario, and source-readiness help should use the full structure.
Open Issues To Surface In Help Where Relevant
| Issue | Where to surface |
|---|---|
Authoritative adjusted-contract mapping/deliverables for 2MSTR and 2COIN are still missing. | Performance Data Readiness, Execution Quality, Forward Outcomes. |
| Amberdata MSTR/COIN historical quote coverage is partial and sometimes returns empty data for exact instruments/timestamps. | Performance Execution Benchmarks, Data Gaps, future Amberdata reliability work. |
| Contract volume and open interest are not populated in current execution-liquidity rows. | Performance Execution Liquidity. |
| Forward outcome coverage remains partial. | Performance Outcome Availability and attribution tables. |
| Realized P&L is not sourced. | Performance Realized P&L and Position Coverage. |
| Strategy intent is not available from Alpha; buy=long-vol and sell=short-vol remain assumptions. | Opportunity Alignment, Trade Drilldown, Trade Book. |
| Snapshot freshness and probability readiness are separate checks. | Data Capture and Probability. |
| Conditional probability outputs depend on stationarity and blend weight. | Probability and Model Explorer. |
| Model Lab runs request-scoped scenarios only; it does not change production defaults. | Model Lab. |
Definition Of Done Before Structured Help Migration
- Reference docs reflect the current production state and known gaps.
- In-app generated reference content is regenerated from
docs/. - The structured help component has a defined section model.
- High-priority pages are migrated first, beginning with Measurement and Probability.
- Existing one-line help should only remain where a metric is simple and has no meaningful source caveat.