neon-sprawl/docs/reviews/2026-04-03-final-branch-docs-review.md

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. Optional follow-up: one line under E2.M2 in neon_sprawl_vision.plan.md for sourceKind / allowedXpSourceKinds parity with modules.

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	Partially matches	Epic 2 title and E2.M1 note OK; E2.M2 could mention grant channel validation for parity with modules
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).

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

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.