don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
neon-sprawl/docs/reviews/2026-05-30-epic-5-anchor-st...

6.0 KiB
Raw Blame History

Documentation review — Epic 5 anchor stability + doc cluster

Date: 2026-05-30
Scope: Uncommitted docs batch — epic_05_pve_combat.md stable slice anchors; link updates in E5M1/E5M2/E5M3 backlogs, NEO-84/NEO-86/NEO-96/NEO-98 plans, server/README.md; cross-check against Epic 5 modules, game-design progression seams, and full-stack backlog policy
Base: Working tree on main (uncommitted)

Verdict

Approve — suggestions applied (2026-05-30 follow-up).

Summary

The batch correctly adds explicit HTML slice anchors to epic_05_pve_combat.md (matching the Epic 1 / Epic 3 precedent) and removes fragile GitHub heading slugs (#slice-1---combat-rules-mvp, etc.) that were prone to renderer drift. Hook vocabulary, gig-vs-skill XP boundaries, and full-stack E5M1/E5M2/E5M3 backlog pairing remain aligned with game-design and module docs. Follow-ups from initial review (stable deep links, E5M2 NEO-98 resolve vocabulary, E5.M3 Linear row) are Done.

Documentation checked

Path Result
docs/decomposition/epics/epic_05_pve_combat.md Matches — <a id="epic-5-slice-1"> … epic-5-slice-4, epic-5-definition-of-done; slice telemetry vocabulary unchanged.
docs/plans/E5M1-prototype-backlog.md Matches — epic links use stable #epic-5-slice-1 / #epic-5-definition-of-done anchors; Slice 1 complete; full-stack checklist satisfied.
docs/plans/E5M2-prototype-backlog.md Matches — stable slice/DoD anchors; kickoff + E5M2-09 document NEO-98 attackAbilityId resolve supersession; full-stack pairing NEO-97/NEO-98 intact.
docs/plans/E5M3-prototype-backlog.md Matches — stable #epic-5-slice-3 / DoD anchors; decomposition checklist + client capstone NEO-111 present. Gig XP / encounter loot separation matches progression.md seams.
docs/plans/NEO-84-implementation-plan.md Matches — hook names align with epic Slice 1 list.
docs/plans/NEO-86-implementation-plan.md Matches — capstone AC + gig XP proof; DoD link uses #epic-5-definition-of-done.
docs/plans/NEO-96-implementation-plan.md Matches — Slice 2 hook vocabulary; reconciliation complete.
docs/plans/NEO-98-implementation-plan.md Matches — capstone scope reconciliation documents NEO-98 server integration; aligns with 2026-05-30-NEO-98-followup.md.
docs/decomposition/modules/E5_M1_CombatRulesEngine.md Matches — gig XP on defeat via NEO-44; combat → gig, not E2.M2 skill XP.
docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md Matches — freeze table + NEO-98 attackAbilityId / range-gated resolve documented.
docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md Matches — slug table (lines 50–63) and summary Linear row both use E5M3-08 → NEO-108, E5M3-09 → NEO-107.
docs/decomposition/modules/documentation_and_implementation_alignment.md Matches — E5.M1 Ready, E5.M2 Ready + NEO-98 integration, E5.M3 decomposed In Progress.
docs/game-design/progression.md, gigs.md, abilities.md N/A (not edited) — spot-check: combat encounters → gig XP; no skill XP from fight loop reintroduced in Epic 5 docs.
server/README.md (NEO-84 combat hooks) Matches — epic link valid; hook semantics unchanged.
server/README.md (NEO-96 NPC hooks) Matches — epic cross-link to Slice 2 anchor added (parity with NEO-84).

Blocking issues

None.

Suggestions

  1. Use stable slice anchors in deep links — Anchors exist (epic-5-slice-1 … epic-5-slice-4, epic-5-definition-of-done) but updated links drop fragments entirely. Match Epic 3 / E3M1 pattern: Done. Backlog intros, telemetry AC, DoD re-read AC, and server/README.md NEO-84/NEO-96 now use #epic-5-slice-N / #epic-5-definition-of-done.

    Example target:

    [Epic 5 · Slice 2 — NPC archetypes and telegraphs](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-2)

  2. E5M2 backlog — NEO-98 resolve source drift — Kickoff table row NPC attacks and E5M2-09 goal still say telegraph resolve applies NpcBehaviorDef.attackDamage. Module doc and NEO-98 plan correctly document attackAbilityId + ability baseDamage / maxRange. Add a kickoff footnote or revise the E5M2-09 goal + landed NEO-95 line to note NEO-98 supersession (behavior attackDamage = projection/CI cross-ref only). Done.

  3. E5_M3 module summary Linear row — Line 11 lists E5M3-08 → NEO-107, E5M3-09 → NEO-108; backlog and slug table in the same module file use E5M3-08 → NEO-108, E5M3-09 → NEO-107 (documented creation-order swap). Fix the summary Linear cell to match the slug table. Done.

Nits

  • Related docs path style — E5M2/E5M3 backlogs use ./../decomposition/epics/epic_05_pve_combat.md; E5M1 uses ../decomposition/.... Normalize to one form. Done. All E5 backlogs use ../decomposition/....
  • Epic 5 Slice 4 — Anchor epic-5-slice-4 added with no current consumers (pre-production); fine as forward-looking stability.
  • Prior reviews — 2026-05-30-NEO-98-followup.md suggestions are addressed; no reopen needed for NEO-98 doc cluster.

Verification

After applying suggestions:

# No remaining fragile epic_05 heading slugs
rg 'epic_05_pve_combat\.md#' docs/ server/

# Epic 5 stable anchors referenced where slice-specific
rg 'epic-5-slice-|epic-5-definition-of-done' docs/

# E5M3 slug ↔ Linear consistency
rg 'E5M3-0[89].*NEO-10[78]' docs/plans/E5M3-prototype-backlog.md docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md

# NEO-98 resolve vocabulary in E5M2 backlog
rg 'attackDamage|attackAbilityId' docs/plans/E5M2-prototype-backlog.md

Human re-read: epic Slice 1–3 telemetry hook lists vs plan AC checklists; E5M3 kickoff Gig XP row vs progression.md combat → gig seam.