don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
neon-sprawl/docs/reviews/2026-04-03-game-design-bran...

6.8 KiB
Raw Blame History

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.