Session memory extraction + tiered context loading improvements

- /review-all-gdds, /architecture-review, /story-done: auto-append Session
  Extract block to active.md after report write (verdict, flags, next action)
- /review-all-gdds, /architecture-review, /create-epics-stories, /content-audit:
  L0 summary scan phase before full document load (reduces token cost)
- GDD template: added Summary section + Cross-References table + Last Verified field
- ADR template: added Summary section + Last Verified field

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
2026-03-13 15:56:42 +11:00
parent 14593802fe
commit cdb1aa83b7
7 changed files with 169 additions and 16 deletions

View File

@@ -26,14 +26,34 @@ and Pre-Production.
## Phase 1: Load Everything
Read all inputs before analysis:
### Phase 1a — L0: Summary Scan (fast, low tokens)
Before reading any full document, use Grep to extract `## Summary` sections
from all GDDs and ADRs:
```
Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 4
Grep pattern="## Summary" glob="docs/architecture/adr-*.md" output_mode="content" -A 3
```
For `single-gdd [path]` mode: use the target GDD's summary to identify which
ADRs reference the same system (Grep ADRs for the system name), then full-read
only those ADRs. Skip full-reading unrelated GDDs entirely.
For `engine` mode: only full-read ADRs — GDDs are not needed for engine checks.
For `coverage` or `full` mode: proceed to full-read everything below.
### Phase 1b — L1/L2: Full Document Load
Read all inputs appropriate to the mode:
### Design Documents
- All GDDs in `design/gdd/` — read every file completely
- All in-scope GDDs in `design/gdd/` — read every file completely
- `design/gdd/systems-index.md` — the authoritative list of systems
### Architecture Documents
- All ADRs in `docs/architecture/` — read every file completely
- All in-scope ADRs in `docs/architecture/` — read every file completely
- `docs/architecture/architecture.md` if it exists
### Engine Reference
@@ -389,6 +409,22 @@ If yes:
This ensures all future story files can reference stable TR-IDs that persist
across every subsequent architecture review.
### Session State Update
After writing all approved files, silently append to
`production/session-state/active.md`:
## Session Extract — /architecture-review [date]
- Verdict: [PASS / CONCERNS / FAIL]
- Requirements: [N] total — [X] covered, [Y] partial, [Z] gaps
- New TR-IDs registered: [N, or "None"]
- GDD revision flags: [comma-separated GDD names, or "None"]
- Top ADR gaps: [top 3 gap titles from the report, or "None"]
- Report: docs/architecture/architecture-review-[date].md
If `active.md` does not exist, create it with this block as the initial content.
Confirm in conversation: "Session state updated."
The traceability index format:
```markdown

View File

@@ -22,10 +22,20 @@ Parse the argument:
1. **Read `design/gdd/systems-index.md`** for the full list of systems, their
categories, and MVP/priority tier.
2. **Read all GDD files** in `design/gdd/` (or the single system GDD if a
system name was given).
2. **L0 pre-scan**: Before full-reading any GDDs, Grep all GDD files for
`## Summary` sections plus common content-count keywords:
```
Grep pattern="(## Summary|N enemies|N levels|N items|N abilities|enemy types|item types)" glob="design/gdd/*.md" output_mode="files_with_matches"
```
For a single-system audit: skip this step and go straight to full-read.
For a full audit: full-read only the GDDs that matched content-count keywords.
GDDs with no content-count language (pure mechanics GDDs) are noted as
"No auditable content counts" without a full read.
3. **For each GDD, extract explicit content counts or lists.** Look for patterns
3. **Full-read in-scope GDD files** (or the single system GDD if a system
name was given).
4. **For each GDD, extract explicit content counts or lists.** Look for patterns
like:
- "N enemies" / "enemy types:" / list of named enemies
- "N levels" / "N areas" / "N maps" / "N stages"

View File

@@ -40,11 +40,28 @@ If no argument, use `AskUserQuestion`:
## 2. Load All Inputs
Read everything before generating any output:
### Step 2a — L0: Summary Scan
Before full-reading any documents, Grep all GDDs for their `## Summary` sections:
```
Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5
```
For `all` mode: display a manifest of all Approved/Designed GDDs with their
summaries so the user can confirm scope before the full load begins.
For `layer:` or `[system-name]` modes: filter to only the target GDDs based
on the Summary quick-reference line (Layer + Priority). Skip full-reading
GDDs outside the requested scope entirely.
### Step 2b — L1/L2: Full Document Load
Read everything for the in-scope systems before generating any output:
### Design Documents
- `design/gdd/systems-index.md` — authoritative system list, layers, status
- All GDDs in `design/gdd/` — read every file with "Approved" or "Designed" status
- In-scope GDDs in `design/gdd/` — read every file with "Approved" or "Designed" status
- For each GDD, extract:
- System name and layer (from systems-index.md)
- All acceptance criteria (these become story acceptance criteria)

View File

@@ -38,17 +38,37 @@ completeness. This skill reviews the *relationships* between all GDDs.
## Phase 1: Load Everything
Read all design documents before any analysis:
### Phase 1a — L0: Summary Scan (fast, low tokens)
Before reading any full document, use Grep to extract `## Summary` sections
from all GDD files:
```
Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5
```
Display a manifest to the user:
```
Found [N] GDDs. Summaries:
• combat.md — [summary text]
• inventory.md — [summary text]
...
```
For `since-last-review` mode: run `git log --name-only` to identify GDDs
modified since the last review report file was written. Show the user which
GDDs are in scope based on summaries before doing any full reads. Only
proceed to L1 for those GDDs plus any GDDs listed in their "Key deps".
### Phase 1b — L1/L2: Full Document Load
Full-read the in-scope documents:
1. `design/gdd/game-concept.md` — game vision, core loop, MVP definition
2. `design/gdd/game-pillars.md` if it exists — design pillars and anti-pillars
3. `design/gdd/systems-index.md` — authoritative system list, layers, dependencies, status
4. **Every system GDD in `design/gdd/`** — read completely (skip game-concept.md
and systems-index.md — those are read above)
For `since-last-review` mode: run `git log --name-only` to identify GDDs
modified since the last review report file was written. Only load those GDDs
plus any GDDs they depend on.
4. **Every in-scope system GDD in `design/gdd/`** — read completely (skip
game-concept.md and systems-index.md — those are read above)
Report: "Loaded [N] system GDDs covering [M] systems. Pillars: [list]. Anti-pillars: [list]."
@@ -510,6 +530,22 @@ Ask: "Should I update the systems index to mark these GDDs as needing revision?"
as an exact string and parentheticals break that match.)
Ask approval before writing.
### Session State Update
After writing the report (and updating systems index if approved), silently
append to `production/session-state/active.md`:
## Session Extract — /review-all-gdds [date]
- Verdict: [PASS / CONCERNS / FAIL]
- GDDs reviewed: [N]
- Flagged for revision: [comma-separated list, or "None"]
- Blocking issues: [N — brief one-line descriptions, or "None"]
- Recommended next: [the Phase 7 handoff action, condensed to one line]
- Report: design/gdd/gdd-cross-review-[date].md
If `active.md` does not exist, create it with this block as the initial content.
Confirm in conversation: "Session state updated."
---
## Phase 7: Handoff

View File

@@ -269,6 +269,20 @@ If yes, edit the story file:
- Update the top-level `updated` field
- This is a silent update — no extra approval needed (already approved in step above)
### Session State Update
After updating the story file, silently append to
`production/session-state/active.md`:
## Session Extract — /story-done [date]
- Verdict: [COMPLETE / COMPLETE WITH NOTES / BLOCKED]
- Story: [story file path] — [story title]
- Tech debt logged: [N items, or "None"]
- Next recommended: [next ready story title and path, or "None identified"]
If `active.md` does not exist, create it with this block as the initial content.
Confirm in conversation: "Session state updated."
---
## Phase 8: Surface the Next Story