The problem I needed to solve
When a Hokm bug appears only near a hand’s end, replaying every stage is a slow way to investigate it. I needed observation and controlled state construction.
Implementation in this snapshot
HokmDebugQaTools.BuildSnapshot gathers players, hand, trick and match state. ForceHakemForNewHand, ForceTrump and SetTrickScoreForDebug can construct a targeted scenario.
The design decision and its cost
Snapshot construction is separate from final presentation, and FormatSnapshot produces readable text. Score editing checks numeric limits to avoid completely meaningless debug input.
Current boundaries
Debug tools are not product certification. The presence of runtime testers or a documentation report does not mean I ran them successfully against this export; that requires Unity and the complete scene.
Constructing a near-ending state for investigation
Suppose an issue appears only at six tricks each. SetTrickScoreForDebug can reset hand state, set trump and increment team counts through AddTrickPoint. This replaces playing every card for a targeted investigation, but does not generate the actual earlier trick history. The constructed state suits a bounded question, such as how hand completion behaves at those counts. It should not be presented as evidence from a naturally played match with every preceding event.
BuildSnapshot collects hands, controller types, Hakem, dealer, active seat, leader, suits and both scoring cycles. It skips assignments without players and substitutes defaults such as Seat0 or zero for some missing states. That permits incomplete reports, but readers must distinguish defaults from verified state. Zero does not necessarily mean a match genuinely started at zero. FormatSnapshot labels trick and match scores separately in its readable report.
Mutation tools reject negative scores and values above the configured target. Those bounds do not prove consistency among card counts, current trick and animation flow. ForceTrump and ForceHakemForNewHand convert state-operation exceptions into Failure results for explicit feedback. This study describes code and documentation capabilities; successful runtime testers or complete QA require Unity and the full scene. Debug-tool availability is not a report of executed tests.
What this stage taught me
These tools let me ask precise questions about actual state. For me, that means less guessing: identify which stage and data are wrong before investigating appearance or rules.
