# Epic 2 - Skills and Progression Framework

## Source Anchors

- Master epic reference: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, System Modules Epic 2
- Related modules: E2.M1, E2.M2, E2.M3, E2.M4

## Ownership and success (Level 1)

- **Ownership focus:** Systems Design + Gameplay Engineering
- **Success criteria:** Any character can train all **non-combat** **skills** tracked as `SkillDef`, and **skill** progression stays long-term without dead-end grinds (**gig** combat roles are separate—see [`gigs.md`](../../game-design/gigs.md)).

## Objective

Provide a data-driven **non-combat skill** layer: `SkillDef` registry, **skill** XP awards, level curves, and eventually mastery/perk and pacing controls. **Gathering** and **crafting** feed **skill** progression via [E2.M2](../modules/E2_M2_XpAwardAndLevelEngine.md); **combat encounters** feed **gig** progression (not `SkillDef` XP)—see [`docs/game-design/progression.md`](../../game-design/progression.md). **Mission rewards** may still grant **skill** XP when scripted.

## Module Breakdown

### E2.M1 - SkillDefinitionRegistry

- Responsibility: Central catalog for **non-combat** `SkillDef` rows: **stable `id`**, **`SkillCategory`** (`gather` / `process` / `make` / `tech`), **`displayName`**, **`allowedXpSourceKinds`** (which `XpGrantEvent.sourceKind` values may grant XP per skill), and unlock prerequisites. **Combat roles** are **gigs**, not `SkillDef`. Detail: [E2.M1 — SkillDefinitionRegistry](../modules/E2_M1_SkillDefinitionRegistry.md), [`content/schemas/skill-def.schema.json`](../../../content/schemas/skill-def.schema.json).
- Key contracts: `SkillDef`, `SkillCategory`, `UnlockRequirement`; prototype schema requires **`allowedXpSourceKinds`** per skill.
- Dependencies: None
- Stage target: Prototype
- **Linear (Slice 1 prototype):** [Epic 2 project](https://linear.app/neon-sprawl/project/epic-2-classless-skill-and-progression-framework-5200f84bf8b6) — [NEO-33](https://linear.app/neon-sprawl/issue/NEO-33) → [NEO-36](https://linear.app/neon-sprawl/issue/NEO-36) (label **`E2.M1`**); table and ordering in the module doc.

### E2.M2 - XpAwardAndLevelEngine

- Responsibility: XP award rules, level thresholds, level-up event generation.
- Key contracts: `XpGrantEvent`, `LevelCurve`, `LevelUpEvent`
- Dependencies: E2.M1
- Stage target: Prototype
- **Linear (Slice 2 prototype):** [Epic 2 project](https://linear.app/neon-sprawl/project/epic-2-classless-skill-and-progression-framework-5200f84bf8b6) — [NEO-37](https://linear.app/neon-sprawl/issue/NEO-37) → [NEO-38](https://linear.app/neon-sprawl/issue/NEO-38) → [NEO-39](https://linear.app/neon-sprawl/issue/NEO-39); [NEO-40](https://linear.app/neon-sprawl/issue/NEO-40) in parallel with NEO-39 after NEO-38 (label **`E2.M2`**). Detail: [E2.M2 — XpAwardAndLevelEngine](../modules/E2_M2_XpAwardAndLevelEngine.md).
- **Linear (Slice 3 integration):** [NEO-41](https://linear.app/neon-sprawl/issue/NEO-41) (gather + **E3.M1**), [NEO-42](https://linear.app/neon-sprawl/issue/NEO-42) (craft + **E3.M2**), [NEO-43](https://linear.app/neon-sprawl/issue/NEO-43) (mission rewards + **E7.M2**), [NEO-44](https://linear.app/neon-sprawl/issue/NEO-44) (gig XP from combat, **E5.M1** only — no **`E2.M2`** label on NEO-44).
- Note: **E3.M1** and **E3.M2** (and mission/reward routers such as **E7.M2**) integrate as **callers** of **E2.M2** for **skill** XP. **E5.M1** resolves **combat** and advances **gig** progression **outside** **E2.M2**—see Slice 3. None of these are **hard** dependencies for implementing the **E2.M2** core (stub callers in Slice 2).

### E2.M3 - MasteryAndPerkUnlocks

- Responsibility: Mastery tracks and perk unlock state for **skill** build expression beyond raw levels.
- Key contracts: `MasteryTrack`, `PerkDef`, `PerkUnlockEvent`, `PerkState`
- Dependencies: E2.M2, E2.M1 (catalog `skillId` validation)
- Stage target: Pre-production
- **Linear (Slice 4 — E2.M3):** [Epic 2 project](https://linear.app/neon-sprawl/project/epic-2-classless-skill-and-progression-framework-5200f84bf8b6) — [NEO-45](https://linear.app/neon-sprawl/issue/NEO-45) → [NEO-49](https://linear.app/neon-sprawl/issue/NEO-49) (label **`E2.M3`**); flagship **`salvage`** track; table and ordering in [E2.M3 — MasteryAndPerkUnlocks](../modules/E2_M3_MasteryAndPerkUnlocks.md) and [E2M3-pre-production-backlog.md](../../plans/E2M3-pre-production-backlog.md).

### E2.M4 - ProgressionPacingControls

- Responsibility: Tuning knobs for progression velocity and catch-up policy enforcement.
- Key contracts: `XpModifierProfile`, `CatchUpRule`, `PacingPolicy`
- Dependencies: E2.M2, E9.M2
- Stage target: Pre-production

## Implementation Slices (Backlog-Ready)

### Slice 1 - Skill registry and prototype skills

- Scope: E2.M1 with at least three **non-combat** `SkillDef` rows loaded from data—e.g. aligned with **Gather**, **Process** or **Make**, and **Tech** as in [`docs/game-design/skills.md`](../../game-design/skills.md). **Combat role progression** is **gig**-scoped, not a `SkillDef` line (see [`docs/game-design/gigs.md`](../../game-design/gigs.md), [`docs/game-design/progression.md`](../../game-design/progression.md)).
- Dependencies: None
- Acceptance criteria:
  - All prototype activities reference skills by stable IDs.
  - Invalid skill references fail validation in CI or at load time.
- Telemetry hooks: `skill_unlock` (if gating exists), schema validation metrics.

### Slice 2 - XP engine (E2.M2 core)

- Scope: Implement `XpGrantEvent`, `LevelCurve`, `LevelUpEvent`, and server-authoritative level resolution on top of `SkillDef` from E2.M1. No dependency on Epic 3 or Epic 5 modules beyond future call sites.
- Dependencies: E2.M1 (matches module-level E2.M2 → E2.M1 only).
- Acceptance criteria:
  - XP and level-up can be triggered from tests or a stub caller without gathering/combat content.
  - Curves and thresholds are data-driven and hot-reloadable or reloadable by policy agreed for prototype.
- Telemetry hooks: `xp_grant`, `level_up`, time-to-first-level-up (once integration slice fires real activity).

### Slice 3 - XP award integration at activity sites

- **Linear:** [NEO-41](https://linear.app/neon-sprawl/issue/NEO-41), [NEO-42](https://linear.app/neon-sprawl/issue/NEO-42), [NEO-43](https://linear.app/neon-sprawl/issue/NEO-43), [NEO-44](https://linear.app/neon-sprawl/issue/NEO-44) (see **E2.M2** module breakdown above).
- Scope: Wire **gathering** (E3.M1) and **crafting** (E3.M2) to the **E2.M2 skill XP** award API so prototype **`SkillDef`** lines gain XP from real play. Wire **combat** (E5.M1) to **gig XP only** ([`gigs.md`](../../game-design/gigs.md), [`progression.md`](../../game-design/progression.md))—**no** hook that maps **encounter resolution** to **skill** XP or a combat `SkillDef`. **Mission / quest reward** paths may still call the **skill** XP API when the **payout** explicitly includes skill XP (**not** the same as “combat trained this skill”).
- Dependencies: E2.M2, E3.M1, E3.M2, E5.M1 (integration prerequisites; not part of the E2.M2 module dependency list). Gig XP plumbing may live beside E2.M2 or under Epic 5—**split call sites** by progression type (skill vs gig).
- Acceptance criteria:
  - Visible **skill** XP and skill level-up feedback within first session from real **gather/craft** actions.
  - Visible **gig** XP and gig progression feedback from **combat** (main gig only, per game-design).
- Telemetry hooks: `xp_grant`, `level_up`, time-to-first-level-up for **skills**; gig progression hooks as agreed when gig model lands (e.g. `gig_xp_grant`, `gig_level_up`).

### Slice 4 - Mastery and pacing (pre-production)

- **Linear (E2.M3):** [NEO-45](https://linear.app/neon-sprawl/issue/NEO-45) → [NEO-49](https://linear.app/neon-sprawl/issue/NEO-49) — see [E2.M3 module](../modules/E2_M3_MasteryAndPerkUnlocks.md). **E2.M4** pacing backlog is separate (depends on E9.M2).
- Scope: E2.M3 for first **salvage** mastery branch; E2.M4 for global pacing policy when E9.M2 is available.
- Dependencies: E2.M2 (E2.M3); E2.M2 + E9.M2 (E2.M4)
- Acceptance criteria:
  - At least one mastery path unlocks a perk without blocking other skills.
  - Pacing policy can be toggled for test cohorts without redeploy where possible.
- Telemetry hooks: `perk_unlock`, `pacing_profile_applied`.

## Risks and Mitigations

- Risk: XP faucets create runaway leveling in one skill.
  - Mitigation: Diminishing returns per slice; monitor skill distribution via E9.M2.
- Risk: **Skill** progression feels flat without mastery expression.
  - Mitigation: Ship E2.M3 early in pre-production with one flagship mastery line.

## Definition of Done

- Prototype uses E2.M1 + E2.M2 for three **non-combat** `SkillDef` lines (stable **`id`** + **`allowedXpSourceKinds`** per [E2.M1](../modules/E2_M1_SkillDefinitionRegistry.md)); **gig** progression for combat is separate.
- Pre-production adds E2.M3/E2.M4 with documented tuning workflow.
- Events align with baseline telemetry in master plan.