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-18-e1m3-documentati...

5.0 KiB
Raw Permalink Blame History

Documentation review — E1.M3 documentation pass

Date: 2026-04-18
Scope: E1.M3 decomposition expansion, prototype backlog, register/alignment touchpoints, and Linear story linkage (NEO-23–NEO-27).
Base: main / repo as of review (no full docs/game-design/** pass). Follow-up: Suggestions in this file are Done. (strikethrough under Suggestions); epic Slice 3 anchor + alignment pointers landed in the same doc pass.

Verdict

Approve with suggestions — Content is coherent, implementation-ready, and consistent with authority + NEO-9 boundary. Address anchor fragility on Epic 1 Slice 3 and optionally tighten alignment-table wording vs Linear issues. Done. (2026-04-18 follow-up commit.)

Summary

The E1.M3 module doc, E1M3-prototype-backlog.md, and supporting register/alignment rows form a clear stack: E1.M1/NEO-9 precursor vs E1.M3 contracts, Slice 3 alignment, and ticketed work in Linear. Cross-links to decomposition siblings, client_server_authority.md, and plans resolve. Remaining gaps are mechanical (GitHub/Cursor heading slug stability for Slice 3; optional explicit mention of NEO-23–27 in the alignment tracking row).

Documentation checked

Path Result
docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md Matches — Purpose, boundary table, contracts, deps/dependents, snapshot, risks, Linear table align with register and NEO-9 out-of-scope.
docs/plans/E1M3-prototype-backlog.md Matches — Story order, AC blocks, dependency graph vs Linear blockers; precursor warning preserved.
docs/decomposition/modules/module_dependency_register.md (E1.M3 note) Matches — Note matches module doc and Planned status.
docs/decomposition/modules/documentation_and_implementation_alignment.md (E1.M3 row) Matches (post–follow-up) — Plans cell now cites Linear NEO-23–NEO-27 + backlog; register Planned rule unchanged.
docs/decomposition/epics/epic_01_core_player_runtime.md (Slice 3) Matches (post–follow-up) — Stable #epic-1-slice-3 anchor added.
docs/decomposition/modules/client_server_authority.md (E1.M3, deferred networking) Matches — Cited behavior matches E1_M3 responsibilities.
docs/plans/NEO-9-implementation-plan.md Matches — Boundary “do not re-scope NEO-9” is respected in E1.M3 + backlog.
docs/decomposition/modules/contracts.md N/A (spot-check) — E1.M3 references kinds/versioning at high level; no conflict.
docs/game-design/gathering.md N/A — Not modified; still points at E1.M3 module; no conflict expected from this pass.

Blocking issues

None — no broken relative paths were found for files targeted by this change set; docs/architecture/tech_stack.md, E9_M1_TelemetryEventSchema.md, and server/README.md targets exist.

Suggestions

  1. Stable anchor for Epic 1 Slice 3 — epic_01_core_player_runtime.md is deep-linked as #slice-3---interaction-targeting-and-ability-input-wiring from E1_M3_InteractionAndTargetingLayer.md and E1M3-prototype-backlog.md. Slug behavior varies by renderer; epic_03_crafting_economy.md already uses explicit <a id="epic-3-slice-…"> (see docs/reviews/2026-04-03-game-design-branch-docs-review.md). Add a similar id="epic-1-slice-3" (or equivalent) before the Slice 3 heading in epic_01_core_player_runtime.md and point links at it to avoid anchor drift. Done. — <a id="epic-1-slice-3"></a> in epic_01_core_player_runtime.md; links updated to #epic-1-slice-3 in E1_M3_InteractionAndTargetingLayer.md and E1M3-prototype-backlog.md.

  2. Alignment table vs Linear — The E1.M3 row says register stays Planned until first implementation merges; that is correct per documentation_and_implementation_alignment.md rules. Consider one clause in the Plans / pointers cell: e.g. “Linear NEO-23–NEO-27 (Todo); register unchanged until code merges” so the table reflects ticketed work without bumping status early. Done. — E1.M3 row Plans cell updated.

  3. E1M3-05 acceptance line — In E1M3-prototype-backlog.md, the checkbox “update … when E1M3-01 merges” could say NEO-23 for parity with Linear keys used elsewhere in the same file. Done.

Nits

  • Summary table Linear cell uses an en-dash between NEO-23 and NEO-27 links; fine for humans; optional to spell out “through” for clarity in prose contexts outside the table. Done. — E1_M3_InteractionAndTargetingLayer.md Summary Linear row now says “through”.

Verification

  • After any anchor fix: open epic_01_core_player_runtime.md from links in E1_M3_InteractionAndTargetingLayer.md and E1M3-prototype-backlog.md and confirm the viewport lands on Slice 3.
  • Grep E1.M3 / NEO-2[3-7] in docs/ after edits to ensure no stale “TBD” story rows remain.
  • When NEO-23 merges: update alignment row + register per the backlog “After this backlog” section (already stated).