[SCENARIO] Explainable Readiness Experience

[shchukins]

Problem

A readiness score without causal context is hard to trust. The user needs a compact explanation of why readiness changed, based on deterministic model components rather than generic narrative.

User-facing flow

1. Backend computes readiness from load and recovery state.
2. Backend produces structured explanation factors from model components.
3. API returns machine-readable factors plus concise user-facing reason text.
4. iOS and Telegram display the same explanation without running model logic locally.
5. Trend and metric context help the user understand the answer without turning the product into a raw dashboard.

Definition of done

• Readiness responses include deterministic explanation factors.
• Explanation factors distinguish load, recovery, trend, missing data, and fallback modes.
• iOS presents concise positive/negative factors and missing-data indicators.
• Metric docs stay synchronized with displayed model behavior.
• Trend visualization supports interpretation without creating a fake secondary score.
• Tests cover explanation outputs for high fatigue, poor recovery, improving freshness, missing data, and fallback modes.

Linked existing issues

• [Feature] Readiness stability and volatility analytics #37
• [Feature] Readiness explanation layer #50
• [Feature] Readiness, fatigue, and recovery trend visualization #53
• [EPIC] Metrics layer & explainability (Athlytics-inspired) #56
• [Feature] Extract metrics layer (fatigue, recovery, readiness) #57
• [Feature] Metric-level documentation (formula + explanation) #58
• [Feature] iOS explainable readiness presentation #59
• [Feature] Unit tests for core metrics #60
• [Feature] Dynamic semantic slogan system for Human Engine branding #81

Migration note

Created from the accepted end-to-end epic proposal in docs/product/END_TO_END_EPICS_PROPOSAL.md. Existing technical explainability issues remain open and linked here for continuity.