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-branch-chore-gam...

6.7 KiB
Raw Blame History

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 for content/skills/*.json vs skill-def.schema.json; docs updated (CT.M1, internal-content-authoring Phase 0).
  4. Decomposition grep: Done — automated via scripts/check_decomposition_language.py in PR gate; see CT.M1 — 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.