# HyperTwist Phase 4 template launch selector rationale packet

Created on `2026-05-07`

Status:

- first-party HyperTwist packet
- bounded Phase `4` dashboard template selection visibility slice

## Purpose

This packet surfaces why the dashboard preferred template won when analytics broke a primary-score tie.

The open tasks were:

- keep the new analytics tie-break behavior visible to operators
- stop forcing dashboard users to infer selector behavior from recap history alone
- explain tied-template resolution directly on the `[Template Launch]` detail surface

It is not:

- another template ranking rewrite packet
- a new analytics derivation packet
- a new dashboard page or interaction packet
- a template launch history redesign packet

## Scope

Bounded lane:

- let the preferred-template selector optionally emit a short rationale string
- build a concise stored-outcome signal summary for winner-versus-peer analytics tie-breaks
- append that rationale to the current dashboard `[Template Launch]` detail only when analytics actually decided the winner

Out of scope:

- changing primary review or recovery template priority rules
- persisting selector rationale into run history
- adding rationale to recap or template-history rows
- changing launch button behavior

## Why this was the right next packet

The previous packet made tied template selection smarter by using stored success and mistake signal.

That immediately created one obvious product gap:

- the dashboard now made a better choice
- but operators could not see why that choice beat an equally ranked peer
- and the selector still looked opaque unless someone manually compared historical analytics elsewhere

So the next honest move was:

- keep the selector logic centralized
- expose the tie-break explanation on the same surface where the preferred template is presented
- and only show that explanation when analytics actually moved the decision

## What landed

Primary code changes:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistCoachDashboardWidget.h`
  - widened `FindPreferredDashboardTemplateLaunch(...)` so callers can request a selector rationale string
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistCoachDashboardWidget.cpp`
  - added helper formatting for template display titles and concise tie-break outcome signal summaries
  - taught the preferred-template selector to emit a rationale when analytics prefer one tied template over another
  - appends that rationale to the dashboard `[Template Launch]` detail line only when the analytics tie-break fired

## Product effect

The dashboard template lane is now explainable at the moment of action:

- operators still see the same preferred template and launch affordance
- when the selector chose between equally ranked peers using stored analytics, the detail line says so directly
- the explanation identifies the tied peer and the stored outcome signal that favored the chosen template
- when analytics were not involved, the detail surface stays unchanged

## Acceptance criteria

- preferred dashboard template selection still uses the existing primary ranking rules
- selector rationale only appears when analytics broke a tie
- rationale text is shown on the `[Template Launch]` detail surface
- full product build succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln` / `UnrealHyperTwistEditor`
2. confirm tied preferred-template selections append a selector rationale on the dashboard detail line
3. confirm non-tied or primary-score-decided selections do not show the extra rationale text
4. confirm launch behavior itself remains unchanged

That is the packet.
