diff --git a/docs/game-design/README.md b/docs/game-design/README.md index 021a26a..624ca0d 100644 --- a/docs/game-design/README.md +++ b/docs/game-design/README.md @@ -8,4 +8,4 @@ Non-implementation notes: **gigs** (combat roles), **skills** (non-combat), **[abilities](abilities.md)** (what players trigger), **[items](items.md)** (loot, craft, equip), **[gathering](gathering.md)** (resource nodes, yields), **[crafting](crafting.md)** (recipes, pipeline), **[economy](economy.md)** (faucets, sinks, trade), **[death-loss-recovery](death-loss-recovery.md)** (stakes, recovery), **[risk-security-bands](risk-security-bands.md)** (tiers, PvP eligibility), **[zones](zones.md)** (place identity), travel/mechanics stubs, and other design artifacts before they are tied to concrete systems or tickets. -Implementation-facing breakdowns stay under [`docs/decomposition/`](../decomposition/README.md) and plans under [`docs/plans/`](../plans/). +Implementation-facing breakdowns stay under [`docs/decomposition/`](../decomposition/README.md) and plans under [`docs/plans/`](../plans/) (see [`docs/plans/README.md`](../plans/README.md) for **NEO-*** vs legacy **`NEON-*`** plan filenames). diff --git a/docs/game-design/abilities.md b/docs/game-design/abilities.md index d5dd18f..50246fa 100644 --- a/docs/game-design/abilities.md +++ b/docs/game-design/abilities.md @@ -2,7 +2,7 @@ Vision for **what the player triggers** in play: combat **kits**, non-combat **skill interactions**, and **item**-carried actions—and how those map to **gigs**, **`SkillDef`**, and **Seams**. This is **not** a full ability list or data schema; it steers combat design, UX, and implementation boundaries. -**Framing:** [progression.md](progression.md) (**gig** vs **skill**). **Combat roles:** [gigs.md](gigs.md). **Gear, craft, consumables:** [skills.md](skills.md) **Seams** ([anchor](skills.md#seams-gigs-skills)). **Item buckets & acquisition:** [items.md](items.md). **Gather → craft economy spine:** [gathering.md](gathering.md), [crafting.md](crafting.md). **Combat pillar pointers:** [overview.md — Combat pillars](overview.md#combat-pillars-vision-stub). +**Framing:** [progression.md](progression.md) (**gig** vs **skill**). **Combat roles:** [gigs.md](gigs.md). **Gear, craft, consumables:** [skills.md](skills.md) — [Seams (gigs ↔ skills)](skills.md#seams-gigs-skills). **Item buckets & acquisition:** [items.md](items.md). **Gather → craft economy spine:** [gathering.md](gathering.md), [crafting.md](crafting.md). **Combat pillar pointers:** [overview.md — Combat pillars](overview.md#combat-pillars-vision-stub). ## Vocabulary diff --git a/docs/game-design/overview.md b/docs/game-design/overview.md index 4a3c71e..0b3582a 100644 --- a/docs/game-design/overview.md +++ b/docs/game-design/overview.md @@ -39,21 +39,14 @@ Neon Sprawl’s design work here starts from **concrete visions** of progression ### Planned topics (stubs) -Link new files here when they exist; remove or rewrite this subsection once the table is populated. +**Shipped vision docs** are listed in the [Artifact index](#artifact-index) above—update that table when a new first-class file lands. -- **Progression** — [progression.md](progression.md): hybrid **gig + skill** overview and vocabulary. **Gigs:** [gigs.md](gigs.md). **Skills** + seams: [skills.md](skills.md). Recruitment channel **deferred**; *professions* stay folded into **skills** + rep unless a future doc defines something separate. -- **Zones** — [zones.md](zones.md): tone, danger, faction/economic **hooks**; **graph** in [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md). -- **Travel & connections** — how places link (gates, costs, downtime, danger en route); complements zone identity. -- **Mechanics** — loops, constraints, what the server vs. client must honor. -- **Items** — [items.md](items.md): categories, rarity philosophy, crafting vs. drops; **Seams** for gig/skill gates. -- **Abilities** — [abilities.md](abilities.md): inputs, timing; combo with items; **gig** vs **skill** gates (see [progression.md](progression.md) vocabulary). **Combat context:** [Combat pillars (vision stub)](#combat-pillars-vision-stub). -- **Gathering & resources** — [gathering.md](gathering.md): nodes, competition, exhaustion, open-world contesting; **skill XP** not **gig** XP. -- **Crafting & recipes** — [crafting.md](crafting.md): depth vs breadth, failure, quality, stations; **skill XP**; [items.md](items.md) for output buckets. -- **Economy** — [economy.md](economy.md): currency, sinks, trade, **E3.M5** / **E8.M3**; **mission** payouts vs **combat** loot ([progression.md](progression.md)). -- **Factions & reputation** — who remembers you, grudges, access gates; **gig** story arcs: [gigs.md](gigs.md), rep + seams: [skills.md](skills.md). -- **Combat pillars** — [Vision stub below](#combat-pillars-vision-stub): PvE vs. PvP stance, readability, time-to-kill, fairness; **items in combat** in [items.md](items.md). -- **Death, loss & recovery** — [death-loss-recovery.md](death-loss-recovery.md): stakes, **E3.M4**/**E6.M3**, recovery UX. -- **Risk & security bands** — [risk-security-bands.md](risk-security-bands.md): **tiers**, **PvP** opt-in, **theft**/gather **contest** hooks; **place** **fiction**: [zones.md](zones.md). +The bullets below are **roadmap / not-yet-first-class-file** topics (or pointers into existing docs for cross-cutting angles): + +- **Travel & connections** — how places link (gates, costs, downtime, danger en route); complements [zones.md](zones.md) and [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md). +- **Mechanics** — loops, constraints, what the server vs. client must honor (no dedicated vision file yet). +- **Factions & reputation** — who remembers you, grudges, access gates; ties [gigs.md](gigs.md), [skills.md](skills.md), future faction doc. +- **Combat pillars** — [Vision stub below](#combat-pillars-vision-stub); **items in combat** in [items.md](items.md). - **Social play** — squad scale, corps, trust, betrayal affordances, async cooperation. - **Encounters & enemy roles** — archetypes, what a fight teaches, variety without noise. **Skill + gig split runs:** [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md). - **Onboarding** — first session hook, clarity vs. mystery, how much systems the new player sees. @@ -79,5 +72,5 @@ Combat is still missing a **single** pillar doc. Until then, use this table for | Area | Location | |------|----------| | Module / epic breakdown | [`docs/decomposition/`](../decomposition/README.md) | -| Implementation plans | [`docs/plans/`](../plans/) | +| Implementation plans | [`docs/plans/`](../plans/) — [README (NEO vs NEON filenames)](../plans/README.md) | | Architecture | [`docs/architecture/`](../architecture/tech_stack.md) | diff --git a/docs/plans/NEON-29-implementation-plan.md b/docs/plans/NEON-29-implementation-plan.md index 68c200d..99b9691 100644 --- a/docs/plans/NEON-29-implementation-plan.md +++ b/docs/plans/NEON-29-implementation-plan.md @@ -1,5 +1,7 @@ # NEON-29 Implementation Plan — Expand prototype client district for camera/nav stress QA +> **Historical — Jira archive.** This file preserved the **Atlassian / NEON-*** story record. **Active tracker:** Linear **NEO-***, team Neon Sprawl. The same work is described for implementation kickoff in [**NEO-19** — implementation plan](NEO-19-implementation-plan.md) (same title and scope). Do not open new work against **NEON-*** keys. + ## Story reference - **Key:** [NEON-29](https://neon-sprawl.atlassian.net/browse/NEON-29) diff --git a/docs/plans/README.md b/docs/plans/README.md new file mode 100644 index 0000000..344e9ee --- /dev/null +++ b/docs/plans/README.md @@ -0,0 +1,15 @@ +# Implementation plans (`docs/plans/`) + +Story-level implementation plans live here, keyed by **Linear issue id** (`NEO-*`) when the work is tracked in Linear (team **NEO**, Neon Sprawl). + +## Legacy `NEON-*` filenames + +A small number of files keep the historical **Jira / Atlassian `NEON-*`** key in the **filename** only. They are **not** the active issue tracker for new work. + +- Each such file includes a short **Historical** banner at the top pointing at the matching **`NEO-*`** plan (same scope) where kickoff and commits should align. +- Prefer opening and linking **`NEO-*`** issues and plans for new contributors. + +## Conventions + +- New or moved plans: `docs/plans/{LINEAR_KEY}-implementation-plan.md` (see [story kickoff](../../.cursor/rules/story-kickoff.md)). +- Cross-links from decomposition and game-design docs should use **`NEO-*`** URLs (Linear) for current engineering work. diff --git a/docs/reviews/2026-04-30-documentation-review.md b/docs/reviews/2026-04-30-documentation-review.md new file mode 100644 index 0000000..2fae45d --- /dev/null +++ b/docs/reviews/2026-04-30-documentation-review.md @@ -0,0 +1,53 @@ +# Documentation review — game design + decomposition alignment + +**Date:** 2026-04-30 +**Scope:** Representative pass over `docs/game-design/` (index, progression vocabulary, skills roster + seams hooks, abilities, gathering, risk/security), `docs/decomposition/README.md`, `docs/decomposition/modules/documentation_and_implementation_alignment.md`, and spot-checked epic/module paths referenced from those docs. +**Base:** Workspace as of 2026-04-30 (no branch named). + +## Verdict + +**Approve with suggestions** — vision docs and decomposition cross-links are coherent with the hybrid gig/skill model; no blocking factual errors found in the sampled paths. A few polish items improve discoverability and reader trust. + +## Summary + +Game-design entry points (`README.md`, `overview.md`, `progression.md`, `skills.md`, `abilities.md`, `gathering.md`, `risk-security-bands.md`) agree on **gig** = combat role, **skill** = non-combat, **combat encounter → gig XP** vs **gather/craft → skill XP**, and **Seams** as the gear/craft/deploy boundary. Decomposition README and the implementation alignment table mirror **E1.M3** / **E1.M4** story landings without contradicting the register’s **In Progress** rows. Sampled relative links to epics, **E4.M1** / **E4.M4**, **E6.M1**–**M3**, **E3.M3**, and `docs/architecture/tech_stack.md` resolve. Residual risk is mostly **legacy plan naming** (**NEON-*** vs **NEO-***) and small markdown UX nits. + +## Documentation checked + +| Path | Assessment | +|------|------------| +| `docs/game-design/README.md` | **Matches** — index, correct links to overview, progression, decomposition, plans. | +| `docs/game-design/overview.md` | **Matches** — artifact table, hybrid links, Epic 4 slice anchor for risk, architecture link valid. | +| `docs/game-design/progression.md` | **Matches** — vocabulary table aligned with skills/gigs; Epic 2 Slice 3 note matches gathering/crafting docs. | +| `docs/game-design/skills.md` (incl. roster + ``) | **Matches** — explicit seam anchor; roster and Process/Make boundaries consistent with progression. | +| `docs/game-design/abilities.md` | **Partially matches** — content aligns with gigs/skills/items; link text `[anchor](skills.md#…)` is confusing (see Suggestions). | +| `docs/game-design/gathering.md` | **Matches** — skill XP vs gig XP; module links (E3.M1, E1.M3, E3.M3, E4.M2) present on disk. | +| `docs/game-design/risk-security-bands.md` | **Matches** — E4.M4 / E6.M1–M2 / server authority framing matches docs-review ground truth. | +| `docs/decomposition/README.md` | **Matches** — epic table, tooling CT.* note, links to contracts and register. | +| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | **Matches** — E1.M3/E1.M4 narrative consistent with `module_dependency_register.md` grep for E1.M4. | +| `docs/decomposition/epics/epic_04_world_topology.md` (slice anchors) | **Matches** — `#epic-4-slice-2` anchor exists for risk doc deep links. | +| `neon_sprawl_vision.plan.md` (existence check from doc links) | **Matches** — file at repo root as linked from game-design. | +| `docs/plans/NEON-29-implementation-plan.md` | **N/A** (sampled for drift) — legacy Jira **NEON-*** plan alongside Linear **NEO-*** plans; see Suggestions. | + +## Blocking issues + +None identified in this pass. + +## Suggestions + +1. ~~**`abilities.md` framing link** — Replace the link text `anchor` with something meaningful (e.g. `Seams (gigs ↔ skills)`) in the sentence that currently uses `[anchor](skills.md#seams-gigs-skills)` so readers scanning links see the destination intent.~~ **Done.** (`docs/game-design/abilities.md`) +2. ~~**Legacy `NEON-*` vs `NEO-*` plans** — `docs/plans/NEON-29-implementation-plan.md` still points at Atlassian; consider a short note in `docs/plans/` (only if you add a `README.md` there) or a header in each legacy file: “superseded by Linear NEO-* / historical” so new contributors do not treat **NEON-*** as the active tracker.~~ **Done.** — Banner on [`NEON-29-implementation-plan.md`](../plans/NEON-29-implementation-plan.md) → [NEO-19](../plans/NEO-19-implementation-plan.md); [`docs/plans/README.md`](../plans/README.md). +3. ~~**`overview.md` “Planned topics (stubs)”** — Large overlap with the artifact index above it; optional consolidation would reduce maintenance when adding a new vision file (update one table instead of two).~~ **Done.** — Stub list trimmed to roadmap-only bullets; index owns shipped files. + +## Nits + +- **`documentation_and_implementation_alignment.md`** — The E1.M3 table cell is very long; fine for a living log, but harder to diff. Optional: split per-ticket bullets under the module page only, keep one line + “see module doc” in the table. +- **TODO block in `overview.md` (rating / compliance)** — Appropriate as vision debt; no change required unless stakeholders want it moved to a single “compliance” stub file. + +## Verification + +After any edits: + +1. ~~Re-open `docs/game-design/abilities.md` and confirm the Seams link reads naturally.~~ **Checked** (2026-05-05 follow-up). +2. ~~`rg 'NEON-' docs/plans` — decide whether each hit is archival or should gain a one-line deprecation pointer.~~ **Checked** — only [`NEON-29-implementation-plan.md`](../plans/NEON-29-implementation-plan.md); archival banner + [`docs/plans/README.md`](../plans/README.md). +3. Spot-check any new `docs/game-design/*.md` against `progression.md` vocabulary and `skills.md` Seams once before filing implementation plans.