61 lines
5.1 KiB
Markdown
61 lines
5.1 KiB
Markdown
# 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/schemas/skill-def.schema.json), [`content/skills/prototype_skills.json`](../../content/skills/prototype_skills.json), [E2.M1](../decomposition/modules/E2_M1_SkillDefinitionRegistry.md) + [E2.M2](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md); [`skills.md`](../game-design/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`**.
|