neon-sprawl/docs/reviews/2026-03-31-game-design-skills-coherence.md

Game design docs coherence review — skills + links

Date: 2026-03-31
Scope: docs/game-design/skills.md and connected game-design + decomposition references (no PR diff; full-document pass).
Base: docs/game-design/ vision set as of this date.

Verdict

Approve for vision / pre-implementation guidance — the hybrid gig + skill model, Seams, and v0 skill roster are internally coherent and usable to steer E2/E3/E5 work. Epic 2 Slice 1 (non-combat SkillDef trio) and Slice 3 (encounters → gig XP, gather/craft → skill XP, mission rewards may grant skill XP) are aligned with game-design.

Summary

skills.md is the strongest single artifact: clear vocabulary, domains vs categories, roster tables, production chains, Seams (combat gear, cybernetics, crafting, deployables, utility Rigging), decisions log, and deferred late-stage tuning (failure XP, respec, synergy). Linked docs (progression.md, overview.md, gigs.md, README.md) and Epic 2 slices 1 and 3 align with skills = non-combat, combat encounters = gig XP only (mission reward skill XP stays a separate payout).

Remaining gaps are expected for vision docs: stable skill IDs, per-recipe data tags, and gig ↔ item deploy matrices are not yet specified — call those out for implementation plans rather than blocking the design read-through.

Documentation checked

Path	Match vs skills.md / hybrid model
docs/game-design/skills.md	N/A (source reviewed)
docs/game-design/progression.md	Matches after Medtech fab naming alignment
docs/game-design/overview.md	Matches — index, rating vision, artifact table
docs/game-design/gigs.md	Matches — sub-gig Combat gear bullet now links to skills.md Seams
docs/game-design/README.md	Matches
docs/decomposition/epics/epic_02_skills_and_progression.md	Matches — Slice 3: gather/craft → E2.M2 skill XP; encounters → gig XP; mission rewards may grant skill XP (no combat SkillDef from encounters)
docs/decomposition/epics/epic_03_crafting_economy.md	Not re-read in full — skills.md “Where skills meet” cites E3; no contradiction spotted from skills side
docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md	Matches — schema + allowedXpSourceKinds, categories gather/process/make/tech, Slice 1 acceptance criteria

Blocking issues

None for using the docs as design guidance. (No incorrect security or authority claims found.)

Suggestions

1. gigs.md — Combat gear: Done — sub-gig section links to skills.md#seams-gigs-skills.
2. epic_02 — Slice 3: Done — encounters → gig XP only; gather/craft → E2.M2 skill XP; mission rewards may grant skill XP explicitly (progression.md, epic_02 Slice 3).
3. overview.md artifact table: Done — skills.md row notes Hardshell / Softshell / Edgesmith / Rigging equip vs combat-deploy + link to Seams.
4. Stable IDs + XP sources: Done — content/schemas/skill-def.schema.json, content/skills/prototype_skills.json, E2.M1 + E2.M2; skills.md links.

Nits

• Categories table (Tech): Addressed — row now includes exploit dev and crypto & identity.
• Anchor fragility: Addressed — skills.md uses explicit <a id="…"> for Skill roster, Open questions (skills-only), and Decisions log (same pattern as Seams).

Verification

• Manually re-follow links from skills.md intro → progression.md, gigs.md, overview.md, brainstorm/hack-bodyguard-missions.md, E2/E3/E7 epics.
• After gig data model work: grep docs/decomposition for “combat skill” / “class” and align with hybrid vocabulary.

Follow-up (applied in this review pass)

• progression.md: medic fab → Medtech fab (consistent with roster).
• epic_02_skills_and_progression.md Slice 1 scope: non-combat trio aligned with skills.md / gigs hybrid (see commit).
• skills.md: Tech category row aligned with full Tech roster (exploit dev, crypto & identity).
• gigs.md: sub-gig Combat gear → link to skills.md Seams.
• AGENTS.md: Docs review agent row → .cursor/rules/docs-review-agent.md.
• Combat XP rule: progression.md + epic_02 Slice 3 — encounters → gig XP only (no combat SkillDef); mission reward skill XP is separate.
• overview.md: artifact table skills.md row — Hardshell / Softshell / Edgesmith / Rigging + Seams link.
• SkillDef schema: content/schemas/skill-def.schema.json + prototype_skills.json; E2.M1 / E2.M2 docs for IDs and allowedXpSourceKinds.