# Phase 7.2 Next-Step Proposal: Hi Fi Snake build023.zip

## Proposal Summary

The primary focus of the next build cycle must be overhauling the first-session onboarding experience. Playtest data shows that players fail to build a basic mental model of the game, often moving straight forward without collecting pellets or turning, leading to rapid deaths from hazards. We must rebuild the first three rooms to teach mechanics progressively without early punishment, redesign the intrusive tutorial popup flow, and replace discouraging long-term missions with immediate, achievable goals.

## Urgent

* **Rebuild the First Three Rooms (Level Design Onboarding)**: Replace the current punishing start with a progressive sequence. Room 1 must be a safe, hazard-free space where pellet placement forces lateral movement. Room 2 should introduce simple walls to teach turning. Room 3 should introduce hazards (lava/fire) only after movement is understood. (Evidence Class: evidence_backed; Source Finding: Players fail to build a mental model / Early deaths to red barriers)
* **Review first-room pellet placement**: Position pellets so players must intentionally perform multiple left/right turns before reaching the first door. Avoid allowing the first door to be reached primarily through forward movement.
* **Redesign Tutorial Flow & Dismissal**: Remove the opening popup that explains mechanics before players experience them. Instead, show contextual hints (e.g., "Collect pellets to open doors") only after the first door unlocks. Ensure all tutorial popups can be dismissed by tapping anywhere on the screen. (Evidence Class: evidence_backed; Source Finding: Tutorial popup causes friction and is hard to dismiss)
* **Teach One Concept Per Room:** The opening sequence should introduce only one new mechanic at a time (movement → navigation → hazards). Avoid combining multiple new concepts in the same room.

## Next

* **Improve First Reward Loop & Delay Long-Term Missions**: Replace discouraging early missions (e.g., "Collect 100 pellets") with an immediate, highly achievable goal (e.g., "Collect 3 pellets to unlock first skin") to give players an early feeling of success. (Evidence Class: likely; Source Finding: Discouraging early mission goals / High early churn risk)
* **Refine Active-Input Movement Feedback**: Provide clearer visual or audio feedback when players stop moving or freeze under pressure to help them understand that active input is required to navigate hazards. (Evidence Class: likely; Source Finding: Active-input movement causes players to freeze under pressure)

## Later

* **Late-Game Balancing & Procedural Room Selection**: Defer adjustments to late-game pacing, room randomization, and speed scaling. (Reason: Players are currently churning in Room 1 or 2, so we lack sufficient data to evaluate these systems.)
* **Cosmetic Pricing & Mission Economy**: Defer broad economy rebalancing until first-session retention is stabilized. (Reason: Focus must remain on the first 2 minutes of gameplay.)

## Keep

* **Active-Input Player Movement**: Retain the active-input control model as it provides intentional player-driven movement, but soften the early-game environment to prevent panic freezes.
* **Player Speed Progression Formula**: Keep the build023 starting speed at 2.4 and room scaling at 0.55. Keep current movement pacing for now. The playtest does not provide sufficient evidence that speed progression is responsible for early churn.

## Try

* **Contextual Control Prompts**: If a player remains stationary in Room 1 for more than 3 seconds, display a subtle, non-blocking directional arrow overlay on the grid to prompt movement.

## Avoid / Defer

* **Avoid early hazard placement**: Avoid introducing mechanics before they have been taught. For instance, do not place red barriers or walking hazards in the immediate path of the first gate. (Evidence Class: evidence_backed; Source Finding: Early deaths to red barriers)
* **Defer shop expansion**: Avoid adding more cosmetic items or complex menus until the basic onboarding flow is validated. (Evidence Class: likely; Source Finding: High early churn risk)

## Reference Trinity Impact

| Reference Role | Impact | Explanation |
| --- | --- | --- |
| Primary | strengthened | Teaching players how to turn and collect pellets safely builds the foundational mental model required for Snake's self-growing obstacle mechanic. |
| Secondary | unchanged | The room-by-room progression and upgrade cadence inspired by Archero remain intact, though early room layouts are simplified for onboarding. |
| Tertiary | unchanged | Neon spectacle and visual feedback remain, but visual clutter is minimized during the tutorial phase to ensure readability. |

## Evidence Classification

| Proposed Change | Evidence Class | Supporting Evidence |
| --- | --- | --- |
| Rebuild first three rooms | evidence_backed | Multiple players failed to turn or collect pellets, dying immediately to red barriers right after the first gate. |
| Redesign tutorial popup flow | evidence_backed | Peru player took 26s to dismiss the popup; developer notes confirm poor timing and layout issues in portrait mode. |
| Delay long-term missions | likely | Developer notes highlight that showing 100-pellet goals immediately after a player dies with 3-5 pellets feels discouraging. |


## Root Causes

* **Gameplay Teaches Through Failure Instead of Success**: The game immediately tests lateral movement and hazard avoidance before teaching basic grid navigation.
* **Intrusive & Poorly Timed UI**: The opening tutorial popup blocks gameplay, explains mechanics out of context, and is physically difficult to dismiss on mobile.
* **Mismatched Progression Milestones**: Showing long-term grind missions to players who survive for less than 30 seconds creates a feeling of futility.

## Production Risk

* **Onboarding Level Maintenance**: Creating bespoke tutorial rooms (Rooms 1-3) requires manual level design and bypasses the procedural generation system for the start of the run.
* **UI Layout Fragmentation**: Ensuring the tutorial hints and popups scale correctly across both portrait mobile and landscape desktop.

## Next Test Hypotheses

* **Hypothesis 1**: Introducing a hazard-free Room 1 that forces lateral movement to collect pellets will eliminate "Straight-Line Syndrome" and increase Room 1 completion rates by 40%.
* **Hypothesis 2**: Removing the opening popup and allowing tap-anywhere dismissal for contextual hints will reduce onboarding friction and increase the percentage of players completing Room 1 and attempting a second run.

## Suggested Version Note

"Onboarding overhaul: Rebuilt the first three rooms into a safe, progressive tutorial sequence, redesigned tutorial popups for easier dismissal, and introduced achievable early-game goals."

## What To Watch Next

* Observe if players in Room 1 successfully perform lateral turns to collect pellets.
* Track the average time taken to clear Room 1 and Room 2.
* Monitor if players easily dismiss or interact with the new contextual hints.