50 lines
5.0 KiB
Markdown
50 lines
5.0 KiB
Markdown
# 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).
|