@zigrivers/scaffold 3.4.1 → 3.5.1

package/content/knowledge/review/review-game-ui.md

@@ -0,0 +1,293 @@
+---
+name: review-game-ui
+description: Failure modes and review passes specific to game UI specifications — HUD hierarchy, menu navigation, controller accessibility, settings coverage, FTUE effectiveness, state machine completeness, and platform shell compliance
+topics: [game-dev, review, ui, hud, menus, controller, accessibility, ftue]
+---
+
+# Review: Game UI Specification
+
+A game UI specification must translate game mechanics into clear, navigable, accessible interfaces. It must be hierarchical (HUD elements prioritized by gameplay criticality), complete (every menu has a path back, no dead ends), accessible (every screen reachable with controller), configurable (settings cover graphics, audio, controls, accessibility), and platform-compliant (system UI respects console certification requirements). This review uses 7 passes targeting the specific ways game UI specifications fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+## Summary
+
+- **Pass 1 — HUD Information Hierarchy**: HUD elements are prioritized by gameplay criticality; health, ammo, and objective markers are visible at a glance; non-critical information is layered or hidden behind contextual triggers.
+- **Pass 2 — Menu Completeness & Navigation**: Every menu has a path back, no dead ends exist, breadcrumb trail is clear, and the menu tree covers all player-facing systems without orphaned screens.
+- **Pass 3 — Controller Accessibility**: Every screen is reachable with D-pad, focus order follows spatial layout, shoulder buttons switch tabs, and no interaction requires mouse/touch to complete.
+- **Pass 4 — Settings Coverage**: Graphics, audio, controls, and accessibility settings are present with appropriate ranges; no critical setting is missing; defaults are sensible for target hardware.
+- **Pass 5 — FTUE Effectiveness**: Tutorial teaches core mechanics without blocking progress; skip option is available; re-access to tutorial information exists; no mechanic requires undocumented player discovery.
+- **Pass 6 — UI State Machine Completeness**: Every UI state has defined entry and exit conditions; no orphan states exist; all transitions are handled including error, disconnect, and loading states.
+- **Pass 7 — Platform Shell Compliance**: System UI respects platform conventions (PS button, Xbox guide, Switch home); notification handling is specified; console certification UI requirements are addressed.
+
+## Deep Guidance
+
+---
+
+## Pass 1: HUD Information Hierarchy
+
+### What to Check
+
+HUD elements are prioritized by gameplay criticality. Health, ammo, objective markers, and minimap are visible at a glance without eye movement from the center of the screen. Non-critical information (XP progress, currency, social notifications) is layered — hidden by default and surfaced contextually. The HUD does not present more than 5-7 simultaneous elements during active gameplay.
+
+### Why This Matters
+
+HUD overload causes players to miss critical gameplay information. When health, ammo, minimap, quest tracker, XP bar, currency, social notifications, buff timers, and cooldown indicators all compete for attention simultaneously, players die because they did not notice their health was low — the information was there, but buried in noise. Conversely, a HUD that hides too much forces players to open menus mid-combat. The hierarchy must match gameplay criticality.
+
+### How to Check
+
+1. List every HUD element and classify as critical (player dies without it), important (gameplay quality degrades without it), or contextual (useful but not time-sensitive)
+2. Verify critical elements are visible without eye movement from screen center — use screen quadrant analysis
+3. Check that contextual elements have defined show/hide triggers (e.g., XP bar appears for 3 seconds after earning XP, then fades)
+4. Count simultaneous elements during peak gameplay — more than 7 concurrent elements indicates overload
+5. Cross-reference with GDD mechanics: every mechanic with player-visible feedback must have a corresponding HUD element
+6. Verify HUD scales with resolution — elements positioned by percentage, not fixed pixels
+7. Check for HUD customization: can the player move, resize, or hide HUD elements?
+
+### What a Finding Looks Like
+
+- P0: "Health indicator is positioned in the bottom-left corner, 800+ pixels from screen center. In fast-paced combat, players must look away from the action to check health. Health must be near the reticle or use screen-edge vignette effects."
+- P1: "14 HUD elements are visible simultaneously during combat. This exceeds cognitive load limits. Non-critical elements (XP bar, currency, social notifications) should be contextual, not persistent."
+- P2: "HUD layout is specified in fixed pixel coordinates (health at 50,720). This will break at non-1080p resolutions. Use percentage-based or anchor-based positioning."
+- P3: "HUD element for combo counter exists but no fade timing is specified. Define how long the counter persists after the last hit (recommended: 3-5 seconds)."
+
+---
+
+## Pass 2: Menu Completeness & Navigation
+
+### What to Check
+
+Every menu screen has a clear path back to the parent screen. No dead-end screens exist (screens with no exit path). The breadcrumb trail is visible at all times. The menu tree covers all player-facing systems (inventory, settings, social, store, leaderboards, achievements) without orphaned screens that are reachable only through obscure paths.
+
+### Why This Matters
+
+Incomplete menu trees strand players. A settings screen with no back button forces the player to restart the game. A crafting menu reachable only through a specific NPC but not from the inventory screen creates confusion. Players who cannot find a feature assume it does not exist — a hidden feature is a missing feature. Menu navigation should be exhaustively mapped, not discovered through play.
+
+### How to Check
+
+1. Build a complete menu tree from the UI spec — every screen, every transition, every button
+2. Verify every screen has a back/escape path — no leaf node should be inescapable
+3. Check for orphaned screens: screens not reachable from the main menu or hub screen through documented navigation
+4. Verify breadcrumb visibility: does the player always know where they are in the menu hierarchy?
+5. Check for consistent navigation patterns: does "B button" always mean "back"? Does "Start" always open the pause menu?
+6. Verify that all player-facing systems appear in the menu tree: inventory, settings, social, store, map, journal, achievements, leaderboards, help
+7. Check menu depth: menus deeper than 3 levels should be reconsidered — deep menus hide features
+
+### What a Finding Looks Like
+
+- P0: "The crafting submenu has no back button or escape path. Once entered through the NPC dialog, the only exit is closing the game. The screen is inescapable."
+- P1: "Accessibility settings are nested under Gameplay > Advanced > Accessibility — 3 levels deep. Players who need these settings most are least likely to find them. Move to a top-level settings tab."
+- P2: "Leaderboard screen is reachable from the post-match screen but not from the main menu. Players cannot browse leaderboards outside of match flow."
+- P3: "Menu transition animations are not specified. Define whether transitions are instant, slide, or fade and their duration (recommended: 150-250ms)."
+
+---
+
+## Pass 3: Controller Accessibility
+
+### What to Check
+
+Every screen is fully navigable with a gamepad D-pad. Focus order follows spatial layout (left-to-right, top-to-bottom). Shoulder buttons switch between tabs. No interaction requires a mouse pointer, touch input, or keyboard to complete. Focus indicators are clearly visible with sufficient contrast.
+
+### Why This Matters
+
+Console games and PC games with controller support must be fully navigable without a mouse. A single screen that requires mouse input breaks the controller experience entirely — the player must put down their controller, find their mouse, click, and pick the controller back up. This is a console certification failure for PlayStation, Xbox, and Nintendo platforms. Even on PC, controller users expect full navigation support.
+
+### How to Check
+
+1. For every screen, verify that all interactive elements are reachable via D-pad navigation
+2. Check focus order: does it follow spatial layout? (Left-to-right, top-to-bottom, matching visual hierarchy)
+3. Verify tab switching: shoulder buttons (L1/R1 or LB/RB) switch between tabs in tabbed interfaces
+4. Check that focus indicator is clearly visible: minimum 3px border or highlight with 4.5:1 contrast ratio
+5. Verify that no interaction requires a cursor: dropdowns, sliders, text input, scrolling all work with D-pad
+6. Check for focus traps: UI elements that capture focus and prevent D-pad navigation away (common with custom widgets)
+7. Verify that wrapping behavior is consistent: does D-pad right on the last column wrap to the first column of the next row, or stop?
+
+### What a Finding Looks Like
+
+- P0: "The server browser uses a mouse-driven scrollable list with no D-pad navigation. Controller users cannot select a server. This is a console certification blocker."
+- P0: "Text input for player name uses a mouse-clickable keyboard with no controller support. Console players cannot complete account creation."
+- P1: "Focus order in the inventory grid goes left-to-right then jumps to a panel on the right, skipping the second row. Focus order does not match spatial layout."
+- P2: "Focus indicator is a 1px white border on a light gray background. Contrast ratio is approximately 1.5:1 — below the 4.5:1 minimum for visibility."
+
+---
+
+## Pass 4: Settings Coverage
+
+### What to Check
+
+Settings screen covers all five minimum categories: graphics/video, audio, controls/input, gameplay, and accessibility. Each category has appropriate settings with sensible ranges. No critical setting is missing (resolution, volume, subtitle toggle, colorblind mode, control remapping). Default values are appropriate for target hardware.
+
+### Why This Matters
+
+Missing settings force players to accept defaults that may not suit their hardware, preferences, or needs. A game without a resolution setting alienates players with non-standard monitors. A game without subtitle options excludes deaf and hard-of-hearing players. A game without control remapping fails accessibility standards (and Xbox/PS certification). Settings are not optional features — they are baseline requirements.
+
+### How to Check
+
+1. Verify graphics settings: resolution, display mode (fullscreen/windowed/borderless), frame rate cap, V-sync, quality presets, individual quality settings (textures, shadows, anti-aliasing, draw distance)
+2. Verify audio settings: master volume, music volume, SFX volume, voice volume, subtitle toggle, subtitle size, audio output selection
+3. Verify control settings: control remapping, sensitivity sliders (camera, aim), invert Y-axis, vibration toggle, dead zone adjustment
+4. Verify accessibility settings: colorblind mode (protanopia, deuteranopia, tritanopia), font scaling, screen reader support, reduced motion, high contrast mode
+5. Verify gameplay settings: difficulty selection (if applicable), HUD customization, language selection, camera distance
+6. Check setting ranges: sensitivity sliders should have wide enough ranges (not just 1-10 but 0.1-5.0 or similar), resolution should include common values
+7. Verify that changed settings are previewed in real-time where possible (audio slider plays a sample, graphics changes show before confirm)
+
+### What a Finding Looks Like
+
+- P0: "No control remapping exists. Players who cannot use the default layout due to physical disabilities are locked out. This is an accessibility requirement and a platform certification blocker."
+- P0: "No subtitle toggle exists. Deaf and hard-of-hearing players cannot follow narrative content. This is an accessibility baseline."
+- P1: "Colorblind mode is listed as 'colorblind: on/off' without specifying which type. Protanopia, deuteranopia, and tritanopia require different palette adjustments — a single toggle is insufficient."
+- P2: "Graphics quality has 3 presets (Low, Medium, High) but no individual settings. Players with specific hardware constraints cannot optimize (e.g., low shadows but high textures)."
+- P3: "Audio settings do not include a 'dialogue boost' option. While not required, this is a common accessibility feature that improves clarity for hearing-impaired players."
+
+---
+
+## Pass 5: FTUE Effectiveness
+
+### What to Check
+
+The First Time User Experience (FTUE) teaches all core loop mechanics without blocking player progress. A skip option is available for returning players or replays. Tutorial information is re-accessible after completion (help menu, practice mode, or tooltip system). No core mechanic requires the player to discover it without guidance.
+
+### Why This Matters
+
+A bad FTUE either overwhelms (teaching every system in the first 10 minutes) or under-teaches (leaving players to discover critical mechanics by accident). Both cause churn: overwhelmed players quit because the game feels complex, under-taught players quit because they feel lost. The FTUE must pace instruction to match the player's cognitive load, teach mechanics in context (during gameplay, not via text walls), and provide an escape hatch for experienced players who do not need hand-holding.
+
+### How to Check
+
+1. List every core loop mechanic — movement, combat, inventory, crafting, social, economy
+2. Verify each mechanic has a tutorial moment: in-context prompt, guided task, or practice scenario
+3. Check tutorial pacing: no more than 2-3 new mechanics introduced per tutorial segment
+4. Verify skip option: can the player skip the entire tutorial? Individual tutorial steps? Is the skip accessible from the first prompt?
+5. Check for re-access: after completing the tutorial, can the player re-read instructions? Is there a help menu, codex, or practice mode?
+6. Verify that the tutorial does not block progress: can the player proceed if they fail a tutorial challenge? Is there a retry with hints?
+7. Check for advanced mechanics: are they taught later in gameplay (progressive disclosure) or dumped in the opening tutorial?
+
+### What a Finding Looks Like
+
+- P0: "Combat tutorial requires the player to defeat a training dummy to proceed, but no hint system exists if the player fails 3+ times. A player who cannot complete the tutorial is permanently stuck."
+- P1: "Crafting system is never taught. The player must discover it by opening the inventory and finding a 'Craft' tab. 60% of players may never discover this core system."
+- P1: "All 8 core mechanics are taught in a single 25-minute unskippable tutorial. Player drop-off during tutorials longer than 10 minutes exceeds 40%."
+- P2: "Tutorial is skippable but no help menu or re-access exists. A player who skips the tutorial and later needs guidance has no recourse."
+
+---
+
+## Pass 6: UI State Machine Completeness
+
+### What to Check
+
+Every UI state has defined entry conditions, exit conditions, and transitions to other states. No orphan states exist (states with no entry path). No terminal states exist except intentional ones (quit game). Error states, disconnect states, and loading states are explicitly handled. State transitions are deterministic — no ambiguous transitions where two states compete.
+
+### Why This Matters
+
+Incomplete UI state machines are the primary source of UI softlocks — states the player enters but cannot exit. When the game shows a loading screen but the load fails silently, the player is stuck forever. When a disconnect occurs during a menu transition, the UI may be in an undefined state. When a modal dialog opens on top of another modal, focus may be lost. Every state transition must be mapped, including the error and edge-case transitions that are easy to forget.
+
+### How to Check
+
+1. List every UI state: main menu, loading, in-game HUD, pause menu, inventory, settings, store, matchmaking, post-match, error dialog, disconnect overlay
+2. For each state, define: what triggers entry? What triggers exit? What are all possible transitions?
+3. Check for orphan states: states that exist in the design but have no defined entry path
+4. Check for softlock potential: states that can be entered but have no exit transition (especially error states)
+5. Verify loading states: every loading screen has a timeout and error fallback (not infinite spin)
+6. Check disconnect handling: every state has a defined behavior when network connectivity is lost
+7. Verify modal stacking: what happens when a system notification triggers while a game dialog is open? Is there a priority queue?
+
+### What a Finding Looks Like
+
+- P0: "Loading screen has no timeout. If asset loading fails silently, the player is stuck on the loading screen indefinitely with no error message and no exit path."
+- P0: "Matchmaking state has no cancel button. Once matchmaking begins, the player cannot return to the main menu without force-quitting the application."
+- P1: "Disconnect during inventory management is not specified. If the server connection drops while the player has the inventory open, the UI state is undefined — does it close the inventory? Show an error? Return to main menu?"
+- P2: "No modal priority system is defined. If a system notification, a party invite, and a trade request arrive simultaneously, the stacking behavior is unspecified."
+
+---
+
+## Pass 7: Platform Shell Compliance
+
+### What to Check
+
+System UI respects platform conventions for PlayStation (PS button returns to system menu), Xbox (Guide button returns to dashboard), and Nintendo Switch (Home button returns to system). Notification handling is specified — game does not block or interfere with system notifications. Console certification UI requirements (save icon display, mandatory legal notices, suspend/resume behavior) are addressed.
+
+### Why This Matters
+
+Platform shell compliance is a hard certification requirement. A game that does not properly handle the PS button, fails to display the mandated save icon, or interferes with system notifications will fail certification and cannot ship on that platform. These requirements are non-negotiable and documented in each platform's Technical Requirements Checklist (TRC for PlayStation, Xbox Requirements for Xbox, Lotcheck for Nintendo). Failing certification delays launch by weeks to months.
+
+### How to Check
+
+1. Verify system button handling: PS button, Xbox Guide button, Switch Home button all behave per platform spec
+2. Check suspend/resume: game correctly saves state and resumes when the player leaves and returns
+3. Verify save icon display: a save icon is displayed whenever the game writes to persistent storage (platform requirement)
+4. Check mandatory legal notices: EULA, privacy policy, and age rating screens appear per platform requirements
+5. Verify notification handling: system notifications (friend online, message received, download complete) display correctly over the game UI
+6. Check for account switching: what happens if the user switches accounts mid-game? (Platform-specific requirements)
+7. Verify that game UI does not render in platform-reserved screen areas (safe zone compliance)
+
+### What a Finding Looks Like
+
+- P0: "No suspend/resume handling is specified. On PS5, pressing the PS button and returning to the game may result in a broken state. Suspend/resume is a mandatory TRC requirement."
+- P0: "Save icon display is not specified. PlayStation TRC requires a visible save indicator whenever writing to storage. Failure is an automatic certification rejection."
+- P1: "System notification handling is not addressed. If a friend-request notification appears during a full-screen cinematic, the behavior is undefined. Specify whether the game pauses, overlays, or queues."
+- P2: "Safe zone compliance is not documented. UI elements placed within 5% of screen edges may be clipped on some displays. Platform safe zone guidelines require all critical UI within the 90% safe area."
+
+---
+
+## Finding Template
+
+Use this template for all game UI review findings:
+
+```markdown
+### Finding: [Short description of the issue]
+
+**Pass:** [Pass number] — [Pass name]
+**Priority:** P0 | P1 | P2 | P3
+**Location:** [UI spec section and screen/element]
+
+**Issue:** [Specific description of what is wrong, with references to the UI spec text.
+Avoid subjective language — state the structural problem.]
+
+**Evidence:** [Quote or reference the specific UI spec content that demonstrates the issue.
+For navigation findings, show the broken path. For accessibility findings, show the
+non-compliant element. For state machine findings, show the missing transition.]
+
+**Impact:** [What goes wrong during implementation or certification if this is not fixed.
+Be specific: "controller users cannot reach this screen" or "certification will fail on
+PlayStation" or "players will softlock on this screen."]
+
+**Recommendation:** [Concrete action to resolve the finding. Not "improve navigation" but
+"add D-pad focus support to the server browser list — each row is a focusable element,
+D-pad up/down moves between rows, A/X button selects."]
+
+**Trace:** [Which downstream artifacts, screens, or certification requirements are affected]
+```
+
+### Example Finding
+
+```markdown
+### Finding: Server browser has no controller navigation — console certification blocker
+
+**Pass:** 3 — Controller Accessibility
+**Priority:** P0
+**Location:** UI Spec Section 5.2 "Server Browser"
+
+**Issue:** The server browser screen uses a mouse-driven scrollable list with
+hover-to-select interaction. No D-pad navigation, focus indicators, or
+controller bindings are specified. Controller users cannot select a server,
+making the multiplayer flow inaccessible on gamepad.
+
+**Evidence:** UI Spec Section 5.2: "Server list displays available servers in a
+scrollable table. Player clicks a row to select, double-clicks to join."
+No controller input is mentioned. No focus indicator design is shown.
+
+**Impact:** Console certification will fail — every screen must be fully navigable
+with a gamepad. PC controller users cannot access multiplayer. This blocks the
+entire online flow for controller input.
+
+**Recommendation:** Add D-pad navigation to the server list:
+  - Each server row is a focusable element
+  - D-pad up/down moves focus between rows
+  - A button (Xbox) / X button (PS) selects the focused row
+  - X button (Xbox) / Square button (PS) opens server details
+  - Focus indicator: 3px highlight border with team accent color
+  - L1/R1 switch between server list tabs (All, Favorites, Recent)
+
+**Trace:** UI Spec 5.2 → blocks multiplayer-flow.md controller path,
+console-certification.md TRC 3.12 (controller navigation), QA test plan
+controller coverage
+```

package/content/knowledge/review/review-netcode.md

@@ -0,0 +1,280 @@
+---
+name: review-netcode
+description: Failure modes and review passes specific to netcode design — latency analysis, bandwidth ceilings, cheat surfaces, and disconnect handling
+topics: [game-dev, review, networking, latency, bandwidth, anticheat]
+---
+
+# Review: Netcode Design
+
+Netcode design documents must specify how the game handles the physical reality of network latency, limited bandwidth, and untrusted clients. A netcode design that works under ideal conditions (20ms ping, no packet loss, no cheaters) is not a design — it is a fantasy. This review uses 7 passes targeting the specific ways netcode designs fail under real-world conditions.
+
+Follows the review process defined in `review-methodology.md`.
+
+## Summary
+
+- **Pass 1 — Worst-Case Latency Analysis**: The design handles 200ms+ latency gracefully; player-facing impact at each latency tier is documented; no mechanic requires sub-frame synchronization over the network.
+- **Pass 2 — Bandwidth Ceiling Calculation**: Per-player and per-match bandwidth budgets are calculated; entity count × update rate × payload size does not exceed typical residential upstream limits.
+- **Pass 3 — Cheat Surface Audit**: Every piece of data sent to the client is evaluated for cheat potential; server-authoritative validation exists for every game-state-changing action.
+- **Pass 4 — Determinism Verification**: For lockstep and rollback architectures, determinism requirements are identified and verified; floating-point divergence, platform differences, and desync detection are addressed. (NOT applicable to pure client-server designs.)
+- **Pass 5 — Disconnect/Reconnect Handling**: Graceful handling for every disconnect scenario: mid-match, mid-transaction, mid-save; reconnection restores state without exploits or data loss.
+- **Pass 6 — Matchmaking Fairness Assessment**: Matchmaking considers latency, skill, party size, and region; no systematic advantage for players in specific network conditions.
+- **Pass 7 — Bandwidth Spike Resilience**: The design handles transient bandwidth spikes (ability usage, explosions, mass entity spawns) without degrading below playable quality.
+
+## Deep Guidance
+
+---
+
+## Pass 1: Worst-Case Latency Analysis
+
+### What to Check
+
+The netcode design documents player experience at every latency tier: ideal (< 50ms), acceptable (50-100ms), degraded (100-200ms), and poor (200-500ms). Every gameplay mechanic is evaluated for its latency tolerance. No mechanic assumes LAN-quality latency.
+
+### Why This Matters
+
+Most netcode designs are tested and tuned on local networks or same-region servers. In production, 10-20% of players experience 100ms+ latency and 5% experience 200ms+. A mechanic that feels great at 30ms but breaks at 150ms will generate complaints from millions of players. The design must define what "graceful degradation" means for each latency tier — not "it still works" but specifically what the player experiences.
+
+### How to Check
+
+1. List every gameplay mechanic that involves networked state: movement, combat, trading, inventory, chat, matchmaking
+2. For each mechanic, evaluate at four latency tiers: < 50ms, 50-100ms, 100-200ms, 200ms+
+3. Identify mechanics with strict timing requirements: fighting game frame data, rhythm game hit windows, reaction-based combat
+4. Verify that client-side prediction is specified for latency-sensitive mechanics (movement, shooting)
+5. Check for latency compensation on hit detection: is the system using client-side hit detection with server validation, server-side hit detection with lag compensation, or something else?
+6. Verify that the design specifies what happens at extreme latency (> 500ms): timeout? Disconnect? Graceful degradation?
+7. Check for latency hiding techniques: animations that mask delay, local prediction for responsiveness, rollback for correction
+
+```markdown
+## Latency Impact Matrix
+
+| Mechanic            | < 50ms        | 50-100ms      | 100-200ms      | 200ms+         |
+|---------------------|---------------|---------------|----------------|----------------|
+| Player movement     | [experience]  | [experience]  | [experience]   | [experience]   |
+| Combat hit reg      | [experience]  | [experience]  | [experience]   | [experience]   |
+| Ability activation  | [experience]  | [experience]  | [experience]   | [experience]   |
+| Item pickup         | [experience]  | [experience]  | [experience]   | [experience]   |
+| Chat/emotes         | [experience]  | [experience]  | [experience]   | [experience]   |
+| Trading             | [experience]  | [experience]  | [experience]   | [experience]   |
+
+Acceptable threshold: [Define which cells are acceptable, degraded, or unplayable]
+```
+
+### What a Finding Looks Like
+
+- P0: "Combat uses server-authoritative hit detection with no lag compensation. At 150ms, players must lead targets by 300ms (round trip) — making fast-paced combat unplayable for 15% of the player base."
+- P0: "The design specifies 16ms tick rate for combat resolution but does not address how clients at 100ms+ latency interact with this tick rate. Inputs will consistently arrive 6+ ticks late."
+- P1: "Movement prediction exists but no reconciliation strategy is specified. When the server corrects a misprediction, what does the player see? Rubber-banding? Snap? Smooth interpolation?"
+- P2: "Latency tolerance for the trading system is not specified. Trades at 200ms latency may show stale inventory or allow double-spend if not handled."
+
+---
+
+## Pass 2: Bandwidth Ceiling Calculation
+
+### What to Check
+
+Total bandwidth consumption is calculated for worst-case scenarios: maximum players, maximum entities, maximum action density. Per-player upstream and downstream bandwidth stay within residential internet limits. Bandwidth is budgeted across entity types, not just estimated in aggregate.
+
+### Why This Matters
+
+Bandwidth overruns cause packet loss, which causes desync, rubber-banding, and hit registration failures. Unlike latency (which is physics), bandwidth is design-controllable — the team chooses how much data to send. A 64-player battle royale where each player sends full state at 60Hz consumes more bandwidth than most residential connections provide. The design must calculate this before implementation, not discover it in the first 64-player playtest.
+
+### How to Check
+
+1. Calculate per-entity update size: how many bytes does one entity state update require? (Position: 12 bytes, rotation: 4-16 bytes, velocity: 12 bytes, state flags: varies)
+2. Calculate entity count × update rate = updates per second
+3. Calculate total downstream: (entity count × update size × update rate) + overhead (packet headers, reliability layer)
+4. Verify downstream stays under 1 Mbps for residential players (conservative) or document the minimum connection requirement
+5. Calculate upstream: (local entity updates × update size × update rate) + input data
+6. Verify upstream stays under 256 Kbps (many residential connections have asymmetric upload)
+7. Check for bandwidth scaling: does bandwidth grow linearly with player count? Are there diminishing returns from interest management?
+
+### What a Finding Looks Like
+
+- P0: "64-player match with 30Hz updates at 64 bytes per entity = 64 × 64 × 30 = 122,880 bytes/sec (983 Kbps) downstream for entities alone. With packet overhead and game events, this exceeds 1.5 Mbps — above many residential connections."
+- P1: "Bandwidth calculation exists but does not account for game events (ability effects, explosions, chat). Events can spike bandwidth 3-5x above entity-update baseline."
+- P1: "No interest management (relevancy filtering) is specified. Every player receives updates for all 64 players regardless of distance, even if most are not visible."
+- P2: "Upstream bandwidth is not calculated. If the game sends input + local entity state at 60Hz, upstream may exceed residential upload limits."
+
+---
+
+## Pass 3: Cheat Surface Audit
+
+### What to Check
+
+Every piece of data sent to the client is evaluated for cheat potential. The server validates every game-state-changing action. The client is treated as untrusted — it is a rendering terminal, not an authority. Anti-cheat measures are proportional to the competitive stakes.
+
+### Why This Matters
+
+Any data the client possesses can be read by a cheater. Any action the client is authoritative on can be forged by a cheater. In competitive games, cheating drives away legitimate players — a single aimbotter in a lobby causes 63 other players to have a bad experience. Anti-cheat is not a post-launch bolt-on; the netcode architecture must be designed with cheat resistance as a core constraint.
+
+### How to Check
+
+1. List every data type sent to the client: player positions, health values, inventory contents, map data, enemy positions, loot tables
+2. For each, evaluate: what can a cheater do with this data? (Wallhacks from enemy positions, ESP from health values, loot sniping from loot table data)
+3. Verify server authority: for every game-state-changing action (damage, movement, item acquisition, currency change), does the server validate the action or trust the client?
+4. Check for speed hacks: does the server validate movement speed, or does it trust client-reported position?
+5. Check for teleport prevention: does the server verify position continuity (no instant jumps)?
+6. Verify that hit detection is server-validated: even if the client reports a hit, does the server verify line-of-sight, range, cooldowns, and ammunition?
+7. Check for economy cheats: can the client modify currency, item counts, or transaction outcomes?
+
+```markdown
+## Cheat Surface Audit Template
+
+| Data Sent to Client     | Cheat Vector          | Impact    | Mitigation         |
+|-------------------------|-----------------------|-----------|--------------------|
+| All player positions    | Wallhack/ESP          | High      | [Fog of war / culling] |
+| Player health values    | Health ESP            | Medium    | [Send only for visible] |
+| Loot table / drop data  | Loot prediction       | Medium    | [Server-side only]  |
+| Full map data           | Map reveal            | Low-High  | [Stream on demand]  |
+| Hit registration        | Aimbot + client auth  | Critical  | [Server validation] |
+| Movement authority      | Speed/teleport hack   | Critical  | [Server validation] |
+| Inventory/currency      | Item duplication      | Critical  | [Server-authoritative] |
+
+Unmitigated critical vectors: [COUNT — must be 0]
+```
+
+### What a Finding Looks Like
+
+- P0: "Client is authoritative for hit detection. A cheater can send 'I hit every player for maximum damage every frame' and the server will accept it."
+- P0: "All player positions are sent to every client regardless of visibility. This enables trivial wallhacks — the cheat client simply renders hidden players."
+- P1: "Server validates movement speed but not acceleration. A speed hack that gradually increases speed from 100% to 200% over 10 seconds would bypass the speed check."
+- P2: "Inventory changes are server-authoritative but the client caches inventory locally. A cheater could display spoofed items to other players in social contexts."
+
+---
+
+## Pass 4: Determinism Verification
+
+### What to Check
+
+**CONDITIONAL: This pass applies only to lockstep or rollback netcode architectures.** For client-server authority models, skip this pass entirely.
+
+For deterministic architectures, every operation that affects game state must produce identical results on every machine given the same inputs. Floating-point operations, random number generation, physics simulation, and platform-specific behavior are all sources of non-determinism that cause desync.
+
+### Why This Matters
+
+Lockstep and rollback architectures rely on all clients simulating identically. A single non-deterministic operation causes the simulations to diverge — desync — which manifests as teleporting players, phantom hits, and corrupted game state. Desync is catastrophic because it is cumulative: once simulations diverge, they never re-converge without correction. Determinism is an all-or-nothing requirement.
+
+### How to Check
+
+1. Verify that the architecture is actually lockstep or rollback — if it is client-server with authoritative server, skip this pass
+2. Check floating-point handling: are fixed-point math libraries used? If IEEE 754 floating-point is used, are platform-specific differences (x86 vs. ARM) addressed?
+3. Verify RNG determinism: all random number generation uses a shared seed with a deterministic algorithm (no system RNG)
+4. Check physics engine determinism: is the physics engine guaranteed deterministic? (Most are NOT across platforms)
+5. Verify iteration order: hash maps, sets, and any unordered data structures must use deterministic iteration
+6. Check that desync detection exists: periodic state hash comparison between clients to detect divergence early
+7. Verify desync recovery: when detected, how is desync resolved? Full state resync? Rollback to last known good state?
+
+### What a Finding Looks Like
+
+- P0: "Rollback architecture uses Unity's built-in physics engine, which is not deterministic across platforms. PC and console clients will desync within minutes."
+- P0: "Floating-point arithmetic is used for all game state calculations with no fixed-point alternative. x86 and ARM produce different results for the same operations."
+- P1: "RNG uses a shared seed but the document does not specify which PRNG algorithm. Different implementations of 'random' produce different sequences."
+- P2: "Desync detection is mentioned but no detection mechanism is specified. Without periodic state hashing, desync goes undetected until it becomes visible to players."
+
+---
+
+## Pass 5: Disconnect/Reconnect Handling
+
+### What to Check
+
+Every disconnect scenario is handled: mid-match, mid-transaction, mid-save, mid-trade. Reconnection restores the player to their correct state without data loss, exploits, or unfair advantage. Timeout thresholds and abandon penalties are specified.
+
+### Why This Matters
+
+Disconnects are not edge cases — they are guaranteed. On mobile, network transitions (Wi-Fi to cellular) cause momentary disconnects. On any platform, ISP issues, router restarts, and game crashes cause unexpected disconnects. A game that loses player progress, duplicates items, or awards undeserved wins/losses on disconnect will hemorrhage players. Disconnect handling is a core system, not an afterthought.
+
+### How to Check
+
+1. For each game mode, specify what happens when a player disconnects: is their character removed instantly? After a timeout? Does an AI take over?
+2. Check for mid-transaction disconnect: if a player disconnects while buying/selling/trading, what is the transaction state? Is it rolled back? Completed? Left in limbo?
+3. Verify reconnection flow: can a player rejoin an in-progress match? Within what time window? Is their state preserved?
+4. Check for exploit potential: can a player disconnect to avoid a loss? To duplicate items? To undo a bad trade?
+5. Verify timeout thresholds: how long does the server wait before treating a disconnect as an abandon?
+6. Check for abandon penalties: are players who intentionally disconnect punished? How are intentional disconnects distinguished from network issues?
+7. Verify save state consistency: if the player disconnects between a game state change and a save, which state wins?
+
+### What a Finding Looks Like
+
+- P0: "No reconnection mechanism exists. A player who disconnects from a 45-minute match must start over. This is unacceptable for competitive modes."
+- P0: "Mid-trade disconnect handling is not specified. If player A sends an item and disconnects before receiving player B's item, the trade state is undefined — potential item duplication or loss."
+- P1: "Disconnect during a ranked match counts as an automatic loss. No grace period exists for reconnection. A 2-second ISP hiccup causes a full loss of ranked points."
+- P2: "AI takeover is specified for disconnected players but the AI difficulty level is not defined. An overpowered AI substitute could be more effective than the disconnected player, creating a perverse incentive to disconnect."
+
+---
+
+## Pass 6: Matchmaking Fairness Assessment
+
+### What to Check
+
+Matchmaking considers latency (players are matched within acceptable ping ranges), skill (players face opponents of similar ability), party size (solo players are not matched against coordinated groups), and region (geographic proximity for latency). No systematic advantage exists for players in specific network conditions or regions.
+
+### Why This Matters
+
+Unfair matchmaking drives player churn faster than any other factor. A new player matched against a veteran quits in frustration. A player with 30ms ping matched against a player with 200ms ping has a structural advantage in any real-time combat. A solo player matched against a coordinated 4-stack loses due to communication, not skill. Matchmaking fairness is the foundation of competitive game health.
+
+### How to Check
+
+1. Verify that ping-based matchmaking exists: players within the same match should have comparable latency (< 50ms difference ideal, < 100ms acceptable)
+2. Check for skill-based matchmaking (SBMM): is there a rating system? How does it handle new players (placement matches)? How quickly does it converge?
+3. Verify party-size matching: solo players vs. solo players, groups vs. groups — or at minimum, compensation for size imbalance
+4. Check for region selection: can players choose their region? Is the choice locked or advisory?
+5. Verify that matchmaking queue times are bounded: what happens when the pool is too small for fair matches? (Wider skill range? Cross-region? Bot backfill?)
+6. Check for smurf prevention: can experienced players create new accounts to stomp new players?
+7. Verify that matchmaking data is used for balance analysis: is win rate by skill bracket tracked?
+
+### What a Finding Looks Like
+
+- P0: "No ping-based matchmaking exists. A player in Tokyo can be matched against a player in New York, producing 200ms+ latency in a competitive shooter."
+- P1: "SBMM exists but no placement system is defined. New players start at median rating and are immediately matched against average players, producing 30-50 matches of stomps before the rating converges."
+- P1: "Solo players and 5-stacks are in the same matchmaking pool with no compensation. Coordinated groups have a 15-20% win rate advantage over equivalent-skill solo players."
+- P2: "Queue time bounds are not specified. In low-population regions, players may wait indefinitely or receive wildly unfair matches."
+
+---
+
+## Pass 7: Bandwidth Spike Resilience
+
+### What to Check
+
+The design handles transient bandwidth spikes caused by gameplay events: ability usage, explosions, mass entity spawns, zone transitions, and player clustering. Spike mitigation strategies (priority queuing, delta compression, update rate reduction) are specified.
+
+### Why This Matters
+
+Steady-state bandwidth may be well within limits, but a single moment — 10 players using abilities simultaneously in a team fight — can spike bandwidth 5-10x above baseline. Without spike mitigation, this causes packet loss during the most important gameplay moments, precisely when network quality matters most. Players remember "the game lagged during the final team fight" more than any other quality issue.
+
+### How to Check
+
+1. Identify spike scenarios: large battles, ability clusters, zone transitions, mass spawns, world events
+2. For each scenario, calculate peak bandwidth: (entities changed × update size) for that frame/tick
+3. Verify that peak bandwidth does not exceed steady-state by more than 3x without mitigation
+4. Check for priority queuing: are critical updates (player position, health) prioritized over cosmetic updates (emotes, particle effects)?
+5. Verify delta compression: are only changed fields sent, or full entity state on every update?
+6. Check for adaptive update rates: does the server reduce update frequency under load? Which entities are downgraded first?
+7. Verify that spike mitigation degrades gracefully: cosmetic quality drops before gameplay accuracy
+
+### What a Finding Looks Like
+
+- P0: "10v10 team fight with all abilities active produces 15x baseline bandwidth. No spike mitigation is specified. This will cause packet loss and desync during the most critical gameplay moments."
+- P1: "Delta compression is specified for entity position but not for game events. A single explosion event sends full effect data (particle count, damage list, audio trigger) to all 64 players simultaneously."
+- P2: "Adaptive update rate is mentioned but priority order is not defined. Without explicit priority (gameplay > VFX > audio > cosmetic), the system may downgrade gameplay updates to preserve cosmetic fidelity."
+
+---
+
+## Common Review Anti-Patterns
+
+### 1. LAN-Optimized Netcode
+
+The netcode design was tested and tuned on a local network. All latency budgets assume < 20ms. Bandwidth calculations assume gigabit LAN speeds. The design feels great in the studio and breaks for every player outside the same city as the data center.
+
+**How to spot it:** Latency analysis mentions only one tier (e.g., "at 20ms latency"). No latency degradation table exists. Bandwidth calculations do not reference residential internet speeds or upstream limits.
+
+### 2. "Anti-Cheat Will Handle It"
+
+The netcode design defers all cheat prevention to a third-party anti-cheat solution (EasyAntiCheat, BattlEye, Vanguard). These tools detect cheat software but cannot fix architectural flaws. If the client is authoritative for hit detection, no anti-cheat tool can prevent a modified client from reporting false hits. Architectural cheat resistance and software-based anti-cheat are complementary, not substitutes.
+
+**How to spot it:** The cheat prevention section names an anti-cheat product but does not analyze the server-authority model. No discussion of what data the client receives or what actions the client is authoritative for.
+
+### 3. Determinism Assumed, Not Verified
+
+For lockstep/rollback designs, the document states "the simulation is deterministic" without analyzing sources of non-determinism. Floating-point operations, hash map iteration order, physics engine behavior, and platform-specific math libraries are all sources of non-determinism that must be explicitly addressed.
+
+**How to spot it:** The word "deterministic" appears without any discussion of fixed-point math, PRNG seeding, physics engine guarantees, or cross-platform verification.