neon-sprawl/.cursor/rules/full-stack-epic-decomposition.md

description	alwaysApply
Epics deliver playable game features — prototype backlogs must pair server + client stories; forbid Bruno-only "optional UI" deferrals.	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, prototype backlog template.

Canonical pattern

Mirror Epic 1 (E1M3-prototype-backlog): 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) — 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):

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).

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 (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.
• Manual QA (planning-implementation-docs): 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.

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 mention client backlog
• module_dependency_register.md note updated when issues are created

Code review

Reviewers (human or code-review-agent) 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.