From 5bb70efd6ca98fe3c71b04883579c6f160f49da4 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Fri, 17 Apr 2026 20:47:47 -0400 Subject: [PATCH] chore: docs review for E1.M3 documentation pass --- docs/reviews/2026-04-18-e1m3-documentation.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/reviews/2026-04-18-e1m3-documentation.md diff --git a/docs/reviews/2026-04-18-e1m3-documentation.md b/docs/reviews/2026-04-18-e1m3-documentation.md new file mode 100644 index 0000000..b903975 --- /dev/null +++ b/docs/reviews/2026-04-18-e1m3-documentation.md @@ -0,0 +1,49 @@ +# 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). + +## 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. + +## 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) | **Partially matches** — Register **Planned** + “until first … implementation merges” is consistent with policy; readers might still expect **In Progress** now that NEO-23–27 exist (see Suggestions). | +| `docs/decomposition/epics/epic_01_core_player_runtime.md` (Slice 3) | **Partially matches** — Prose matches E1_M3 / backlog; **no explicit HTML `id`** on Slice 3 (see Suggestions vs `epic_03` pattern). | +| `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 ``** (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. + +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. + +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. + +## 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. + +## 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).