# Decomposition Workspace

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

- Source of truth: [`neon_sprawl_vision.plan.md`](../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`](../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](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [docs vs implementation](modules/documentation_and_implementation_alignment.md), [full module dependency register](modules/module_dependency_register.md) (E1–E9 and CT modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), 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](tooling/internal_authoring.md) 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. When decomposing a prototype backlog (`docs/plans/E*M*-prototype-backlog.md` or slice-specific files like [E3S5-client-prototype-backlog.md](../plans/E3S5-client-prototype-backlog.md)):

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

Epic 3 established this pattern with **Slice 5 — Client economy integration** after Slices 1–3 server work. Apply the same pattern to other epics going forward.

## 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](epics/epic_01_core_player_runtime.md) |
| 2 - Skills and Progression Framework | [epics/epic_02_skills_and_progression.md](epics/epic_02_skills_and_progression.md) |
| 3 - Crafting Economy | [epics/epic_03_crafting_economy.md](epics/epic_03_crafting_economy.md) |
| 4 - World Topology | [epics/epic_04_world_topology.md](epics/epic_04_world_topology.md) |
| 5 - PvE Combat | [epics/epic_05_pve_combat.md](epics/epic_05_pve_combat.md) |
| 6 - PvP Security | [epics/epic_06_pvp_security.md](epics/epic_06_pvp_security.md) |
| 7 - Quest / Faction | [epics/epic_07_quest_faction.md](epics/epic_07_quest_faction.md) |
| 8 - Social / Guild | [epics/epic_08_social_guild.md](epics/epic_08_social_guild.md) |
| 9 - LiveOps / Integrity | [epics/epic_09_liveops_integrity.md](epics/epic_09_liveops_integrity.md) |

Template for new epics or major revisions: [epics/_epic_template.md](epics/_epic_template.md)

## Cross-cutting tooling (not E1–E9)

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

## Next Actions

1. Expand slices into **Linear issues** under epic/module **projects** when writing a **prototype backlog** (`docs/plans/E*M*-prototype-backlog.md`) — **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 **module / slice** scope with **labels** (not a duplicate Feature tier). 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.