neon-sprawl/docs/reviews/2026-04-03-branch-chore-game-design-docs-vs-main.md

# Branch review — `chore/game-design-docs` vs `main`

**Date:** 2026-04-03  
**Scope:** Full documentation and content-contract pass over all paths changed relative to `main` (`git diff main...HEAD`). Includes game-design vision set, decomposition updates (Epic 2 / E2.M1 / E2.M2), `content/` schema + prototype catalog, Cursor rules, and `AGENTS.md`.  
**Base:** `main` at merge-base with this branch; branch tip includes prior commits on `chore/game-design-docs` plus coherence follow-ups.

## Verdict

**Approve with suggestions addressed in-repo for one epic line** — The branch delivers a **coherent hybrid progression story** (gigs + skills, Seams, gig XP vs skill XP, mission reward carve-out) and wires it into **Epic 2** slices and **SkillDef** JSON Schema. **Non-doc** changes (`.vscode/` launch/tasks) are fine but **out of scope** for design coherence; no conflict with docs.

## Summary

Compared to `main`, this branch adds the **`docs/game-design/`** corpus (`overview`, `progression`, `skills`, `gigs`, `README`, `brainstorm/`), extends **Epic 2** and **E2.M1/E2.M2** to match that vision, introduces **`content/schemas/skill-def.schema.json`** with **`allowedXpSourceKinds`**, replaces prototype skills with three **non-combat** rows, and adds the **docs review** agent plus an earlier coherence review file. Cross-links between game-design and decomposition are generally consistent. One **stale sentence** in **Epic 2 Objective** implied combat fed the same **skill-XP** pipeline as gather/craft; that line is **updated** during this review to match **`progression.md`** / **Slice 3**.

## Documentation checked

| Path | Role vs `main` | Match / notes |
|------|------------------|---------------|
| `docs/game-design/overview.md` | New | **Matches** hybrid index; artifact table + **Seams** pointer for `skills.md` |
| `docs/game-design/progression.md` | New | **Matches** vocabulary, mission vs encounter XP, implementation note |
| `docs/game-design/skills.md` | New | **Matches** roster, Seams, decisions log; explicit **`id`** anchors for fragile fragments |
| `docs/game-design/gigs.md` | New | **Matches** gig XP rules, link to **Seams**, combat vs skill boundary |
| `docs/game-design/README.md` | New | **Matches** entry to `overview` / `progression` / brainstorm |
| `docs/game-design/brainstorm/*` | New | **Matches** “ideas only”; links to `skills.md` resolve |
| `docs/decomposition/epics/epic_02_skills_and_progression.md` | Updated | **Matches** after **Objective** paragraph fix (hybrid model explicit); Slice 1/3/DoD align |
| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | Updated | **Matches** schema paths, categories, acceptance criteria |
| `docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md` | Updated | **Matches** `sourceKind` validation, gig vs skill callers |
| `content/schemas/skill-def.schema.json` | Updated | **Matches** game-design categories (`gather`/`process`/`make`/`tech`); no combat `SkillDef` |
| `content/skills/prototype_skills.json` | Updated | **Matches** Slice 1 non-combat trio + `allowedXpSourceKinds` |
| `content/README.md` | Updated | **Matches** pointers to schema + E2 docs |
| `.cursor/rules/docs-review-agent.md` | New | **Matches** repo conventions; `globs: docs/**/*` |
| `AGENTS.md` | Updated | **Matches** Docs review row |
| `docs/reviews/2026-03-31-game-design-skills-coherence.md` | New | Prior focused review; still consistent with branch after later edits |
| `docs/decomposition/epics/epic_03_crafting_economy.md` | Unchanged | **Spot-check:** gather/craft → skill XP via E2.M2 — **no contradiction** |
| `docs/decomposition/modules/client_server_authority.md` | Unchanged | **Nit:** combat path still says “`SkillDef`” in one line — likely **ability/stats** semantics, not non-combat skill catalog; clarify when combat data model is written |
| `neon_sprawl_vision.plan.md` | Updated later | Epic 2 / pillars align with **gigs + skills** hybrid (see current plan text) |
| `.vscode/launch.json`, `.vscode/tasks.json` | New | **N/A** (editor config, not design docs) |

## Blocking issues

None for **using the branch as design + schema guidance**.

## Suggestions

1. ~~**Epic 2 Objective** — “gathering, crafting, and combat all feed one coherent progression model.”~~ **Fixed in this review** — now states **skill** vs **gig** split and mission **skill** rewards.
2. ~~**E2.M1 “Module Breakdown” stub**~~ **Done** — `epic_02` **E2.M1** block matches long-form module + schema links.
3. ~~**CT.M1 / CI:**~~ **Done** — PR gate runs [`scripts/validate_content.py`](../../scripts/validate_content.py) for `content/skills/*.json` vs `skill-def.schema.json`; docs updated ([CT.M1](../decomposition/modules/CT_M1_ContentValidationPipeline.md#ci-prototype), [`internal-content-authoring` Phase 0](../plans/internal-content-authoring.md#phase-0-contracts-validation)).
4. ~~**Decomposition grep:**~~ **Done** — automated via [`scripts/check_decomposition_language.py`](../../scripts/check_decomposition_language.py) in **PR gate**; see [CT.M1 — CI (prototype)](../decomposition/modules/CT_M1_ContentValidationPipeline.md#ci-prototype).

## Nits

- ~~**Epic title vs filename:**~~ **Addressed** — epic file is **`epic_02_skills_and_progression.md`** with H1 **Skills and Progression Framework**; cross-links match.
- ~~**`module_dependency_register.md`:** E2.M1 **Contract Needed**~~ **Addressed** — includes **`allowedXpSourceKinds`**.
- **Two review files:** `2026-03-31-…` vs this `2026-04-03-…` — keep both; this one is **branch-wide vs main**, the other is **skills-focused**.

## Verification

- `git diff main...HEAD --stat` — 18 paths (docs + content + Cursor + VS Code + AGENTS).
- Re-follow `overview` → `progression` / `skills` / `gigs` / decomposition links.
- Validate sample data: `python3 -c "… jsonschema …"` against `skill-def.schema.json` (optional local check).

## Follow-up (applied during this review pass)

- `epic_02_skills_and_progression.md` **Objective**: hybrid **skill** vs **gig** wording + links to `progression.md` and E2.M2.
- `epic_02_skills_and_progression.md` **E2.M1** module stub: non-combat **`SkillDef`**, categories, **`allowedXpSourceKinds`**, links to E2.M1 module + JSON Schema.
- **Content CI:** `.github/workflows/pr-gate.yml` + `scripts/validate_content.py` + `scripts/requirements-content.txt`; CT.M1 / E2.M1 / `content/README` / internal-content-authoring updates.
- **Decomposition language CI:** `scripts/check_decomposition_language.py` + PR gate + CT.M1 / docs-review-agent notes.
- **Epic 2 naming:** Renamed epic doc + **Skills and Progression Framework** (dropped misleading “classless” now that **gigs** are combat roles).
- **module_dependency_register:** E2.M1 **Contract Needed** lists **`allowedXpSourceKinds`**.