neon-sprawl/docs/reviews/2026-04-30-documentation-review.md

# 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`](../plans/NEON-29-implementation-plan.md) → [NEO-19](../plans/NEO-19-implementation-plan.md); [`docs/plans/README.md`](../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`](../plans/NEON-29-implementation-plan.md); archival banner + [`docs/plans/README.md`](../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.