neon-sprawl/docs/reviews/2026-05-30-epic-5-anchor-stability.md

# 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](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:~~

   ```markdown
   [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](2026-05-30-NEO-98-followup.md) suggestions are addressed; no reopen needed for NEO-98 doc cluster.

## Verification

After applying suggestions:

```bash
# 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.