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-05-04-documentation-re...

5.4 KiB
Raw Permalink Blame History

Documentation review — game design, decomposition, and plans

Date: 2026-05-04
Scope: Follow-up pass on docs/game-design/ (abilities, progression, overview, zones, death-loss-recovery, economy, gigs, skills seam anchor), docs/decomposition/README.md and docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md, plus recent plans NEO-35-implementation-plan.md and NEO-36-implementation-plan.md. Link spot-checks for epic anchors and schema paths referenced from those docs.
Base: Workspace as of 2026-05-04.

Verdict

Approve with suggestions — hybrid gig/skill vocabulary, Seams, zone graph vs security overlay, and death/loss module wiring remain aligned with the docs-review ground truth. No blocking contradictions found. A few link and polish items improve trust; one item repeats an open suggestion from 2026-04-30-documentation-review.md.

Summary

Sampled vision docs still agree that gig = combat role, skill = non-combat, combat encounters → gig XP vs gather/craft/mission-scripted → skill XP where defined, and economy does not re-gate craft on gig (docs/game-design/economy.md Gig vs skill). docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md matches NEO-35 / NEO-36 plans on registry surface, HTTP projection scope, and allowedXpSourceKinds vs combat. Epic deep links checked from this pass resolve (#epic-4-slice-1, #epic-3-slice-4, #seams-gigs-skills). Residual work is mostly markdown UX and one broken rule link in an older plan.

Documentation checked

Path Assessment
docs/game-design/abilities.md Partially matches — vocabulary and module links align with gigs/skills/items; first-line Seams link still uses placeholder link text anchor in the markdown link label (see Suggestions).
docs/game-design/progression.md Matches — vocabulary and Epic 2 Slice 3 note consistent with E2.M1 and hybrid model.
docs/game-design/overview.md Matches — artifact table, combat pillar stub, decomposition links coherent.
docs/game-design/skills.md (#seams-gigs-skills) Matches — stable HTML id present; Seams remain authoritative boundary reference.
docs/game-design/gigs.md (roster) Matches — nine-gig table consistent with overview “9-gig roster.”
docs/game-design/economy.md Matches — gig vs skill economic identity aligned with progression and Seams.
docs/game-design/zones.md Matches — E4.M1 fiction on same graph as tiers; links to E4.M2–M4 and epic slice anchors valid.
docs/game-design/death-loss-recovery.md Matches — E5.M1 / E3.M4 / E6.M3 / E9.M4 ordering and Seams pointer for chrome vs gear.
docs/game-design/README.md Matches — index paths to overview, progression, decomposition, plans.
docs/decomposition/README.md Matches — epic table, Linear alignment, links to contracts and register.
docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md Matches — NEO-33→36 ordering, schema paths, combat vs skill XP rule matches game-design.
docs/plans/NEO-35-implementation-plan.md Matches — acceptance criteria and E2.M2 forward notes align with E2.M1 module contract.
docs/plans/NEO-36-implementation-plan.md Matches — route/DTO/Bruno/test story aligned with module and interactables pattern.
content/schemas/skill-def.schema.json Matches — exists; referenced consistently from E2.M1 and NEO-35 plan.
docs/plans/NEO-22-implementation-plan.md (spot) Partially matches — content fine; one link targets a non-existent rules file (see Suggestions).
docs/plans/NEON-29-implementation-plan.md (existence) N/A — archival Jira-keyed plan; same caveat as 2026-04-30 review.

Blocking issues

None identified in this pass.

Suggestions

  1. abilities.md Seams link text — Replace [anchor](skills.md#seams-gigs-skills) with readable text (e.g. Seams (gigs ↔ skills)) on the framing line so scanners see intent. Same item as 2026-04-30 review; still open.
  2. NEO-22-implementation-plan.md broken rules link — The bullet referencing NEON-* keys links to ../../.cursor/rules/jira-git-naming.md, which does not exist. Point at linear-git-naming.md (or whichever rule is canonical) and adjust visible label if “Jira” is no longer accurate.
  3. Legacy NEON-29 plan — Still Atlassian-keyed; optional one-line header or docs/plans/README.md note so new contributors do not treat it as active Linear scope (same theme as 2026-04-30 review).
  4. E2_M1_SkillDefinitionRegistry.md plans note — The sentence that plans are added at kickoff is satisfied for NEO-33–36; optional one-line refresh (“plans exist under docs/plans/NEO-33 … NEO-36”) to reduce staleness.

Nits

  • overview.md: Overlap between Artifact index and Planned topics (stubs) remains large; consolidation is optional maintenance savings (same as prior review).

Verification

After edits:

  1. Open docs/game-design/abilities.md and confirm the Seams link reads naturally in the first paragraph.
  2. rg 'jira-git-naming' docs — should return no hits after fixing NEO-22.
  3. rg 'NEON-' docs/plans — confirm each legacy file is either annotated or intentionally unchanged.