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-30-documentation-re...

5.4 KiB
Raw Permalink Blame History

Documentation review — game design + decomposition alignment

Date: 2026-04-30
Scope: Representative pass over docs/game-design/ (index, progression vocabulary, skills roster + seams hooks, abilities, gathering, risk/security), docs/decomposition/README.md, docs/decomposition/modules/documentation_and_implementation_alignment.md, and spot-checked epic/module paths referenced from those docs.
Base: Workspace as of 2026-04-30 (no branch named).

Verdict

Approve with suggestions — vision docs and decomposition cross-links are coherent with the hybrid gig/skill model; no blocking factual errors found in the sampled paths. A few polish items improve discoverability and reader trust.

Summary

Game-design entry points (README.md, overview.md, progression.md, skills.md, abilities.md, gathering.md, risk-security-bands.md) agree on gig = combat role, skill = non-combat, combat encounter → gig XP vs gather/craft → skill XP, and Seams as the gear/craft/deploy boundary. Decomposition README and the implementation alignment table mirror E1.M3 / E1.M4 story landings without contradicting the register’s In Progress rows. Sampled relative links to epics, E4.M1 / E4.M4, E6.M1–M3, E3.M3, and docs/architecture/tech_stack.md resolve. Residual risk is mostly legacy plan naming (NEON-* vs NEO-*) and small markdown UX nits.

Documentation checked

Path Assessment
docs/game-design/README.md Matches — index, correct links to overview, progression, decomposition, plans.
docs/game-design/overview.md Matches — artifact table, hybrid links, Epic 4 slice anchor for risk, architecture link valid.
docs/game-design/progression.md Matches — vocabulary table aligned with skills/gigs; Epic 2 Slice 3 note matches gathering/crafting docs.
docs/game-design/skills.md (incl. roster + <a id="seams-gigs-skills">) Matches — explicit seam anchor; roster and Process/Make boundaries consistent with progression.
docs/game-design/abilities.md Partially matches — content aligns with gigs/skills/items; link text [anchor](skills.md#…) is confusing (see Suggestions).
docs/game-design/gathering.md Matches — skill XP vs gig XP; module links (E3.M1, E1.M3, E3.M3, E4.M2) present on disk.
docs/game-design/risk-security-bands.md Matches — E4.M4 / E6.M1–M2 / server authority framing matches docs-review ground truth.
docs/decomposition/README.md Matches — epic table, tooling CT.* note, links to contracts and register.
docs/decomposition/modules/documentation_and_implementation_alignment.md Matches — E1.M3/E1.M4 narrative consistent with module_dependency_register.md grep for E1.M4.
docs/decomposition/epics/epic_04_world_topology.md (slice anchors) Matches — #epic-4-slice-2 anchor exists for risk doc deep links.
neon_sprawl_vision.plan.md (existence check from doc links) Matches — file at repo root as linked from game-design.
docs/plans/NEON-29-implementation-plan.md N/A (sampled for drift) — legacy Jira NEON-* plan alongside Linear NEO-* plans; see Suggestions.

Blocking issues

None identified in this pass.

Suggestions

  1. abilities.md framing link — Replace the link text anchor with something meaningful (e.g. Seams (gigs ↔ skills)) in the sentence that currently uses [anchor](skills.md#seams-gigs-skills) so readers scanning links see the destination intent. Done. (docs/game-design/abilities.md)
  2. Legacy NEON-* vs NEO-* plans — docs/plans/NEON-29-implementation-plan.md still points at Atlassian; consider a short note in docs/plans/ (only if you add a README.md there) or a header in each legacy file: “superseded by Linear NEO-* / historical” so new contributors do not treat NEON-* as the active tracker. Done. — Banner on NEON-29-implementation-plan.md → NEO-19; docs/plans/README.md.
  3. overview.md “Planned topics (stubs)” — Large overlap with the artifact index above it; optional consolidation would reduce maintenance when adding a new vision file (update one table instead of two). Done. — Stub list trimmed to roadmap-only bullets; index owns shipped files.

Nits

  • documentation_and_implementation_alignment.md — The E1.M3 table cell is very long; fine for a living log, but harder to diff. Optional: split per-ticket bullets under the module page only, keep one line + “see module doc” in the table.
  • TODO block in overview.md (rating / compliance) — Appropriate as vision debt; no change required unless stakeholders want it moved to a single “compliance” stub file.

Verification

After any edits:

  1. Re-open docs/game-design/abilities.md and confirm the Seams link reads naturally. Checked (2026-05-05 follow-up).
  2. rg 'NEON-' docs/plans — decide whether each hit is archival or should gain a one-line deprecation pointer. Checked — only NEON-29-implementation-plan.md; archival banner + docs/plans/README.md.
  3. Spot-check any new docs/game-design/*.md against progression.md vocabulary and skills.md Seams once before filing implementation plans.