MR Ventures — Production Readiness Final Report

Consolidated analysis from two independent audit sessions, with gap analysis, unified roadmap, and detailed PRDs for every pending work item

Generated 2026-05-14 · Branch analysys_roadmap_for_completion · Godot 4.6.1-stable · .NET 9.0.203 · 622/622 C# tests passing

1. Executive Summary

~75%

Core Game Mechanics Complete

~35%

Production Shell Ready

Ship-Critical Work Items

Source Audits Consolidated

Bottom line: The core gameplay loop (generators, upgrades, missions, chests, staff, executive actions, market, rank progression) is functionally solid with 622 passing C# tests and clean GDScript validation. However, the game lacks the production shell (splash, loading, FTUE, tutorial, progressive unlocks, settings, analytics, monetization) required for a shippable product. Both independent audits converge on the same core gaps.

What Works Well

8-generator economy with formula-driven stats (GeneratorStatsCalculator)
Rank progression (30 ranks across 5 wealth chapters)
48 staff members with tier system, pity guarantees, and chest drops
696 executive action/deal resources across 8 generator themes
Mission system (dynamic + scenario) with chest rewards
Market with ventures + research sub-tabs
HQ upgrades system with gem economy
Store UI with offer catalog and rank gating
Offline earnings calculation
Localization (EN/ES) with content localization pipeline
DomainEventBus + SignalHub communication architecture
Save/load system with version migration
Strong test coverage (622 C#, 21 bridge, GDScript passing)

What Is Missing for Shipping

No splash/loading screen — app launches directly into gameplay
No first-time user experience (welcome, tutorial, guided first session)
No progressive feature unlocks — all tabs visible at once
No tab notification badges or next-best-action indicators
No settings screen (audio, locale, tutorial replay, support)
No production analytics or telemetry
No IAP/ad provider integration (UnavailableStorePurchaseProvider active)
No cloud save system
No corrupted-save recovery UI
No celebration animations beyond basic popups
No audio/music/haptics system
CI GDScript and export gates are advisory, not required

2. Source Report Comparison & Gap Analysis

Two independent audits were conducted using the same codebase snapshot. This section identifies where they agree, where they diverge, and what each uniquely discovered.

Areas of Full Agreement

Area	Shared Finding	Severity
Splash/Loading	Completely missing — no branded launch experience	P1
Welcome/FTUE	No first-time user flow; players see full game immediately	P1
Progressive Unlocks	All tabs (HQ, Execs, Market, Staff, Store) visible at start; should be gated	P1
Tutorial System	TutorialManager exists but only 2 tutorial resources wired; most first-session moments missing	P1
Tab Indicators	Only EA/deal completion dots exist; missing mission, staff, store, upgrade, and next-best-action indicators	P2
Settings Screen	No user-facing settings (audio, locale, tutorial replay, support, credits)	P1
Analytics	DomainEventBus exists for testing; no production telemetry sink	P1
Monetization/IAP	Store UI and offer catalog exist; purchase provider is intentionally unavailable	P1
Audio/Music	No sound system implemented	P2
Competitive Pattern Violations	MR Ventures violates 6 of 8 common idle-game patterns for first-session UX	P1

Divergent Findings & Unique Contributions

Finding	Source	Details	Severity
19 case-mismatch file paths	Audit 1	Identified specific file paths with case mismatches that will break on Linux/Android (case-sensitive filesystems)	P0
First-time user state machine (10 states)	Audit 2	Comprehensive state machine covering fresh install, returning, corrupted, cloud conflict, no-network, app update, new scenario, progress reset	P1
Save system hardening	Audit 2	Corrupted-save quarantine UI, cloud adapter interface, conflict-resolution flow, migration verification	P1
Analytics event schema	Audit 2	Detailed 19-event minimum launch schema with payload definitions	P1
CI gate promotion	Audit 2	GDScript, publish settings, resource validation, smoke test, export gates should be promoted from advisory to required; Godot version mismatch (CI uses 4.5.1, project declares 4.6)	P1
Market card state model expansion	Audit 2	Cards should show slot-capped, cash-short, buyable, newly unlocked, and owned states	P2
Gem speedup implementation	Audit 1	Use gems to speed up EA timers and generator cycles; critical for gem sink economy	P2
Celebration animations	Audit 1	Rank-up, evolution, milestone, generator acquisition celebration sequences	P2
Financial education popups	Audit 1	Contextual educational moments at key first-time actions	P2
Finley mascot guide system	Audit 1	Speech bubble guide character for tutorials and tips	P3
A/B testing & remote config	Audit 1	Framework for testing FTUE variants, economy tuning, and monetization placement	P3
Device matrix & export verification	Audit 2	Verified export stripping of test autoloads, safe-area layout, device compatibility matrix	P1
Scenario resource validation CLI	Audit 2	Automated validation of all scenario data resources across environments	P2
Privacy/legal compliance	Audit 2	Privacy consent flow, COPPA/GDPR considerations for analytics and ads	P1
Accessibility improvements	Audit 1	Screen reader support, color-blind modes, text scaling	P3

3. Current State Snapshot

Metric	Value
C# Files	253
GDScript Files	101
Scenes (.tscn)	58
C# Unit Tests	622 passed, 0 failed
Bridge Tests	21 passed
GDScript Validation	Passed
Publish Settings	All checks passed
Build Warnings	495 (C# build)
Generators (prod)	8 generators, 48 chapter resources
EAs/Deals (prod)	696 resources
Staff (prod)	48 members, 56 staff-slot resources
Localization	EN + ES, two CSV files
Godot Version	4.6.1-stable
.NET Version	9.0.203

System Readiness Matrix

System	Status	Notes
Generator Economy	DONE	Formula-driven, clamp systems, cost snapshotting
Rank Progression	DONE	30 ranks, 5 chapters, RP-driven
Missions	DONE	Dynamic + scenario, chest rewards
Chests & Drops	DONE	Tier gating, pity system, first-rare/epic guarantees
Staff System	DONE	48 staff, assignment, XP, milestones
Executive Actions	DONE	Timer, rewards, RP, cost snapshotting
Market	DONE	Ventures + research, acquisition flow
HQ Upgrades	DONE	Gem-based upgrades with rank gating
Store/Offers	PARTIAL	UI + catalog exist; no purchase provider
Offline Earnings	DONE	30% rate, 12h cap, popup exists
Save/Load	PARTIAL	Works for local; no cloud, no corruption recovery UI
Localization	DONE	EN/ES with content pipeline
Splash/Loading	MISSING	No splash, loading, or welcome screen
FTUE/Tutorial	MISSING	TutorialManager exists; only 2 resources wired
Progressive Unlocks	MISSING	All tabs visible at start
Tab Indicators	PARTIAL	Only EA/deal completion dots
Settings	MISSING	No settings screen at all
Analytics	MISSING	Domain events for testing; no prod sink
IAP/Ads	MISSING	Provider interface exists; no platform integration
Audio/Music	MISSING	No implementation
Cloud Save	MISSING	No cloud provider
Celebrations	PARTIAL	Basic popups exist; no animated sequences

4. Unified Roadmap

This roadmap merges findings from both audit sources into a single prioritized list. Items are ordered by shipping criticality, not effort.

P0 — Blockers (Before Any Playable Release)

WI-001: Fix case-mismatch file paths

19 file path case mismatches that will break on Linux/Android case-sensitive filesystems. App will crash or show missing textures on target platforms.

XS Audit 1

WI-002: Required clean-launch smoke test

Automate a test that verifies the game can reach first playable gameplay from a fresh state without runtime errors.

S Audit 2

P1 — Ship-Critical (Before Production Launch)

WI-003: Splash & loading screen

Branded splash scene, loading progress bar with tips, failure fallback. Prevents blank app launch.

S Both PRD →

WI-004: Welcome / FTUE flow

Welcome screen introducing the game fantasy, scenario context, and guided first session from first tap to first mission complete.

M Both PRD →

WI-005: Progressive feature unlocks

Centralized FeatureVisibilityService controlling tab/section visibility based on rank, state flags, and scenario progress.

M Both PRD →

WI-006: Tutorial system activation

Wire TutorialManager to 12+ first-session game events. Create tutorial resources for first generator, upgrade, mission, chest, EA, deal, staff, rank-up, market, staff assignment.

M Both PRD →

WI-007: First-session mission sequence

Ensure first missions are completable within target pacing (2-4 minutes), rewarding, and clearly connected to the progression loop.

S Audit 1

WI-008: Settings screen

Gear icon accessible from all states. Audio toggle, locale selector, tutorial replay, support link, credits, version info, progress reset.

S Both PRD →

WI-009: Save system hardening

Corrupted-save quarantine UI, versioned migration verification, save integrity checks, recovery/reset dialog.

L Audit 2 PRD →

WI-010: Analytics foundation

AnalyticsService adapter with minimum 19-event launch schema. First-launch, tutorial, economy, monetization, retention, and error events.

M Both PRD →

WI-011: IAP integration / purchase provider

Wire platform purchase/ad providers behind existing interfaces. Sandbox testing for purchase, restore, failure, and ad availability flows.

XL Both PRD →

WI-012: CI gate promotion

Promote GDScript, publish settings, resource validation, smoke launch, and export build from advisory to required CI checks. Fix Godot version mismatch (CI 4.5.1 vs project 4.6).

M Audit 2 PRD →

WI-013: App icon, export configuration, and mobile readiness

Production export dry-run, test autoload stripping, safe-area layout verification, device matrix QA.

L Both PRD →

WI-014: Privacy and legal compliance

Privacy consent flow for analytics and ads. COPPA/GDPR/CCPA considerations. Privacy policy URL.

M Audit 2

P2 — Important (Before Retention-Ready Launch)

WI-015: Tab notification badges

Priority-ranked badge system for all 5 tabs plus generator cards. Triggers include completed EA, mission chest, staff assignable, affordable upgrade, store offer.

M Both PRD →

WI-016: Next-best-action indicators

Global arbitration service that determines the single most impactful action for idle players. Shows contextual indicator after 10+ seconds idle.

M Audit 1

WI-017: Market card state model expansion

Market venture cards show slot-capped, cash-short, buyable, newly unlocked, and owned states with distinct visual treatment.

M Audit 2 PRD →

WI-018: Gem speedup implementation

Spend gems to skip/accelerate EA timers and generator production cycles. Critical gem sink for F2P economy balance.

M Audit 1 PRD →

WI-019: Celebration animations

Animated sequences for rank-up, generator evolution, milestone achievements, and generator acquisition.

M Audit 1 PRD →

WI-020: Sound & music system

Background music, SFX for actions/rewards, haptic feedback on key moments. Mute setting respected from first frame.

L Audit 1

WI-021: Financial education popups

Contextual educational moments at first cash, first upgrade, first deal, first staff, first offline return.

M Both PRD →

WI-022: Scenario resource validation CLI

Automated validation of all scenario data resources across dev/prod environments. Reports missing, invalid, or orphaned resources.

M Audit 2

WI-023: Progression probes

Reports for first 5-minute pacing and G3-G8 unlock timing to verify economy bands in live play.

S Audit 2

WI-024: Staff onboarding polish

First staff drop, first assignment, and empty staff-tab states polished for clarity.

S Both

WI-025: Offline earnings rate explanation

Show the offline rate (30%), earning calculation, and time cap (12h) in the offline popup.

XS Audit 1

WI-026: Empty state guidance

When tabs have no actionable content, show guidance text instead of empty space (e.g., Staff tab with no staff).

S Audit 1

P3 — Post-Launch Polish

WI-027: Cloud save

Cloud save adapter, conflict resolution UI, cross-device sync.

L Both PRD →

WI-028: Finley mascot / guide character

Animated speech bubble guide for tutorials, tips, and celebrations. Market Research portrait already exists.

L Audit 1

WI-029: A/B testing framework

Test FTUE variants, economy tuning, monetization placement, and feature rollout.

M Audit 1

WI-030: Remote config / LiveOps

Server-side economy tuning, feature flags, event scheduling.

L Both

WI-031: Rewarded ad hooks

Ad-double offline earnings, ad-boost production, ad-skip EA timer. Frequency caps.

M Audit 1

WI-032: Premium chest purchase

Buy higher-rarity chests with gems or IAP.

M Audit 1

WI-033: Accessibility improvements

Screen reader support, color-blind modes, text scaling, touch target sizing.

M Audit 1

WI-034: Additional locales

Beyond EN/ES: PT, FR, DE, IT, JA, KO, ZH based on target market data.

S per locale Audit 1

WI-035: Visual polish pass

Consistent theming, animation quality, visual regression snapshots for mobile viewports.

M Both

5. PRD: Splash & Loading Screen

WI-003: Splash & Loading Screen

P1 S Sources: Both audits

Problem: The app currently launches directly into the full gameplay dashboard with no branded transition. This feels unprofessional and prevents proper resource loading.

Goal: Display a branded splash followed by a loading screen with progress indication before any gameplay UI appears.

Requirements

Engine splash — Configure project.godot boot splash with MR Ventures branding (logo + background color). Auto-advance after 1.5s.
Game splash scene — MR Ventures logo animation (simple fade/scale), studio mark (optional). Transitions to loading.
Loading scene — Progress bar or progress indicator, rotating business-themed tip text (localized), failure fallback with retry/exit options.
Responsive on slow loads — Loading screen must remain interactive (no frozen frame). Inject-able delay for testing.
Transition — Smooth transition to Welcome (first launch) or Gameplay (returning player).

Content/Assets Required

Asset	Owner	Status
Game logo (high-res)	Art	App icon exists; splash logo needed
Studio mark	Art	Not found; optional
Splash background	Art	Brand-appropriate gradient or image
Loading tip strings (EN/ES)	Content	5-8 rotating tips, localized

Technical Notes

Scenes: scenes/ui/splash.tscn, scenes/ui/loading.tscn
Loading scene uses Godot's ResourceLoader async loading with progress callback
Route: MainNode decides next scene based on save state (fresh vs returning vs corrupted)

Definition of Done

Branded splash displays before any gameplay
Loading screen shows progress and does not appear frozen
Failure during load shows retry/fallback, not crash
Returning players skip welcome, go to gameplay after loading
Tip text is localized (EN/ES)

Test Cases

Fresh install → splash → loading → welcome
Returning player → splash → loading → gameplay
Injected 10s delay → loading remains responsive
Failed resource load → error/retry shown, no crash

6. PRD: First-Time User Experience (FTUE)

WI-004: Welcome & FTUE Flow

P1 M Sources: Both audits

Problem: New players see the full game at once with no guidance. Competitive analysis shows all successful idle games start with 1-2 visible systems and a guided first 5 minutes.

Goal: Guide new players through their first session so they understand the core loop (earn → upgrade → mission → chest → rank) within 5 minutes.

Welcome Flow (One-Time)

Step	Screen	Player Sees	Player Action	Purpose	Skip?	Save Flag
1	Welcome	Finley + "Welcome to MR Ventures" + tagline	Tap "Begin Your Journey"	Establish game fantasy	No	`welcome_seen`
2	Scenario Intro	"You start with a small investment and a big dream..."	Tap "Let's Go"	Set narrative context	No	`scenario_intro_seen`
3	First Generator	Dashboard with G1 spotlighted, dimmed background	Tap generator to produce	Teach tap-to-earn	No	`first_tap_done`
4	First Cash	Cash counter animates up, brief celebration	Continue tapping	Positive reinforcement	Soft	`first_earn_done`
5	First Upgrade	Upgrade button glows when affordable	Tap upgrade	Teach reinvestment	No	`first_upgrade_done`
6	Mission Introduction	Mission bar highlighted	Acknowledge	Introduce goal structure	Soft	`mission_intro_done`
7	First Mission Complete	Mission completion + chest popup	Claim chest	Teach reward loop	No	`first_chest_done`
8	First Staff (if earned)	Staff tab spotlight	View earned staff	Introduce collection	Soft	`staff_intro_done`
9	First Rank-Up	Rank-up celebration, HQ tab unlocks	Explore HQ	Celebrate milestone	Soft	`rank_up_intro_done`
10	Market Introduction	Market tab + available ventures	Browse market	Portfolio expansion	Soft	`market_intro_done`
11	First EA	Execs tab spotlight	Start first EA	Strategic investment	Soft	`ea_intro_done`
12	Staff Assignment	Generator detail Team tab	Assign staff	Teach bonuses	Soft	`staff_assign_done`

First-Time User State Machine

State	First Screen	Save Behavior	Tutorial Behavior
Fresh install, no save	Splash → Loading → Welcome	Create save after first playable	Run full FTUE
Fresh install, cloud save found	Cloud restore choice	No local save until choice resolved	Use restored flags or FTUE
Returning local save	Splash → Loading → Gameplay	Load save, calculate offline	Skip completed tutorials
Returning, cloud conflict	Conflict resolver	Preserve both until choice	Suppress during resolution
Corrupted save	Recovery dialog	Quarantine bad save	Preserve flags if recoverable
After app update	Loading → migration	Run versioned migrations	Show only new-feature tutorials
Long offline return	Gameplay + offline popup	Calculate once, mark claimed	First offline tutorial only once
New scenario	Scenario intro	New scenario file, global preserved	Scenario intro, not full FTUE
Progress reset	Confirm → fresh welcome	Delete after confirmation	Restart tutorials
No network	Local gameplay	Local save, queue sync	No forced change

Definition of Done

New player sees welcome and understands first goal within one screen
Core loop (earn → upgrade → mission → reward) demonstrated within 5 minutes
All tutorial save flags persist across restarts
Returning players never repeat completed tutorials
Skip/replay accessible from Settings
All text localized (EN/ES)

7. PRD: Progressive Feature Unlocks

WI-005: Progressive Feature Visibility

P1 M Sources: Both audits

Problem: All 5 tabs and all systems are visible from the start. This overwhelms new players and violates the universal idle-game pattern of progressive disclosure.

Feature Visibility Schedule

System	Recommended State	Current State	Unlock Trigger
Dashboard / Generators	OPEN AT START	Open	Always visible
Upgrade Button	OPEN AT START	Open	Always visible
Mission Bar	OPEN AT START	Open	Always visible
Rank Display	OPEN AT START	Open	Always visible (simplified)
HQ Tab	VISIBLE BUT LOCKED	Open	Rank 2 or first EA complete
Execs Tab	HIDDEN UNTIL UNLOCK	Open	First generator at GC1 or first EA available
Market Tab	VISIBLE BUT LOCKED	Open	G2 visible as preview; active at Rank 3
Market Research	HIDDEN UNTIL UNLOCK	Lock icon shown	2 generators + 120s runtime
Staff Tab	HIDDEN UNTIL UNLOCK	Open (48 locked roster)	First staff earned from chest
Store Tab	HIDDEN UNTIL UNLOCK	Visible, content locked at Rank 4	Rank 4 + gem value taught
Settings	ALWAYS ACCESSIBLE	Missing	Gear icon, always visible
Offline Return	AFTER FIRST RETURN	Works	First meaningful return
Gem Speedup	HIDDEN UNTIL UNLOCK	Missing	After Rank 2 gem grant

Technical Approach

Create FeatureVisibilityService (pure C#) that evaluates visibility rules against player state
Rules use min_rank, save flags, and state conditions (like "has_staff" or "gems_earned")
Bottom navigation bar reads visibility state from the service on state change events
Tab animations for unlock moments (slide-in, glow, one-time celebration)

Definition of Done

Fresh player sees only Dashboard + Mission Bar + Rank at start
Each tab unlocks individually with visual announcement
Unlock triggers match the table above
Visibility state persists across restarts
No tab shows empty or useless content when first unlocked

8. PRD: Tutorial System Activation

WI-006: Tutorial System Activation

P1 M

Current State: TutorialManager autoload exists with priority sorting, ShowOnce logic, and save-backed shown IDs. Only 2 tutorial resources are wired (Market Research, HQ Upgrades).

Required Tutorial Resources

Tutorial ID	Trigger Event	Target UI	Blocking?	Priority
`tutorial_welcome`	First launch, no save	Welcome screen	Yes	100
`tutorial_first_generator`	Dashboard loaded first time	G1 card spotlight	Soft	90
`tutorial_first_upgrade`	Cash reaches upgrade cost	Upgrade button glow	No	80
`tutorial_missions`	First mission visible	Mission bar	No	70
`tutorial_first_chest`	First mission complete	Chest popup	Yes	90
`tutorial_staff_intro`	First staff earned	Staff tab	No	70
`tutorial_rank_up`	Rank 2 reached	Rank-up popup + HQ	No	80
`tutorial_market`	Market tab unlocks	Market tab	No	70
`tutorial_market_research`	MR conditions met	Research tab	Yes (existing)	80
`tutorial_first_ea`	First EA available	Generator detail Ops	No	70
`tutorial_staff_assign`	Staff + empty slot available	Generator detail Team	No	60
`tutorial_hq_upgrades`	HQ tab first open	HQ section (existing)	No	60
`tutorial_offline_return`	First meaningful return	Offline popup	No	50
`tutorial_store`	Store tab unlocks	Store section	No	40

Definition of Done

All listed tutorial resources created as .tres files
DomainEventBus subscriptions in TutorialManager for each trigger
ShowOnce flag persists and prevents repeats
Tutorial replay option accessible from Settings
Tutorial skip option for advanced players
All tutorial text localized (EN/ES)

9. PRD: Tab Badges & Attention Indicators

WI-015: Tab Badges & Attention Indicators

P2 M

Indicator Priority System

Priority	Indicators	Rule
P0 Critical	First affordable upgrade, completed required EA/deal, completed scenario mission, rank-up pending	Only one P0 active at a time
P1 High	Mission chest ready, G2 buyable after slot unlock, staff assignable to open slot, Market Research unlocked	Visible but suppressible if P0 exists
P2 Reminder	Offline return ready, HQ upgrade affordable, newly unlocked content	Non-urgent reminders
P3 Promo	Store offer, rewarded ad multiplier, optional premium chest	Never during first 5 minutes

Tab Badge Triggers

Tab / Surface	Show When	Clear When
Market tab	EA or Deal completes (reward ready)	Reward collected
HQ tab	Enough gems for available upgrade	Upgrades purchased or gems below threshold
Execs tab	EA completes, reward ready to claim	All completed EA rewards claimed
Staff tab	New staff earned and not viewed, or unassigned staff with available slots	Staff tab opened + staff viewed, or staff assigned
Store tab	New offer unlocked at current rank	Store tab opened and offers viewed
Generator card	EA/Deal reward ready for this generator	Reward collected
Mission bar	Mission progress reaches 80%+	Mission completed and claimed
Upgrade button	Player has enough cash to upgrade	Generator upgraded or cash drops

Definition of Done

Red dot indicator on each applicable tab/surface
Priority arbitration prevents indicator overload
Indicators clear correctly after action taken
No stale indicators after app restart

10. PRD: Settings Screen

WI-008: Settings Screen

P1 S

Required Settings

Setting	Type	Default	Persisted
Music Volume	Slider 0-100	100	Yes (user prefs)
SFX Volume	Slider 0-100	100	Yes
Haptic Feedback	Toggle	On	Yes
Language	Dropdown (EN/ES)	System locale	Yes
Replay Tutorial	Button	N/A	Resets tutorial flags
Support / Contact	Link	N/A	N/A
Credits	Link/screen	N/A	N/A
Privacy Policy	Link	N/A	N/A
Version Info	Label	N/A	N/A
Reset Progress	Button (confirm dialog)	N/A	Deletes save

Access

Gear icon in top-right of dashboard, always visible
Opens as popup/overlay, not a full screen transition
Audio settings respected from first frame (including splash)

11. PRD: Save System Hardening

WI-009: Save System Hardening

P1 L Source: Audit 2

Current State: SaveService loads local JSON saves and handles version migration. No user-facing recovery UI for corrupted saves. No cloud support.

Requirements

Corrupted Save Detection — JSON parse failure, missing required fields, invalid version all trigger recovery path
Recovery Dialog — When corruption detected, show user-facing dialog: "Save data appears corrupted" with options: Retry, Restore from Backup, Start Fresh
Backup Strategy — Auto-backup save file on each successful save (keep last 3 backups). Backup in separate directory from primary save.
Quarantine — Move corrupted file to quarantine directory (don't delete). Include timestamp and error reason.
Migration Verification — After running versioned migration, validate result before overwriting. Rollback on validation failure.
Integrity Hash — Optional SHA256 checksum stored alongside save to detect file tampering/corruption.

Test Cases

Write invalid JSON to global_profile.json → recovery dialog shown
Delete required save field → migration or recovery triggered
App closed during save write → backup auto-restores
Version migration from older save → data preserved, no loss
Successful save → 3 recent backups maintained

12. PRD: Analytics Foundation

WI-010: Analytics Foundation

P1 M

Current State: DomainEventBus and EventRecorder exist for MCP-based testing. No production telemetry sink, schema validation, or analytics SDK.

Architecture

AnalyticsService (pure C#) — accepts events, validates schema, dispatches to sink
AnalyticsSink interface — implemented by production SDK adapter (Firebase, Amplitude, etc.) and debug logger
Leverage existing DomainEventBus subscriptions in EventRecorder as reference
Every event includes: player_id, session_id, app_version, platform, scenario_id, global_rank, save_state, tutorial_state, elapsed_time_since_launch

Minimum Launch Event Schema

Event	Trigger	Extra Data
`app_launch_started`	App entry point	launch_type (fresh/return/update)
`splash_screen_shown`	Splash displayed	—
`loading_started`	Loading begins	—
`loading_completed`	Loading finishes	duration_ms
`loading_failed`	Loading error	error_type
`new_player_detected`	No save found	—
`returning_player_detected`	Valid save found	offline_duration
`welcome_screen_shown`	Welcome displayed	—
`welcome_continue_clicked`	Player taps continue	—
`tutorial_started`	Tutorial begins	tutorial_id
`tutorial_step_completed`	Step finished	tutorial_id, step_index
`tutorial_skipped`	Player skips	tutorial_id, step_index
`first_generator_seen`	G1 visible	—
`first_cash_earned`	First production	amount
`first_upgrade_completed`	First upgrade	generator_id, level
`first_mission_completed`	First mission done	mission_id
`first_chest_earned`	First chest opened	rarity, staff_id
`rank_increased`	Rank up	old_rank, new_rank
`first_session_ended`	First session close	duration, rank, generators

Dependencies

Analytics provider selection (Firebase Analytics, Amplitude, or custom)
Privacy consent flow (WI-014)

13. PRD: Monetization & IAP Integration

WI-011: IAP Integration / Purchase Provider

P1 XL

Current State: Store UI, offer catalog, and StorePurchaseProviders.cs interface exist. Active provider is UnavailableStorePurchaseProvider. No rewarded ad SDK, receipt validation, purchase restore, or platform credentials.

Requirements

Platform IAP Provider — Implement Apple StoreKit / Google Play Billing behind existing IStorePurchaseProvider interface
Receipt Validation — Server-side or client-side receipt verification
Purchase Restore — Restore previously purchased non-consumables on reinstall
Failure Handling — Graceful handling of: cancelled, failed, network error, already owned
Rewarded Ads — Interface + provider for rewarded video ads (offline earnings double, production boost)
Ad Caps — Frequency limits to prevent ad fatigue
Non-Gating — No progression path requires purchase. All store items are accelerants.
Store Hidden Before Value — Store tab hidden until Rank 4 + gem value taught (per progressive unlock schedule)

MVP Decision Point

If IAP/ad integration is not ready for MVP launch, the Store tab should remain hidden and monetization disabled. The game should be fully playable F2P.

Test Cases

Sandbox IAP purchase → item granted, receipt valid
Restore purchase on fresh install → items restored
Purchase failure (cancelled, network) → graceful error, no item granted
Rewarded ad unavailable → button hidden/disabled, no crash
Ad cap reached → ad button disabled with cooldown
Store unlock timing → not visible before Rank 4

14. PRD: CI/QA Gate Promotion

WI-012: CI Gate Promotion

P1 M Source: Audit 2

Current State: C# lint, build, and test are required. GDScript lint and test are advisory (continue-on-error). No Godot import, resource validation, publish settings, smoke test, or export build in CI. CI uses Godot 4.5.1 while project declares 4.6.

Required CI Status Checks (promote to blocking)

Check	Current Status	Target Status
C# lint + build + test	Required	Required
GDScript lint	Advisory	Required
GDScript tests (GUT)	Advisory	Required
Godot import (4.6)	Missing	Required
Resource validation	Missing	Required
Publish settings check	Missing	Required
Smoke launch test	Missing	Required
Export dry-run	Missing	Required

Actions

Update CI Godot version from 4.5.1 to 4.6.x
Remove continue-on-error from GDScript jobs
Add Godot headless import step before GUT
Add validate-publish-settings.sh as CI step
Add resource validation job (scenario data, localization keys)
Add export dry-run for Android/iOS

15. PRD: Export & Mobile Readiness

WI-013: Export & Mobile Readiness

P1 L

Requirements

Test autoload stripping — Verify tools/strip-test-autoloads.sh removes MR Ventures Test Bridge, Godot MCP, and TestStateQuery from release exports
Safe-area layout — All UI respects notch/home indicator safe areas on iPhone X+, Android punch-hole displays
App icon — Production icon for all required sizes (Android adaptive, iOS all sizes)
Export presets — Verify export_presets.cfg excludes development saves, test fixtures, docs
Signed builds — APK signing for Android, provisioning for iOS
Device matrix — Test on: iPhone SE (small), iPhone 15 (standard), iPad (tablet), Android low-end (720p), Android mid-range

Definition of Done

Signed test builds launch on all device matrix targets
No debug/test autoloads in release builds
Safe-area respected on all tested devices
No missing resource errors in device logs
Stable 60fps performance on mid-range devices

16. PRD: Celebration Animations & Audio

WI-019: Celebration Animations

P2 M Source: Audit 1

Celebration Moments

Moment	Current State	Target
Rank-up	Basic popup	Animated celebration with rank badge reveal, particles, sound
Generator Evolution	Basic popup	Visual transformation sequence, new appearance reveal
Generator Acquisition	Celebration popup exists	Polish: confetti, card flip reveal, sound
Milestone Achievement	Toast notification	Brief celebration overlay with milestone icon
First Staff Earned	Chest popup	Special first-staff reveal with character art highlight
Chest Opening	Popup exists	Chest opening animation, rarity glow, reveal sequence

17. PRD: Content & Education Polish

WI-021: Financial Education Popups

P2 M

Current State: Content is reality-anchored with professional business themes. No educational moments implemented in the FTUE.

Education Moment Map

Moment	Financial Concept	Placement
First Cash Earned	Revenue generation	After first production cycle
First Upgrade	Reinvestment / compound growth	After first upgrade
First Deal	Strategic partnerships	After first deal complete
First Staff	Human capital investment	After first staff earned
First Offline Return	Passive income	Offline earnings popup
Market Research	Market analysis / due diligence	Research unlock
Generator Evolution	Business scaling / growth stages	Evolution celebration

Content Requirements

Each moment: one concise sentence (localized EN/ES)
Optional Finley speech bubble for delivery
Tone: reality-anchored, optimistic, professional (per CONTENT_AUTHORING_GUIDELINES.md)
Never blocks gameplay, always contextual

18. PRD: Market Card State Model

WI-017: Market Card State Model Expansion

P2 M Source: Audit 2

Card States

State	Visual	Interaction
LOCKED (rank required)	Greyed out, "Unlock at Rank X" badge	Tap shows rank requirement detail
SLOT_CAPPED	Visible but dimmed, "Generator slot available at Rank X"	Tap shows slot unlock path
CASH_SHORT	Full art, price in red, "Need X more"	Tap shows cost breakdown
BUYABLE	Full art, glowing CTA, price visible	Tap to purchase
NEWLY_UNLOCKED	Full art with "NEW" badge, subtle animation	Badge clears after first view
OWNED	Full art, "OWNED" overlay, level shown	Tap navigates to generator detail

19. PRD: Gem Speedup System

WI-018: Gem Speedup System

P2 M Source: Audit 1

Context: By Rank 30, F2P players earn ~670 deterministic gems. HQ upgrades cost ~720 total. A gem speedup system creates an additional meaningful gem sink and decision point.

Speedup Targets

Target	Mechanic	Gem Cost
EA Timer Skip	Instantly complete a running EA	Scaled by remaining time (e.g., 1 gem per 30s remaining)
EA Instant Start	Start and complete EA in one action	Full time equivalent
Production Boost	2x production for 30 minutes	Fixed cost (e.g., 5 gems)

Unlock

Hidden until Rank 2 gem grant (after gems have value)
Tutorial explains speedup concept with first gem grant
Never required for progression — purely accelerant

20. PRD: Cloud Save & Remote Config

WI-027: Cloud Save (Post-Launch)

P3 L

Requirements

Cloud adapter interface — Abstract cloud storage behind interface (supports Google Play Games, Apple Game Center, Firebase, custom)
Conflict resolution UI — When local and cloud saves diverge, show comparison (rank, generators, playtime) and let player choose
Auto-sync — Upload save to cloud on meaningful state changes (rank up, mission complete, app pause)
No-network graceful degradation — Queue sync for later, play locally
No silent overwrite — Never silently replace local or cloud save

WI-030: Remote Config (Post-Launch)

Server-side economy parameters (upgrade cost multipliers, chest drop rates, mission cadence)
Feature flags for gradual rollout
Event scheduling (limited-time scenarios, seasonal content)

21. Consolidated QA Test Plan

Merged from both audit sources, deduplicated, and prioritized.

P0 Critical Path Tests

ID	Test Name	Setup	Steps	Expected Result
QA-001	Fresh install to first rank-up	Delete save data	Launch → complete welcome → tap generator → upgrade → complete mission → claim chest → reach Rank 2	Player progresses to Rank 2 without confusion. Rank-up popup appears. HQ tab unlocks.
QA-002	Generator acquisition from Market	Player at Rank where G2 available	Open Market → find generator → purchase → observe celebration → return to dashboard	Generator purchased, celebration plays, appears on dashboard, functional.
QA-003	Mission + chest + staff	Active mission near completion	Complete mission → chest popup → open chest → staff granted → new mission appears	Full reward chain works. Staff added. Next mission generated.
QA-004	EA start, wait, and claim	Player with available EA	Start EA → wait for timer → claim reward → verify resources	Timer works. Completion dot shows. Reward credited. Slot restored.
QA-005	Staff assignment	Player has staff + empty generator slot	Navigate to Team tab → assign staff → verify bonus	Staff assigned. Generator stats updated. Staff shows assigned state.
QA-006	Save persistence across restart	Player with Rank 3+, multiple generators	Note state → close app → relaunch → verify	All progress restored. Offline earnings calculated.
QA-007	Case-sensitivity / Android export	Android APK export	Export → install → navigate all tabs → check logs	No missing resource errors. All scenes load.

P1 Save/Load & Edge Cases

ID	Test Name	Setup	Expected Result
QA-008	Corrupted save recovery	Invalid JSON in save	Recovery dialog shown, not silent data loss
QA-009	Offline earnings accuracy	Note income rate, close 30min	Earnings match 30% * online_rate * time
QA-010	Tutorial does not repeat	Completed tutorial save	No tutorials repeat on relaunch
QA-011	App closed during tutorial	Close during first upgrade highlight	Tutorial resumes or restarts coherently
QA-012	Tutorial skipped	Fresh launch, skip tutorial	Skip persists, can be reset from Settings
QA-013	Cloud save restore	No local, cloud profile exists	Cloud restored without duplicate grants
QA-014	Cloud conflict	Divergent local/cloud saves	Conflict UI, no silent overwrite
QA-015	No network on launch	Network disabled	Local play works; cloud/store/ads show unavailable
QA-016	Slow loading	Inject 10s delay	Loading screen responsive, communicates progress
QA-017	Failed resource load	Missing scenario data	User-facing fallback, no crash
QA-018	App closed during splash	Close during splash	No partial save corruption on relaunch
QA-019	Save migration from older version	Older save version	Migration succeeds; relevant tutorials shown

P1 Economy & UI

ID	Test Name	Setup	Expected Result
QA-020	Generator upgrade cost scaling	Generator at levels 1/10/25/50/100	Costs follow GeneratorStatsCalculator. Player never permanently stuck.
QA-021	Gem economy balance	Track gems Rank 1-15	F2P players earn enough for several HQ upgrades
QA-022	Tab navigation	All tabs unlocked	All open/close correctly, rapid switching no glitches
QA-023	Popup stack behavior	Trigger multiple popups	Queue correctly, none swallowed
QA-024	Attention dots clear	Completed EA with dot	Dot clears after reward collection
QA-025	Store offer rank gating	Various ranks	Locked offers show rank requirement. Purchase reflects provider state.
QA-026	Pity system	Fresh save, known pity state	First-rare/epic guarantees fire. Pity counter tracks correctly.
QA-027	Generator evolution	Generator at evolution threshold	Evolution triggers, celebration plays, stats update, save correct
QA-028	Insufficient funds handling	Less cash than needed	Clear feedback, no silent failures, no negative balance
QA-029	Spanish locale coverage	Switch to ES	All text in Spanish, no English fallback visible, text fits containers
QA-030	Performance under load	8 generators, all staff assigned	60fps sustained, memory stable, no crashes
QA-031	Safe area / screen sizes	Phone/tablet aspect fixtures	No clipped text, overlaps, or unsafe-area violations

22. Competitive Benchmark Summary

Game	First 5 Minutes	Locked Features	Monetization Timing	Key Lesson for MR Ventures
AdVenture Capitalist	1 business, fast upgrades, automation later	Managers, angels, regions	After angel reset (~30min)	Start ultra-simple, tease complexity
Idle Miner Tycoon	1 mine, 3 shafts, first manager gifted, forced tutorial	Continents, super managers	Ad boosts from minute 5	Force first manager tutorial, progressive unlocks
Egg, Inc.	1 farm, tap to earn, research early, drones	Prestige hidden, silos limited	Piggy bank (delayed IAP)	Drones create engagement, delayed IAP is clever
Shop Titans	Craft item, sell, restock, guided tutorial	Market, guild, workers, quests	After level 5-10	Every new menu appears because player needs it
Cookie Clicker	Click, buy cursor, grandmas unlock naturally	Golden cookies random, prestige at ~1M	Premium DLC only	Minimal UI, everything by natural progression
Monopoly GO	Roll dice, land on properties, tutorial guided	Events, sticker packs	Immediate but non-blocking	Familiar theme reduces learning curve
Idle Theme Park Tycoon	Upgrade rides, earn idle cash	Managers, cards, research	Ads after park loop	Staff/managers follow proven timing
Idle Bank Tycoon	Upgrade bank areas, manage flow	Managers, new banks	Ads double production	Offline/ad boosts solve known friction

Universal Patterns MR Ventures Must Follow

MR Ventures currently violates 6 of 8 universal idle-game patterns. These must be fixed before production launch.

Only 1-2 things visible at start — complexity hidden and revealed progressively VIOLATED
Forced/soft tutorial for first 2-5 actions — players guided through core loop VIOLATED
Monetization delayed at least 5-15 minutes — value established first VIOLATED
New features unlock one at a time with celebration VIOLATED
Locked features teased with locks/previews PARTIAL
Tab badges/indicators guide next action VIOLATED
Offline return includes ad-double option PARTIAL
Store hidden/locked until value established VIOLATED

23. Ideal First 5 Minutes

Time	Player Moment	UI Shown	Tutorial/Indicator	Hidden	Desired Feeling
0-5s	Launch	Logo splash	None	Everything	Polished
5-10s	Loading	Loading screen + tips	Progress bar	All systems	Intentional
10-25s	Welcome	Finley + brand promise	One tap continue	All tabs	Curious
25-60s	First generator	G1 dashboard only	Soft upgrade highlight	All tabs, full mission bar	Momentum
1-1.5m	First upgrade	Upgrade button glows	Celebration	Mission appears	Rewarded
1.5-2m	First mission progress	Mission bar highlighted	Progress tracking	HQ teased	Goal-driven
2-3m	First mission complete	Mission reward + chest	Chest opening	Staff teased if earned	Surprised
3-4m	First chest opened	Reward reveal	Staff intro if applicable	Store, most tabs	Collecting
4-5m	Second generator preview	Market tab unlocks	G2 as aspiration	Store, Staff (if no staff yet)	Anticipation

Current state: MR Ventures skips steps 1-5 entirely. The player sees the full game at 0 seconds with no guidance, no splash, no welcome, no tutorial, and all tabs visible.

24. Appendix: Specification Conflicts & Resolutions

Conflict	Resolution	Status
8 vs 12 generators	Pacing Master targets 8. Older docs reference 12. Implementation: 8 generators.	RESOLVED
GC naming vs Evolution naming	Code uses `evolution_order` (0-5), docs use "Generator Chapters GC0-GC5". Functionally equivalent.	RESOLVED
Staff slots at GC0	Pacing Master says 0 slots at GC0. Implementation correct (no slots until EA rewards).	RESOLVED
Deals have no rewards	Both Pacing Master and EA Architecture confirm deals grant RP but no item rewards. Implementation matches.	RESOLVED
G1 start behavior	Pacing Master says G1 owned and running at start. Current save shows 2 generators — may be non-fresh state.	NEEDS VERIFICATION
Gem economy balance	670 deterministic gems by Rank 30. HQ upgrades cost 720. Deficit of 50 gems requires 1 purchase or ad reward. Acceptable for soft monetization.	RESOLVED

Unresolved Unknowns

Whether a fresh Godot run reaches first playable gameplay without runtime errors
Whether all UI layouts are production-ready on target devices and safe areas
Whether first-session pacing hits exact target timing bands in live play
Whether export stripping removes debug autoloads in final builds
Whether all icon/image references are valid under an export build
Theme & Tone reference PDF not found in repository — content review may need external source

Build Verification Data

Command	Result
`dotnet --version`	9.0.203
`dotnet test tests/csharp/MR Ventures.Tests.csproj`	622 passed, 0 failed, 0 skipped
`dotnet build "MR Ventures 2025 Godot.csproj"`	Build succeeded, 0 errors, 495 warnings
`./tools/validate-gdscript.sh`	GDScript validation passed
`./tools/validate-publish-settings.sh`	All publish settings checks passed
`node --test tools.test.js`	21/21 passed