Main Street M3: Hint System

[SorraTheOrc]

Implement the hint generator and UI integration that lets players request a Greedy AI recommendation during MarketPhase.

User Story

As a player, I want to press a Hint button during my turn to see a suggested move highlighted with a brief explanation, so I can learn effective strategies.

Deliverables

• example-games/main-street/MainStreetHint.ts with generateHint(), buildRationale()
• hintUsedThisTurn state tracking, reset on DayStart
• Hint button in MainStreetScene with highlight rendering and rationale text display
• Unit tests: correct recommendation, per-turn limit, rationale text, MarketPhase-only

Acceptance Criteria

• Hint button visible during MarketPhase
• Pressing Hint queries GreedyStrategy for recommended action
• Recommended card is highlighted in market; target slot highlighted on grid (for buy-business)
• One-line rationale displayed (e.g., Buy Cafe at slot 5 for +2 synergy bonus)
• End-turn hint displays No good buys available -- end your turn
• Hint does not auto-execute the action
• Limited to 1 use per turn; button disabled after use until next turn
• Hint request recorded in game transcript
• All existing tests continue to pass

Dependencies

• Depends on: CG-0MMN8UTLC12Q1U2R (Greedy Strategy)

References

• PRD: docs/main-street/prd-milestone-3.md (US-3, Section 4.4, 5.5)

---

Related work (automated report)

• CG-0MMN8UTLC12Q1U2R — Main Street M3: Greedy AI Strategy and Scoring Heuristics (status: completed).
  This work implements GreedyStrategy and the helpers scoreAction() and enumerateAndScoreActions() that the hint generator should reuse to evaluate and rank candidate actions. GreedyStrategy's implementation is the primary source of truth for recommended moves.

• CG-0MMN8V9UU0MF2GHK — Main Street M3: Monte Carlo Harness Extension for AI Strategies (status: completed).
  Extends the Monte Carlo harness to run AI strategies (including Greedy). Useful for validation of hint quality and to generate sample scenarios for testing hint behavior across seeds.

• CG-0MMN8WCCD1AXQ2EU — Main Street M3: Transcript Extension for AI, Hint, and Undo Events (status: blocked).
  Specifies transcript schema additions required to record hint requests and undo/redo events. The hint implementation must record the hint request and rationale as a transcript event; this work item is the canonical reference.

• CG-0MM4REQ4C01X8C08 — Main Street: PRD Milestone 3 -- AI, Hints, and Undo System (status: in-progress, parent).
  The PRD contains detailed design, acceptance tests, and API sketches for hints (see section 4.4 and 5.5). Implementations should follow the API sketches (HintGenerator, HintResult) and acceptance criteria listed there.

• docs/main-street/prd-milestone-3.md (file)
  Design doc for Milestone 3 describing goals, success criteria, and a detailed hint architecture sketch. Useful for matching acceptance criteria and for tests referenced in the PRD.

• docs/main-street/ai-strategy.md (file)
  GDD section describing AI strategy tiers and hint-system design. Provides rationale and move-evaluation heuristics that inform buildRationale() templates.

Notes and conservative guidance:

• Prefer reusing GreedyStrategy's scoring helpers rather than duplicating heuristics; this keeps hints consistent with AI behaviour.
• Ensure hint transcript events follow the schema proposed in CG-0MMN8WCCD1AXQ2EU; coordinate with that item if schema details change.
• Use docs/main-street/prd-milestone-3.md acceptance tests (Appendix B) as the basis for unit tests listed in the Deliverables.

(Automated report generated by find_related skill)

[SorraTheOrc]

Map

Intake draft created at .opencode/tmp/intake-draft-Main-Street-Hint-System-CG-0MMN8VNCH0C6XKC4.md; transcript recording left to CG-0MMN8WCCD1AXQ2EU; one-line rationale; non-blocking UI. Review requested.

[SorraTheOrc]

Map

find_related report appended; coordinated decisions: transcript left to CG-0MMN8WCCD1AXQ2EU, one-line rationale, non-blocking UI. Intake brief saved to .opencode/tmp/intake-draft-Main-Street-Hint-System-CG-0MMN8VNCH0C6XKC4.md

[SorraTheOrc]

Map

Intake brief approved by user. Proceeding to effort and risk estimation and final sync.

[SorraTheOrc]

Map

Effort & risk estimate posted: expected ~30.7h (recommended 31h), Low-Medium risk. Suggested 1–2h spike to validate GreedyStrategy helper access and UI complexity. See attached estimate.