# Final branch documentation review

**Date:** 2026-04-03  
**Scope:** Full doc + content contract pass for branch **`chore/game-design-docs`** vs **`main`** (game-design vision set, Epic 2 rename and module updates, `content/` skill schema + CI, `docs-review-agent`, PR gate, root README, `.vscode` debug/tasks).  
**Base:** `main` (diff as of review); HEAD sample `0dea48e` on `chore/game-design-docs` (verify at merge time).

## Verdict

**Approve with suggestions** — Vision and decomposition align on the hybrid **gig vs non-combat skill** model; `SkillDef` schema, prototype catalog, and CI checks are consistent with **E2.M1** / **E2.M2** module text. The **E2.M2** bullet **Note** in **`epic_02_skills_and_progression.md`** was corrected during this review so it no longer implies **E5.M1** calls **E2.M2**.

## Summary

The branch tightens the **skills** track around **`allowedXpSourceKinds`**, four **`SkillCategory`** values, and explicit rejection of **combat encounter → skill XP**. Game-design docs (`progression`, `gathering`, `crafting`, `abilities`, `gigs`, `skills`) and **`epic_02_skills_and_progression.md`** agree with **E2.M1** / **E2.M2**. **`zones.md`** and cross-links sit correctly beside **`risk-security-bands.md`** on the **E4.M1** graph. **`scripts/validate_content.py`** and **`scripts/check_decomposition_language.py`** both pass locally. **`neon_sprawl_vision.plan.md`** **E2.M2** **grant channel policy** was added after this review (**53fb1d6**).

## Documentation checked

| Path | Result | Notes |
|------|--------|--------|
| `docs/game-design/overview.md` | **Matches** | Artifact index + planned topics coherent; combat stub points to Epic 5 / abilities / items |
| `docs/game-design/progression.md` | **Matches** | Epic 2 Slice 3 = gather/craft → skill XP, combat → gig XP, mission rewards explicit |
| `docs/game-design/skills.md` | **Matches** | Seams anchor `#seams-gigs-skills` present; categories align with schema enum |
| `docs/game-design/gigs.md` | **Matches** | Epic 2 / Epic 5 anchors; PvP open indefinite called out |
| `docs/game-design/gathering.md`, `crafting.md`, `abilities.md` | **Matches** | Epic 2 links use `epic_02_skills_and_progression.md` |
| `docs/game-design/zones.md` | **Matches** | Same graph as tiers; E4.M1 / E7.M4 map |
| `docs/game-design/risk-security-bands.md` | **Matches** | Points to `zones.md` for place fiction |
| `docs/decomposition/epics/epic_02_skills_and_progression.md` | **Matches** | Objective + Slice 1/3/DoD correct; **E2.M2** **Note** updated: E3 callers vs E5 gig path (same session as this review) |
| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | **Matches** | Schema table, `allowedXpSourceKinds`, CI pointer |
| `docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md` | **Matches** | `sourceKind` validation; E5.M1 → gig XP |
| `docs/decomposition/modules/E2_M3_*.md`, `E2_M4_*.md` | **Matches** | Epic link updated |
| `docs/decomposition/README.md` | **Matches** | Epic 2 row → new filename |
| `docs/decomposition/modules/CT_M1_ContentValidationPipeline.md` | **Matches** | PR gate + scripts described |
| `neon_sprawl_vision.plan.md` | **Matches** | Epic 2 title, E2.M1, E2.M2 **grant channel policy** bullet (**53fb1d6**) |
| `content/schemas/skill-def.schema.json` | **Matches** | Required fields + enum align with **E2.M1** |
| `content/skills/prototype_skills.json` | **Matches** | Three rows, distinct categories |
| `content/README.md` | **Matches** | Local validate instructions |
| `.cursor/rules/docs-review-agent.md` | **Matches** | Hybrid ground truth includes `zones.md` |
| `AGENTS.md` | **Matches** | Docs review agent row |
| `README.md` (root) | **Matches** | Gigs + skills one-liner |
| `.github/workflows/pr-gate.yml` | **N/A** (workflow) | Validates content + decomposition language |
| `.vscode/launch.json`, `tasks.json` | **N/A** | Launch targets `server/NeonSprawl.Server.Tests` + `NeonSprawl.sln` at repo root — paths exist |

## Blocking issues

None for **merge** from a **documentation correctness** standpoint.

## Suggestions

1. ~~**`neon_sprawl_vision.plan.md`** — Optional one-line under **E2.M2**: reject **XP** grants whose **`sourceKind`** is not in the target skill’s **`allowedXpSourceKinds`** (mirrors module + schema descriptions).~~ **Done** (**53fb1d6**): **Grant channel policy** bullet under **E2.M2**.

## Nits

- **`docs/reviews/2026-04-03-game-design-branch-docs-review.md`** verification bullet still mentions grepping **`epic_02_classless_progression`**; repo docs no longer use that path (harmless historical note).
- **`.vscode/launch.json`** retains default .NET template comments — fine for a first drop; team may want a Neon Sprawl–specific label later.

## Verification

```bash
pip install -r scripts/requirements-content.txt
python scripts/validate_content.py
python scripts/check_decomposition_language.py
rg 'epic_02_classless_progression' docs/ content/ --glob '*.md'
```

Expect **no** hits under `docs/` (except optional old **reviews** text). Spot-check **GitHub** rendering for `docs/game-design/overview.md` and `epic_02_skills_and_progression.md` links after merge.