neon-sprawl/docs/decomposition

Decomposition Workspace

This workspace contains detailed planning artifacts derived from the finalized master plan:

• Source of truth: neon_sprawl_vision.plan.md — design axioms (fun + distinctly cyberpunk theme) live under Design axioms (governing) in that file.
• Tech stack baseline: docs/architecture/tech_stack.md
• Scope here: executable decomposition (epics, modules, milestones)

Folder Layout

• epics/ - One file per player-facing epic (E1–E9) with implementation slices.
• tooling/ - Cross-cutting operator tracks (e.g. content authoring) that are not numbered with the nine core epics; same slice style, separate CT.* module IDs.
• modules/ - Contract definitions, client vs server authority, PvP × combat engine, quest scope × party, data reload × telemetry ops, docs vs implementation, full module dependency register (E1–E9 and CT modules), per-module docs, and interface notes.
• milestones/ - Phase-gated implementation tracks and pass/fail checklists.

Working Rules

1. Do not rewrite baseline vision in these files; link back to the master plan.
2. Keep slices backlog-ready (clear owner, dependencies, acceptance criteria).
3. Use stable IDs (E1, E1.M1, etc.) for core game epics; use CT.M1-style IDs for content tooling so tooling stays out of the E1–E9 sequence.
4. Every new slice must reference telemetry and validation where applicable.

Full-stack epics

Epics deliver playable game features, not server-only vertical slices. Enforced by .cursor/rules/full-stack-epic-decomposition.md (alwaysApply).

When decomposing a prototype backlog:

1. Start from docs/plans/_prototype-backlog-template.md.
2. Pair server and client stories where the feature is player-visible (mirror Epic 1: NEO-23 + NEO-24).
3. Create all Linear issues and blockedBy links in the same decomposition pass — including client slices — not as undocumented “optional follow-ups.”
4. Bruno / manual QA prove contracts; Godot proves the prototype fun/readability gates in vision.

Epic 3 established a dedicated client slice file: E3S5-client-prototype-backlog.md (NEO-72–NEO-75). Apply the same pattern to other epics (e.g. planned E2 client slice for skill/perk HUD).

Linear alignment

Engineering work is tracked as issues in Linear (team NEO), grouped under projects that mirror epics and modules. Do not recreate a Jira-style Feature issue tier—module- or slice-level grouping is labels on the issue only.

Express that grouping with labels (for example the decomposition module id — E1.M1, CT.M2, etc.). Issues belong to a project (e.g. Epic 1, E1.M1, Tech Debt); labels carry scope without a separate Feature work item.

Epic files (E1–E9, master plan)

Epic	Document
1 - Core Player Runtime	epics/epic_01_core_player_runtime.md
2 - Skills and Progression Framework	epics/epic_02_skills_and_progression.md
3 - Crafting Economy	epics/epic_03_crafting_economy.md
4 - World Topology	epics/epic_04_world_topology.md
5 - PvE Combat	epics/epic_05_pve_combat.md
6 - PvP Security	epics/epic_06_pvp_security.md
7 - Quest / Faction	epics/epic_07_quest_faction.md
8 - Social / Guild	epics/epic_08_social_guild.md
9 - LiveOps / Integrity	epics/epic_09_liveops_integrity.md

Template for new epics or major revisions: epics/_epic_template.md

Cross-cutting tooling (not E1–E9)

Track	Document	Modules (register)
Internal authoring & content pipeline	tooling/internal_authoring.md	CT.M1–M3

Next Actions

1. Expand slices into Linear issues under epic/module projects when writing a prototype backlog — copy _prototype-backlog-template.md; follow full-stack epic decomposition. Create all issues and blockedBy links in the same decomposition pass, not at story kickoff. Set estimate 1…N on each issue to match slug execution order so the project board can sort by Estimate (ascending). Tag server / client and module scope with labels. Keep module IDs aligned with the master plan.
2. Populate modules/module_dependency_register.md as contracts stabilize.
3. Refine milestones/phase_execution_plan.md with dates and owners when execution starts.