Skip to content

Make the POST cognitive drill how-to cards reachable after the first run #4732

Description

@atomantic

Problem

The POST cognitive drills show a first-run how-to card (DrillTutorialGate in client/src/components/meatspace/post/PostCognitiveDrillRunner.jsx), gated on a per-type flag in localStorage (portos.post.drillTutorialSeen). It is one-shot per drill type, forever — the card itself says "You'll only see this the first time for each drill type."

That is right for the flash-of-stimulus problem it was built for, but it leaves no way back. The n-back card now carries a worked example strip (the letter stream with the one match called out) precisely because the rule is easy to misread — and after the first run that example is unreachable. A user who last did n-back weeks ago gets no refresher, and there is no way to preview a drill type without starting a scored run.

Approach

Add a "How it works" affordance to the drill screen itself, next to the DrillHeader label. Tapping it re-shows CognitiveDrillTutorial for the current type.

Decision on the mechanic (do not re-litigate): do not re-open the tutorial mid-run. The runners are timed and startedAtRef is stamped at mount, so unmounting a live drill would either lose the run or record a bogus totalMs. Instead, show the affordance only in the pre-roll window — n-back's 800ms Get ready… phase and each runner's equivalent — or, simpler and preferred, put the entry point on the launcher (PostSessionLauncher.jsx / PostDrillConfig.jsx) as a per-drill-type "preview how it works" that renders the same CognitiveDrillTutorial with no runner behind it. That keeps the timed path untouched.

getDrillTutorial(drill) is already a pure data function and CognitiveDrillTutorial already renders standalone, so both are reusable as-is; the drill payload needed for config-dependent copy (n-back lag, digit-span direction, reaction-time mode) is available at config time.

Acceptance criteria

  • A user can view any cognitive drill type's how-to card, including the n-back worked example, without starting a scored run.
  • The first-run gate keeps working unchanged: still one-shot per type, still holds the runner's timers until Start.
  • No path re-mounts a live runner, and no drill result records a totalMs that includes time spent reading the tutorial.
  • Test coverage for the new entry point alongside the existing "first-run tutorial gate" block in PostCognitiveDrillRunner.test.jsx.

Metadata

Metadata

Assignees

No one assigned

    Labels

    model:mediumDispatch capability: routine workhorse modelplanTracked by /do:replanuxProposed from a UX/design audit

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions