chore: add 2026-05-04 documentation review

docs/reviews/2026-05-04-documentation-review.md

@@ -0,0 +1,57 @@
+# Documentation review — game design, decomposition, and plans
+
+**Date:** 2026-05-04  
+**Scope:** Follow-up pass on `docs/game-design/` (abilities, progression, overview, zones, death-loss-recovery, economy, gigs, skills seam anchor), `docs/decomposition/README.md` and `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md`, plus recent plans `NEO-35-implementation-plan.md` and `NEO-36-implementation-plan.md`. Link spot-checks for epic anchors and schema paths referenced from those docs.  
+**Base:** Workspace as of 2026-05-04.
+
+## Verdict
+
+**Approve with suggestions** — hybrid gig/skill vocabulary, Seams, zone graph vs security overlay, and death/loss module wiring remain aligned with the docs-review ground truth. No blocking contradictions found. A few link and polish items improve trust; one item repeats an open suggestion from [2026-04-30-documentation-review.md](2026-04-30-documentation-review.md).
+
+## Summary
+
+Sampled vision docs still agree that **gig** = combat role, **skill** = non-combat, **combat encounters → gig XP** vs **gather/craft/mission-scripted → skill XP** where defined, and **economy** does not re-gate **craft** on **gig** (`docs/game-design/economy.md` **Gig vs skill**). `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` matches **NEO-35** / **NEO-36** plans on registry surface, HTTP projection scope, and `allowedXpSourceKinds` vs combat. Epic deep links checked from this pass resolve (`#epic-4-slice-1`, `#epic-3-slice-4`, `#seams-gigs-skills`). Residual work is mostly **markdown UX** and **one broken rule link** in an older plan.
+
+## Documentation checked
+
+| Path | Assessment |
+|------|------------|
+| `docs/game-design/abilities.md` | **Partially matches** — vocabulary and module links align with gigs/skills/items; first-line Seams link still uses placeholder link text `anchor` in the markdown link label (see Suggestions). |
+| `docs/game-design/progression.md` | **Matches** — vocabulary and Epic 2 Slice 3 note consistent with E2.M1 and hybrid model. |
+| `docs/game-design/overview.md` | **Matches** — artifact table, combat pillar stub, decomposition links coherent. |
+| `docs/game-design/skills.md` (`#seams-gigs-skills`) | **Matches** — stable HTML id present; Seams remain authoritative boundary reference. |
+| `docs/game-design/gigs.md` (roster) | **Matches** — nine-gig table consistent with overview “9-gig roster.” |
+| `docs/game-design/economy.md` | **Matches** — gig vs skill economic identity aligned with progression and Seams. |
+| `docs/game-design/zones.md` | **Matches** — E4.M1 fiction on same graph as tiers; links to E4.M2–M4 and epic slice anchors valid. |
+| `docs/game-design/death-loss-recovery.md` | **Matches** — E5.M1 / E3.M4 / E6.M3 / E9.M4 ordering and Seams pointer for chrome vs gear. |
+| `docs/game-design/README.md` | **Matches** — index paths to overview, progression, decomposition, plans. |
+| `docs/decomposition/README.md` | **Matches** — epic table, Linear alignment, links to contracts and register. |
+| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | **Matches** — NEO-33→36 ordering, schema paths, combat vs skill XP rule matches game-design. |
+| `docs/plans/NEO-35-implementation-plan.md` | **Matches** — acceptance criteria and E2.M2 forward notes align with E2.M1 module contract. |
+| `docs/plans/NEO-36-implementation-plan.md` | **Matches** — route/DTO/Bruno/test story aligned with module and interactables pattern. |
+| `content/schemas/skill-def.schema.json` | **Matches** — exists; referenced consistently from E2.M1 and NEO-35 plan. |
+| `docs/plans/NEO-22-implementation-plan.md` (spot) | **Partially matches** — content fine; one link targets a non-existent rules file (see Suggestions). |
+| `docs/plans/NEON-29-implementation-plan.md` (existence) | **N/A** — archival Jira-keyed plan; same caveat as 2026-04-30 review. |
+
+## Blocking issues
+
+None identified in this pass.
+
+## Suggestions
+
+1. **`abilities.md` Seams link text** — Replace `[anchor](skills.md#seams-gigs-skills)` with readable text (e.g. `Seams (gigs ↔ skills)`) on the framing line so scanners see intent. Same item as 2026-04-30 review; still open.
+2. **`NEO-22-implementation-plan.md` broken rules link** — The bullet referencing **NEON-*** keys links to `../../.cursor/rules/jira-git-naming.md`, which does not exist. Point at [`linear-git-naming.md`](../../.cursor/rules/linear-git-naming.md) (or whichever rule is canonical) and adjust visible label if “Jira” is no longer accurate.
+3. **Legacy `NEON-29` plan** — Still Atlassian-keyed; optional one-line header or `docs/plans/README.md` note so new contributors do not treat it as active Linear scope (same theme as 2026-04-30 review).
+4. **`E2_M1_SkillDefinitionRegistry.md` plans note** — The sentence that plans are added at kickoff is satisfied for NEO-33–36; optional one-line refresh (“plans exist under `docs/plans/NEO-33` … `NEO-36`”) to reduce staleness.
+
+## Nits
+
+- **`overview.md`**: Overlap between **Artifact index** and **Planned topics (stubs)** remains large; consolidation is optional maintenance savings (same as prior review).
+
+## Verification
+
+After edits:
+
+1. Open `docs/game-design/abilities.md` and confirm the Seams link reads naturally in the first paragraph.
+2. `rg 'jira-git-naming' docs` — should return no hits after fixing NEO-22.
+3. `rg 'NEON-' docs/plans` — confirm each legacy file is either annotated or intentionally unchanged.