# Docs review — game-design branch (`chore/game-design-docs` vs `main`)

**Date:** 2026-04-03  
**Scope:** Documentation and content-contract coherence for paths changed on the branch relative to `main`: `docs/game-design/**`, linked `docs/decomposition/**` updates, `content/schemas` + prototype skills, `.cursor/rules/docs-review-agent.md`, `AGENTS.md`, PR gate scripts, and related cross-links. **Out of scope for verdict:** `.vscode/launch.json` and `.vscode/tasks.json` (editor convenience; no doc contradiction).  
**Base:** `main` (review reflects branch state as of this file).  
**Follow-up:** Suggestions in **Suggestions** below were implemented in commit `6b9f4e8` (same day).

## Verdict

**Approve** — Hybrid **gig vs non-combat skill** vocabulary is consistent across vision docs, **Epic 2** / **E2.M1** / **E2.M2**, and **CI** (`validate_content.py`, `check_decomposition_language.py` both **OK** locally). No blocking factual errors found in sampled cross-links. Prior **polish** suggestions (overview placeholder row, `skills.md` next-pass, `abilities.md` framing) are **done** — see strikethrough list below.

## Summary

The branch ships a **complete spine** for progression design: `progression.md`, `gigs.md`, `skills.md` (Seams), `abilities.md`, `items.md`, `gathering.md`, `crafting.md`, plus `overview.md` index and combat-pillars stub. Decomposition renames **Epic 2** to **Skills and Progression Framework** and aligns **Slice 1** / **Slice 3** with **no combat `SkillDef` XP** from encounters. **Content** enforces **`allowedXpSourceKinds`** and **category** enum (`gather` / `process` / `make` / `tech`) consistent with `skills.md`. The **docs-review-agent** ground truth correctly lists the new vision artifacts.

## Documentation checked

| Path | Assessment |
|------|------------|
| `docs/game-design/overview.md` | **Matches** — index, combat pillars stub, links to all core artifacts. ~~Placeholder artifact row~~ **Removed** in follow-up (`6b9f4e8`). |
| `docs/game-design/progression.md` | **Matches** — vocabulary, Epic 2 Slice 3 note, where-to-read includes items / gathering / crafting. |
| `docs/game-design/skills.md` | **Matches** — roster, production chains, Seams, decisions log, links to Epic 2/3/7 and content schema. ~~“Next pass” without gather/craft anchors~~ **Updated** — now cites `gathering.md`, `crafting.md`, E2.M1 (`6b9f4e8`). |
| `docs/game-design/gigs.md` | **Matches** — roster, hub/sub-gig, XP rules, next-artifact links. |
| `docs/game-design/abilities.md` | **Matches** — gig kit vs skill interaction vs item channel; Epic 2 Slice 3 cite. **N/A** for full combat pillar doc (still stubbed in overview). ~~Framing without gather/craft spine~~ **Updated** — `gathering.md` / `crafting.md` in framing (`6b9f4e8`). |
| `docs/game-design/items.md` | **Matches** — buckets, Seams, Epic 3 module map, open questions, cross-links to gathering/crafting. |
| `docs/game-design/gathering.md` | **Matches** — E3.M1/E4.M2/E2.M2 hooks, skill-not-gig XP, pipeline handoff to `crafting.md`. |
| `docs/game-design/crafting.md` | **Matches** — E3.M2 contracts, bench vs gig, module map including E7.M1 / E6.M4. |
| `docs/game-design/README.md` | **Matches** — pointers to overview + progression + new artifacts. |
| `docs/game-design/brainstorm/*` | **Matches** — relative links to parent `skills.md` / `gigs.md` / `overview.md` resolve. |
| `docs/decomposition/epics/epic_02_skills_and_progression.md` | **Matches** — objective and slices align with `progression.md` (gather/craft → skill XP; combat → gig XP; mission skill rewards explicit). |
| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | **Matches** — schema + `allowedXpSourceKinds` table aligns with `content/schemas/skill-def.schema.json`. |
| `docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md` | **Matches** — rejects skill grants outside allowed sources; combat → gig XP. |
| `docs/decomposition/README.md` | **Matches** — Epic 2 filename updated. |
| `docs/decomposition/modules/module_dependency_register.md` | **Matches** — Epic 2 heading + E2.M1 contract row. |
| `docs/decomposition/modules/CT_M1_ContentValidationPipeline.md` | **Matches** — documents PR gate validation. |
| `content/README.md` + `skill-def.schema.json` + `prototype_skills.json` | **Matches** — categories and XP source kinds align with game-design and E2.M1. |
| `.cursor/rules/docs-review-agent.md` | **Matches** — hybrid ground truth includes `gathering.md` and `crafting.md`. |
| `AGENTS.md` | **Matches** — docs-review agent row present. |
| `README.md` (repo root) | **Matches** — gigs + skills product line; consistent with hybrid docs. |
| `neon_sprawl_vision.plan.md` | **Matches** (spot-check via grep) — Epic 2 naming consistent with branch. |

## Blocking issues

None identified.

## Suggestions

1. ~~**`docs/game-design/overview.md`** — Remove or shrink the `*(add rows as files land)*` artifact row once you treat the core economy/combat vision set as “indexed.”~~ **Done** — placeholder row removed (`6b9f4e8`).
2. ~~**`docs/game-design/skills.md`** — Under **Cross-cutting notes**, refresh **Next pass** to reference **`gathering.md`** and **`crafting.md`** as the written anchors for the gather/craft legs of the prototype trio (still **TBD** which three `SkillDef` ids ship first in data).~~ **Done** — next-pass bullet cites `gathering.md`, `crafting.md`, and E2.M1 slice freeze (`6b9f4e8`).
3. ~~**`docs/game-design/abilities.md`** (optional) — In the opening **Framing** paragraph, add one line pointing to **`gathering.md`** / **`crafting.md`** so combat-adjacent readers find the economy spine without going through `items.md` only.~~ **Done** — **Gather → craft economy spine** line in framing (`6b9f4e8`).

## Nits

- ~~Epic 3 slice references in `gathering.md` / `crafting.md` use *italic* slice titles next to the epic link rather than `#` anchors—**intentionally robust** vs GitHub slug drift; keep as-is unless you add explicit HTML ids in the epic doc.~~ **Done** — `epic_03_crafting_economy.md` now has `<a id="epic-3-slice-2"></a>` / `<a id="epic-3-slice-3"></a>`; `gathering.md` / `crafting.md` deep-link with stable anchors.
- `skills.md` **Next artifacts** lists **gigs** first — **intentional** (folder reading order); no change.

## Verification

- Re-run locally: `pip install -r scripts/requirements-content.txt && python scripts/validate_content.py && python scripts/check_decomposition_language.py`
- If **`pip install`** fails with **PEP 668** (externally managed environment), use a venv (e.g. `python3 -m venv .venv-content`, then `.venv-content/bin/pip install -r scripts/requirements-content.txt` — `.venv-content/` is gitignored) or rely on the **PR gate** workflow for the same checks.
- Before merge: grep for **`epic_02_classless_progression`** (should be **zero**); quick click-test of `docs/game-design/overview.md` links in the GitHub preview for the PR.
