iron-requiem/docs/PREMORTEM.md

PREMORTEM.md — Iron Requiem Architecture Risk Assessment

This document identifies potential failure modes and defines the mitigation strategies before implementation begins.

---

1. Does something already exist that does this?

Analysis: There are many "tank" games and many "bullet hells," but the specific marriage of heavy tank physics (inertia) and bullet hell patterns is rare. Most tank games focus on tactical combat or arcade movement.

• Overlap: Bullet patterns are a solved problem in the genre (Touhou, Ikaruga). Tank physics (acceleration/friction) are common in sims.
• Novelty: The "Tank-as-Character" focal point—combining a limited periscope view, crew morale, and heavy machinery feel—is the unique hook.

2. Where is the overlap? What is novel vs. reinventing?

• Reinventing: Basic bullet pooling and collision (handled by Phaser's Arcade Physics).
• Novel: The interaction between the Sighting Mask and Unbuttoning states. This creates a physical tension that doesn't exist in traditional bullet hells, where the pilot has a clear view of the screen.

3. What is the weakest link?

Identified Risk: The "Crew Morale" fun factor.

• Risk: If the morale system feels like a chore or an invisible stat that doesn't impact the feeling of the game, it becomes bloat.
• Mitigation: Move from a "debuff" system to a "buff" system. Morale shouldn't punish the player (no RNG panic) but reward them with higher performance (reload speed, early warnings), making survival feel like earned mastery.

4. What happens when the periscope mask + 200 projectiles drops below 60fps?

Risk: Canvas-layer masks are computationally expensive in Phaser 3.

• Failure Mode: Rendering a full-screen mask with a rotating hole while managing hundreds of active physics bodies can lead to CPU bottlenecks.
• Mitigation:
  • Use a simplified Graphics mask instead of complex geometry.
  • Implementation of aggressive Object Pooling via Phaser.Physics.Arcade.Group.
  • Fallback to Phaser.WEBGL if CANVAS performance degrades, using roundPixels: true to keep the pixel look.

5. What breaks at scale?

Risk: Large zones and ghost crew data in IndexedDB.

• Failure Mode: Large world maps can lead to memory leaks if not properly chunked. Excessive "ghost crew" data (hundreds of failed runs) could bloat IndexedDB storage.
• Mitigation:
  • Implement a ZoneManager that clears previous scene assets upon entering a new zone.
  • Set a hard cap on "Ghost Crew" entries (e.g., top 50 historical runs) to keep storage lean.

6. What coordination fails silently?

Risk: CI/CD deployment overwriting the live game mid-session.

• Failure Mode: A git push triggers a Docker deployment that restarts the Traefik-routed container, cutting off a player's current session.
• Mitigation: Since the game is static assets, we can deploy to a versioned folder (e.g., /v1.0.1/) and update the root redirect. If a session is active, the user is prompted to "Refresh for Update" rather than having the page crash.

7. Where is complexity hand-waved?

Challenge: "The heat system handles this" — how?

• Resolution: Heat is a quantified variable (0-100).
  • Inputs: Speed (v^2) and Combat Intensity (shells fired/sec).
  • Outputs: At >80%, the tank becomes a "Thermal Beacon," attracting more aggressive enemy patterns. At <10% in Tundra zones, the engine has a probability to stall.
  • Numbers: Standard heat gain: 0.1%/s at idle, 2.0%/s at max speed. Cooling: 0.5%/s when stationary.