From f9de62b5632097bf104672fbec178f58250f5b9b Mon Sep 17 00:00:00 2001 From: VinPropane Date: Fri, 3 Apr 2026 21:23:36 -0400 Subject: [PATCH] chore: branch-wide docs review vs main + Epic 2 objective hybrid wording - Save docs/reviews/2026-04-03-branch-chore-game-design-docs-vs-main.md - Epic 2 Objective: skill vs gig progression; link progression + E2.M2 --- .../epics/epic_02_classless_progression.md | 2 +- ...3-branch-chore-game-design-docs-vs-main.md | 66 +++++++++++++++++++ 2 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 docs/reviews/2026-04-03-branch-chore-game-design-docs-vs-main.md diff --git a/docs/decomposition/epics/epic_02_classless_progression.md b/docs/decomposition/epics/epic_02_classless_progression.md index 4248073..fd11e83 100644 --- a/docs/decomposition/epics/epic_02_classless_progression.md +++ b/docs/decomposition/epics/epic_02_classless_progression.md @@ -12,7 +12,7 @@ ## Objective -Provide a data-driven classless progression layer: skill definitions, XP awards, level curves, and eventually mastery/perk and pacing controls so gathering, crafting, and combat all feed one coherent progression model. +Provide a data-driven **classless non-combat skill** layer: `SkillDef` registry, **skill** XP awards, level curves, and eventually mastery/perk and pacing controls. **Gathering** and **crafting** feed **skill** progression via [E2.M2](../modules/E2_M2_XpAwardAndLevelEngine.md); **combat encounters** feed **gig** progression (not `SkillDef` XP)—see [`docs/game-design/progression.md`](../../game-design/progression.md). **Mission rewards** may still grant **skill** XP when scripted. ## Module Breakdown diff --git a/docs/reviews/2026-04-03-branch-chore-game-design-docs-vs-main.md b/docs/reviews/2026-04-03-branch-chore-game-design-docs-vs-main.md new file mode 100644 index 0000000..26f6710 --- /dev/null +++ b/docs/reviews/2026-04-03-branch-chore-game-design-docs-vs-main.md @@ -0,0 +1,66 @@ +# Branch review — `chore/game-design-docs` vs `main` + +**Date:** 2026-04-03 +**Scope:** Full documentation and content-contract pass over all paths changed relative to `main` (`git diff main...HEAD`). Includes game-design vision set, decomposition updates (Epic 2 / E2.M1 / E2.M2), `content/` schema + prototype catalog, Cursor rules, and `AGENTS.md`. +**Base:** `main` at merge-base with this branch; branch tip includes prior commits on `chore/game-design-docs` plus coherence follow-ups. + +## Verdict + +**Approve with suggestions addressed in-repo for one epic line** — The branch delivers a **coherent hybrid progression story** (gigs + skills, Seams, gig XP vs skill XP, mission reward carve-out) and wires it into **Epic 2** slices and **SkillDef** JSON Schema. **Non-doc** changes (`.vscode/` launch/tasks) are fine but **out of scope** for design coherence; no conflict with docs. + +## Summary + +Compared to `main`, this branch adds the **`docs/game-design/`** corpus (`overview`, `progression`, `skills`, `gigs`, `README`, `brainstorm/`), extends **Epic 2** and **E2.M1/E2.M2** to match that vision, introduces **`content/schemas/skill-def.schema.json`** with **`allowedXpSourceKinds`**, replaces prototype skills with three **non-combat** rows, and adds the **docs review** agent plus an earlier coherence review file. Cross-links between game-design and decomposition are generally consistent. One **stale sentence** in **Epic 2 Objective** implied combat fed the same “classless skill” model as gather/craft; that line is **updated** during this review to match **`progression.md`** / **Slice 3**. + +## Documentation checked + +| Path | Role vs `main` | Match / notes | +|------|------------------|---------------| +| `docs/game-design/overview.md` | New | **Matches** hybrid index; artifact table + **Seams** pointer for `skills.md` | +| `docs/game-design/progression.md` | New | **Matches** vocabulary, mission vs encounter XP, implementation note | +| `docs/game-design/skills.md` | New | **Matches** roster, Seams, decisions log; explicit **`id`** anchors for fragile fragments | +| `docs/game-design/gigs.md` | New | **Matches** gig XP rules, link to **Seams**, combat vs skill boundary | +| `docs/game-design/README.md` | New | **Matches** entry to `overview` / `progression` / brainstorm | +| `docs/game-design/brainstorm/*` | New | **Matches** “ideas only”; links to `skills.md` resolve | +| `docs/decomposition/epics/epic_02_classless_progression.md` | Updated | **Matches** after **Objective** paragraph fix (hybrid model explicit); Slice 1/3/DoD align | +| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | Updated | **Matches** schema paths, categories, acceptance criteria | +| `docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md` | Updated | **Matches** `sourceKind` validation, gig vs skill callers | +| `content/schemas/skill-def.schema.json` | Updated | **Matches** game-design categories (`gather`/`process`/`make`/`tech`); no combat `SkillDef` | +| `content/skills/prototype_skills.json` | Updated | **Matches** Slice 1 non-combat trio + `allowedXpSourceKinds` | +| `content/README.md` | Updated | **Matches** pointers to schema + E2 docs | +| `.cursor/rules/docs-review-agent.md` | New | **Matches** repo conventions; `globs: docs/**/*` | +| `AGENTS.md` | Updated | **Matches** Docs review row | +| `docs/reviews/2026-03-31-game-design-skills-coherence.md` | New | Prior focused review; still consistent with branch after later edits | +| `docs/decomposition/epics/epic_03_crafting_economy.md` | Unchanged | **Spot-check:** gather/craft → skill XP via E2.M2 — **no contradiction** | +| `docs/decomposition/modules/client_server_authority.md` | Unchanged | **Nit:** combat path still says “`SkillDef`” in one line — likely **ability/stats** semantics, not non-combat skill catalog; clarify when combat data model is written | +| `neon_sprawl_vision.plan.md` | Unchanged | **Spot-check:** Epic 2 bullets generic — **no direct conflict** with hybrid detail in epics | +| `.vscode/launch.json`, `.vscode/tasks.json` | New | **N/A** (editor config, not design docs) | + +## Blocking issues + +None for **using the branch as design + schema guidance**. + +## Suggestions + +1. ~~**Epic 2 Objective** — “gathering, crafting, and combat all feed one coherent progression model.”~~ **Fixed in this review** — now states **skill** vs **gig** split and mission **skill** rewards. +2. **E2.M1 “Module Breakdown” stub** (short `Responsibility` under `### E2.M1` in `epic_02`): still one generic line; optional align to “non-combat `SkillDef`” to mirror the long-form module doc. +3. **CT.M1 / CI:** Schema and prototype JSON are documented; **wire validation** when the content pipeline lands (`docs/plans/internal-content-authoring.md` already points at ajv/CLI). +4. **Decomposition grep:** Periodically run `rg "combat skill|one combat skill"` under `docs/decomposition` after gig modules are drafted to catch regressions. + +## Nits + +- **Epic title vs filename:** “Classless Skill and Progression” vs `epic_02_classless_progression.md` — fine; readers use **gigs** for combat naming. +- **`module_dependency_register.md`:** E2.M1 row could list **`allowedXpSourceKinds`** in the contract column when you next touch the register (cosmetic). +- **Two review files:** `2026-03-31-…` vs this `2026-04-03-…` — keep both; this one is **branch-wide vs main**, the other is **skills-focused**. + +## Verification + +- `git diff main...HEAD --stat` — 18 paths (docs + content + Cursor + VS Code + AGENTS). +- Re-follow `overview` → `progression` / `skills` / `gigs` / decomposition links. +- Validate sample data: `python3 -c "… jsonschema …"` against `skill-def.schema.json` (optional local check). + +## Follow-up (applied during this review pass) + +- `epic_02_classless_progression.md` **Objective**: hybrid **skill** vs **gig** wording + links to `progression.md` and E2.M2. + +**Commit:** User should commit the Epic 2 Objective fix separately or fold into the next push (not committed by the review tool).