---
description: Epics deliver playable game features — prototype backlogs must pair server + client stories; forbid Bruno-only "optional UI" deferrals.
alwaysApply: true
---

# Full-stack epic decomposition (CRITICAL)

Neon Sprawl is a **game**, not a headless server. Prototype backlogs and epic slices must ship **Godot presentation** for every **player-visible** feature.

## When this rule applies

- Writing or editing **`docs/plans/*backlog*.md`**, **`docs/plans/E*S*-client*.md`**, or **implementation slices** in **`docs/decomposition/epics/epic_*.md`**
- Creating **Linear issues** during decomposition (not at ad-hoc kickoff without client counterparts)
- Reviewing whether an epic/module slice is **“decomposed”** or **“prototype complete”**

Reference: [decomposition README — Full-stack epics](../../docs/decomposition/README.md#full-stack-epics), [prototype backlog template](../../docs/plans/_prototype-backlog-template.md).

## Canonical pattern

Mirror **Epic 1** ([E1M3-prototype-backlog](../../docs/plans/E1M3-prototype-backlog.md)): server contract story immediately followed by client HUD/wiring (e.g. NEO-23 → NEO-24).

For large epics, a dedicated **client slice** file is OK ([E3S5-client-prototype-backlog.md](../../docs/plans/E3S5-client-prototype-backlog.md)) — but **client Linear issues must exist in the same decomposition pass** as server issues, with `blockedBy` links.

## Story classification

| Type | Client story required? | Examples |
|------|------------------------|----------|
| **Infrastructure** | **No** | JSON Schema, CI gates, server catalog load, DB migrations, comment-only telemetry hooks |
| **Player-visible** | **Yes** | Inventory, gather/craft, quests, zone/PvP warnings, combat telegraphs, skill/perk UI, any AC with *player*, *visible*, *HUD*, *select*, *complete*, *understand* |
| **Capstone** | **Yes** | “Playable loop in Godot without Bruno” (e.g. NEO-75) |

Tag **infrastructure-only** stories explicitly in the backlog so agents do not skip UI for the wrong reasons.

## Mandatory backlog contents

When creating `docs/plans/E*M*-prototype-backlog.md` (copy [\_prototype-backlog-template.md](../../docs/plans/_prototype-backlog-template.md)):

1. **Server + client story tables** — every player-visible slug lists **`Client counterpart: NEO-XX`** or points to a client slice slug.
2. **Linear issues created together** — all server **and** client issues + **`blockedBy`** in one decomposition pass; label client issues **`client`** + module id (`E3.M1`, etc.).
3. **Capstone client story** — at least one issue proving the slice is **playable in Godot** (manual QA in `docs/manual-qa/{KEY}.md`), unless the entire epic slice is infrastructure-only (rare).
4. **Epic DoD updated** — prototype Definition of Done says **Godot**, not Bruno-only (see [epic_03 example](../../docs/decomposition/epics/epic_03_crafting_economy.md)).

## Forbidden language

Do **not** use in backlogs or Linear descriptions for player-visible work:

- “Godot HUD (**optional follow-up**)”
- “for manual QA and **future client**” (without a linked **NEO-XX** client issue)
- “client UI deferred” without a **created** client issue id

Use **Out of scope** only for genuinely non-prototype UX (e.g. drag-drop inventory, final art pass).

## Bruno vs Godot

- **Bruno** — proves HTTP contracts and server authority.
- **Godot** — proves [vision prototype gates](../../neon_sprawl_vision.plan.md) (fun, readability, progression visibility).

Do **not** mark a **player-facing** epic slice **complete** when only Bruno passes.

## Kickoff and implementation

- **Story kickoff** for a **server** issue on a player-visible path: plan must **cross-link** the **client counterpart** Linear issue (even if not started). See [story-kickoff](story-kickoff.md).
- **Manual QA** ([planning-implementation-docs](planning-implementation-docs.md)): player-visible **client** stories require `docs/manual-qa/{KEY}.md` with **Godot** steps, not API-only checks.
- **Client scripts:** thin `main.gd`, HTTP client nodes — [godot-client-script-organization](godot-client-script-organization.md).

## Decomposition complete checklist

Before calling an epic slice **decomposed**:

- [ ] Every player-visible acceptance criterion maps to a **`client`** Linear issue
- [ ] No forbidden deferral language in backlog
- [ ] Capstone or client slice issue exists for playable verification
- [ ] Epic / module docs and [documentation_and_implementation_alignment.md](../../docs/decomposition/modules/documentation_and_implementation_alignment.md) mention client backlog
- [ ] [module_dependency_register.md](../../docs/decomposition/modules/module_dependency_register.md) note updated when issues are created

## Code review

Reviewers (human or [code-review-agent](code-review-agent.md)) **should fix** or **block** claims that a **player-facing** prototype slice is done when backlog has **no client issue** or manual QA is Bruno-only.