From f67bae79d8657e5cef8f415676928154004ba41b Mon Sep 17 00:00:00 2001 From: VinPropane Date: Mon, 4 May 2026 21:06:51 -0400 Subject: [PATCH] chore: add 2026-05-04 documentation review --- .../2026-05-04-documentation-review.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/reviews/2026-05-04-documentation-review.md diff --git a/docs/reviews/2026-05-04-documentation-review.md b/docs/reviews/2026-05-04-documentation-review.md new file mode 100644 index 0000000..40d6207 --- /dev/null +++ b/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.