Skip to content

Add Mack Mercer route-aware tutorial assistant#72

Closed
KevinBigham wants to merge 1 commit into
mainfrom
goal/tutorial-assistant-v1
Closed

Add Mack Mercer route-aware tutorial assistant#72
KevinBigham wants to merge 1 commit into
mainfrom
goal/tutorial-assistant-v1

Conversation

@KevinBigham
Copy link
Copy Markdown
Owner

Summary

  • Adds the V1 in-game Tutorial Assistant (Mack Mercer): global chip + expanded panel mounted in AppLayout and on Setup/Onboarding via the routes/index PreGameAssistantMount.
  • Route-aware guidance for all 31 major routes (incl. alias/dynamic normalization), plus "What now?" next-action with phase/route overrides, "Explain ratings", "Deeper strategy", deterministic ticker/phase story callbacks with per-callback cooldowns, Newcomer/Hardcore modes, dismiss/replay/Got-it, Escape-to-close, and save-scoped localStorage persistence — GameSnapshot schema unchanged at v33.
  • Tutorial-assistant docs: goal contract, progress, Phase 0/1 audits, character/UX/trigger/asset specs, ratings-visibility audit, coverage matrix, playtest plan, release gate, completion audit, and Claude Code's independent review (docs/tutorial-assistant/claude-code-audit-2026-05-05.md).

Test plan

  • pnpm --filter @mbd/web typecheck — clean
  • pnpm --filter @mbd/web test -- --run src/features/assistant src/app/routes/index.test.tsx src/app/layout/AppLayout.test.tsx — 21/21 passed
  • pnpm --filter @mbd/contracts test — 18/18 passed
  • pnpm run verify:determinism — 3/3 passed
  • pnpm --filter @mbd/web build — succeeds, dist + PWA precache regenerated
  • Closed-tester playtest at desktop and 390x844 mobile (first-session script in docs/tutorial-assistant/playtest-plan.md)
  • Optional Mack Mercer portrait/expression art slice
  • Optional OVR/rating badges in any dense decision tables that playtest flags as confusing

🤖 Generated with Claude Code

Adds the V1 in-game Tutorial Assistant (Mack Mercer):

- Global Assistant chip + expanded panel mounted in AppLayout for the
  initialized shell, with a pre-game mount on Setup and Onboarding via
  the routes/index PreGameAssistantMount.
- Route-aware guidance for all 31 major routes, including alias and
  dynamic-route normalization (`/league/standings`, `/players/:id`,
  `/games/:id`).
- "What now?" next-action suggestion with phase/route overrides
  (offseason -> checklist, playoffs -> matchup, deadline window ->
  trade/budget, hardcore vs newcomer mode tweaks).
- "Explain ratings" and "Deeper strategy" expanders, plus deterministic
  story callbacks driven by phase/day/season + ticker feed with
  per-callback cooldowns.
- Newcomer / Hardcore modes, dismiss / replay / Got-it controls,
  Escape-to-close, save-scoped localStorage persistence keyed by save
  id/slot — `GameSnapshot` schema unchanged at v33.
- Tutorial-assistant docs: goal contract, progress, phase 0/1 audits,
  character/UX/trigger/asset specs, ratings-visibility audit, coverage
  matrix, playtest plan, release gate, completion audit, and Claude
  Code's independent review.

Validation:

- pnpm --filter @mbd/web typecheck: clean
- pnpm --filter @mbd/web test (focused: assistant + AppLayout +
  AppRoutes): 21/21 passed
- pnpm --filter @mbd/contracts test: 18/18 passed
- pnpm run verify:determinism: 3/3 passed
- pnpm --filter @mbd/web build: succeeds, dist/ + PWA precache regenerated

Known follow-ups (V1+):

- Generated Mack Mercer portrait/expression art slice.
- Closed-tester playtest, especially mobile copy-density feedback at
  390x844.
- Optional OVR/rating badges in any dense decision tables that playtest
  reveals as confusing.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@KevinBigham
Copy link
Copy Markdown
Owner Author

Closing without merge after a fresh review against current main.

Summary of the decision (rationale shared with Kevin in the planning conversation):

  • Stale base. PR is 9 days behind main. Main has moved through LC-1→LC-6 launch candidates plus Sprint 1 cleanup since (60+ commits, ~5,400 net LOC of change on top of the LC stack). Both apps/web/src/app/layout/AppLayout.tsx and apps/web/src/app/routes/index.tsx shifted; rebase would be substantial.
  • Overlaps with shipped surfaces. The codebase already has four guidance/help layers: the AGM-driven Day-One flow at /onboarding, the unused Revised onboarding API that Sprint 2 (Sprint 2 — Revised onboarding becomes canonical #75) is about to canonicalize, the LC-2 guided-start nudges in features/onboarding/nudges/, and the page-help hover content via shared/lib/pageHelpDefinitions.ts. Adding a fifth global Mack Mercer chip on top makes the help/onboarding UX more confusing, not less.
  • v1.0.0 shipped without it. Product is stable in production without this feature.
  • Cuts against the v1.0.1 bar: "0 errors, easy to understand, runs like a G." More surface = more to maintain.

The work is not lost — the branch goal/tutorial-assistant-v1 and the safety-preserve branch preserve/tutorial-assistant-v1-local-2026-05-08 stay intact. If a future iteration of the assistant character makes sense, the artifact is here to revive, but it would need to be redesigned against the Revised onboarding flow (Sprint 2) and against the existing guided-start nudges + page-help layers to avoid stacking.

Related: PR #73 (draft) is intentionally left as-is per Kevin's instruction.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant