ksh999000/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios.git synced 2026-10-16 10:17:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Release 1.1.3 — long skills keep their later steps

Browse Source 
Fix release for 1.1.2: the 14 longest skills keep their later phases
after a compaction, a question nobody answered is never taken as an
answer, settings read the same from a subfolder, the commit check works
for a project in a subfolder of a larger repository, every skill opens
with a title, and the shipped allow rules no longer approve deleting a
branch or writing files without asking. Details in CHANGELOG.md; upgrade
steps in UPGRADING.md (v1.1.2 → v1.1.3).

Refs #83
Refs #133

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0185en4t76fPn7315q4c3nko
This commit is contained in:
Donchitos
2026-10-08 17:52:48 +11:00
co-authored by Claude Opus 5.5
parent b21fa0f7f2
commit be8993bbc5
231 changed files with 12000 additions and 10527 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/review-all-gdds/references/1-load.md
+115
View File
@@ -0,0 +1,115 @@
# /review-all-gdds — Phase 1: Load Everything
> Part of `/review-all-gdds`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.
## Phase 1: Load Everything
**In this file:**
- Phase 1a — L0: Summary Scan (fast, low tokens)
- Phase 1b — Registry Pre-Load (fast baseline)
- Phase 1c — L1/L2: Section Load
### 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
```
**Fail open on a missing Summary.** Establish the denominator: glob
`design/gdd/*.md` and count **N**. A scan matching fewer than N means those GDDs
predate `## Summary` — never treat an absent Summary as a system out of scope.
A zero-match scan means "no GDD carries a Summary yet", not "nothing to review".
This review is holistic and loads its in-scope GDDs regardless (see Phase 1c);
the Summary scan only builds the manifest and narrows `since-last-review`, it
never shrinks the review set.
Display a manifest to the user:
```
Found [N] GDDs. Summaries:
• combat.md — [summary text]
• inventory.md — [summary text]
...
```
For `since-last-review` mode, compute the scope deterministically instead of
reasoning through git history:
```
Bash: bash .claude/scripts/review-scope.sh
```
It prints `PRIOR_REVIEW:`, a `CHANGED:` list, and a `DEPS ...:` list of each
changed GDD's declared dependencies. Use those lists as the scope — the
dependency lines are already the "Key deps" expansion, so no second pass is
needed. If `PRIOR_REVIEW: NONE`, a full review is required; fall back to `full`
mode.
Show the user which GDDs are in scope based on summaries before doing any full
reads. Only proceed to L1 for the `CHANGED` set plus the GDDs named on the
`DEPS` lines.
### Phase 1b — Registry Pre-Load (fast baseline)
Before full-reading any GDD, check for the entity registry:
```
Read path="design/registry/entities.yaml"
```
If the registry exists and has entries, use it as a **pre-built conflict
baseline**: known entities, items, formulas, and constants with their
authoritative values and source GDDs. In Phase 2, grep GDDs for registered
names first — this is faster than reading all GDDs in full before knowing
what to look for.
If the registry is empty or absent: proceed without it. Note in the report:
"Entity registry is empty — consistency checks rely on full GDD reads only.
Run `/consistency-check` after this review to populate the registry."
### Phase 1c — L1/L2: Section Load
Read whole (small, and every part is used):
1. `design/gdd/game-concept.md` — game vision, core loop, MVP definition (or
`design/game-brief.md`, the one-page brief that replaces it at `rigor: minimal` —
pitch, core loop, MVP list)
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
Then, for **every in-scope system GDD**, load the sections this review actually
consumes — **not the whole file**:
```
Grep pattern="^## (Dependencies|Detailed Rules|Detailed Design|Formulas|Tuning Knobs|Acceptance Criteria|Player Fantasy)" glob="design/gdd/*.md" output_mode="content" -A 40
```
That list is not a guess — it is exactly the union the Parallel Execution
contract below already enumerates: Phase 2 needs Dependencies, Detailed
Design/Rules, Formulas, Tuning Knobs and Acceptance Criteria; Phase 3 needs
Player Fantasy and progression/reward structure. Overview is narrative restated
by the Summary this skill already scanned in Phase 1a, and Edge Cases feeds no
checklist item here (`/design-review` owns per-GDD completeness). Loading them
put content in three context windows — this one and both sub-agents' — that no
checklist item ever read.
Accept **either** `## Detailed Rules` or `## Detailed Design`; the design standard
and the GDD template disagree on the name and they denote the same section.
**Escalate to a full read of one GDD** when a scanned section cross-references
material outside itself, or when a GDD matched **zero** sections — that GDD
predates the template, and a zero-match there means "unstructured", not "empty".
Never let a zero-match silently drop a system: the scan narrows the *read*, it
never shrinks the *review set*.
Report: "Loaded [N] system GDDs covering [M] systems. Pillars: [list]. Anti-pillars: [list]."
If fewer than 2 system GDDs exist (count the files present; an empty one is handled under NOT ASSESSED in Phase 5, not here), stop:
> "Cross-GDD review requires at least 2 system GDDs. Write more GDDs first,
> then re-run `/review-all-gdds`."
---
.claude/skills/review-all-gdds/references/2-consistency.md
+145
View File
@@ -0,0 +1,145 @@
# /review-all-gdds — Phase 2: Cross-GDD Consistency
> Part of `/review-all-gdds`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.
## Phase 2: Cross-GDD Consistency
**In this file:**
- 2a: Dependency Bidirectionality
- 2b: Rule Contradictions
- 2c: Stale References
- 2d: Data and Tuning Knob Ownership Conflicts
- 2e: Formula Compatibility
- 2f: Acceptance Criteria Cross-Check
Work through every pair and group of GDDs to find contradictions and gaps.
### 2a: Dependency Bidirectionality
For every GDD's Dependencies section, check that every listed dependency is
reciprocal:
- If GDD-A lists "depends on GDD-B", check that GDD-B lists GDD-A as a dependent
- If GDD-A lists "depended on by GDD-C", check that GDD-C lists GDD-A as a dependency
- Flag any one-directional dependency as a consistency issue
```
⚠️ Dependency Asymmetry
[system-a].md lists: Depends On → [system-b].md
[system-b].md does NOT list [system-a].md as a dependent
→ One of these documents has a stale dependency section
```
### 2b: Rule Contradictions
For each game rule, mechanic, or constraint defined in any GDD, check whether
any other GDD defines a contradicting rule for the same situation:
Categories to scan:
- **Floor/ceiling rules**: Does any GDD define a minimum value for an output? Does any other say a different system can bypass that floor? These contradict.
- **Resource ownership**: If two GDDs both define how a shared resource accumulates or depletes, do they agree?
- **State transitions**: If GDD-A describes what happens when a character dies,
does GDD-B's description of the same event agree?
- **Timing**: If GDD-A says "X happens on the same frame", does GDD-B assume
it happens asynchronously?
- **Stacking rules**: If GDD-A says status effects stack, does GDD-B assume
they don't?
```
🔴 Rule Contradiction
[system-a].md: "Minimum [output] after reduction is [floor_value]"
[system-b].md: "[mechanic] bypasses [system-a]'s rules and can reduce [output] to 0"
→ These rules directly contradict. Which GDD is authoritative?
```
### 2c: Stale References
**Start from the `## Cross-References` table where a GDD has one.** That table is
the document's own declaration of what it depends on — `templates/game-design-document.md`
tells authors it is machine-checked here, and `/design-system` requires it
whenever Dependencies names another GDD. For each row, confirm the `Target GDD`
exists and the `Specific Element Referenced` is still present in it under that
name, with the declared `Nature` still accurate.
A table that is absent, or still holding the template's bracketed examples, is
itself reportable: say the GDD declares no cross-references and that the prose
scan below was the only check applied. Do not treat an absent table as "no
dependencies" — it far more often means the section was never authored.
**Then scan the prose regardless**, table or no table: a declared table catches
what the author remembered, and the scan below catches what they did not.
For every cross-document reference (GDD-A mentions a mechanic, value, or
system name from GDD-B), verify the referenced element still exists in GDD-B
with the same name and behaviour:
- If GDD-A says "combo multiplier from the combat system feeds into score", check
that the combat GDD actually defines a combo multiplier that outputs to score
- If GDD-A references "the progression curve defined in [system].md", check that
[system].md actually has that curve, not a different progression model
- If GDD-A was written before GDD-B and assumed a mechanic that GDD-B later
designed differently, flag GDD-A as containing a stale reference. Severity: a
reference to a mechanic or formula that **does not exist** is **Blocking** — the
architecture would inherit a rule nobody defined; one that exists but was
designed differently is a **Warning**, unless the difference changes a rule the
referencing GDD depends on (then Blocking)
- If the **target GDD is not written yet** (no file in `design/gdd/`): when
`systems-index.md` lists that system (e.g. `Status: Not Started`), it is a
**Warning** — a dependency on planned work, to re-check when that GDD is
written; when neither a GDD nor a systems-index entry exists for it, it is
**Blocking** — nothing will ever define it
```
🔴 Stale Reference
inventory.md (written first): "Item weight uses the encumbrance formula
from movement.md"
movement.md (written later): Defines no encumbrance formula — uses a flat
carry limit instead
→ inventory.md references a formula that doesn't exist — Blocking
```
### 2d: Data and Tuning Knob Ownership Conflicts
Two GDDs should not both claim to own the same data or tuning knob. Scan all
Tuning Knobs sections across all GDDs and flag duplicates:
```
⚠️ Ownership Conflict
[system-a].md Tuning Knobs: "[multiplier_name] — controls [output] scaling"
[system-b].md Tuning Knobs: "[multiplier_name] — scales [output] with [factor]"
→ Two GDDs define multipliers on the same output. Which owns the final value?
This will produce either a double-application bug or a design conflict.
```
### 2e: Formula Compatibility
For GDDs whose formulas are connected (output of one feeds input of another),
check that the output range of the upstream formula is within the expected
input range of the downstream formula:
- If [system-a].md outputs values between [min]–[max], and [system-b].md is
designed to receive values between [min2]–[max2], is the mismatch intentional?
- If an economy GDD expects resource acquisition in range X, and the
progression GDD generates it at range Y, the economy will be trivial or
inaccessible — is that intended?
Flag incompatibilities as CONCERNS (design judgment needed, not necessarily wrong):
```
⚠️ Formula Range Mismatch
[system-a].md: Max [output] = [value_a] (at max [condition])
[system-b].md: Base [input] = [value_b], max [input] = [value_c]
→ Late-[stage] [scenario] can resolve in a single [event].
Is this intentional? If not, either [system-a]'s ceiling or [system-b]'s ceiling needs adjustment.
```
### 2f: Acceptance Criteria Cross-Check
Scan Acceptance Criteria sections across all GDDs for contradictions:
- GDD-A criteria: "Player cannot die from a single hit"
- GDD-B criteria: "Boss attack deals 150% of player max health"
These acceptance criteria cannot both pass simultaneously.
---
.claude/skills/review-all-gdds/references/3-design-holism.md
+183
View File
@@ -0,0 +1,183 @@
# /review-all-gdds — Phase 3: Game Design Holism
> Part of `/review-all-gdds`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.
## Phase 3: Game Design Holism
**In this file:**
- 3a: Progression Loop Competition
- 3b: Player Attention Budget
- 3c: Dominant Strategy Detection
- 3d: Economic Loop Analysis
- 3e: Difficulty Curve Consistency
- 3f: Pillar Alignment
- 3g: Player Fantasy Coherence
Review all GDDs together through the lens of game design theory and player
psychology. These are issues that individual GDD reviews cannot catch because
they require seeing all systems at once.
### 3a: Progression Loop Competition
A game should have one dominant progression loop that players feel is "the
point" of the game, with supporting loops that feed into it. When multiple
systems compete equally as the primary progression driver, players don't know
what the game is about.
Scan all GDDs for systems that:
- Award the player's primary resource (XP, levels, prestige, unlocks)
- Define themselves as the "core" or "main" loop
- Have comparable depth and time investment to other systems doing the same
```
⚠️ Competing Progression Loops
combat.md: Awards XP, unlocks abilities, is described as "the core loop"
crafting.md: Awards XP, unlocks recipes, is described as "the primary activity"
exploration.md: Awards XP, unlocks map areas, described as "the main driver"
→ Three systems all claim to be the primary progression loop and all award
the same primary currency. Players will optimise one and ignore the others.
Consider: one primary loop with the others as support systems.
```
### 3b: Player Attention Budget
Count how many systems require active player attention simultaneously during
a typical session. Each actively-managed system costs attention:
- Active = player must make decisions about this system regularly during play
- Passive = system runs automatically, player sees results but doesn't manage it
More than 3-4 simultaneously active systems creates cognitive overload for most
players. Present the count and flag if it exceeds 4 concurrent active systems:
```
⚠️ Cognitive Load Risk
Simultaneously active systems during [core loop moment]:
1. [system-a].md — [decision type] (active)
2. [system-b].md — [resource management] (active)
3. [system-c].md — [tracking] (active)
4. [system-d].md — [item/action use] (active)
5. [system-e].md — [cooldown/timer management] (active)
6. [system-f].md — [coordination decisions] (active)
→ 6 simultaneously active systems during the core loop.
Research suggests 3-4 is the comfortable limit for most players.
Consider: which of these can be made passive or simplified?
```
### 3c: Dominant Strategy Detection
A dominant strategy makes other strategies irrelevant — players discover it,
use it exclusively, and find the rest of the game boring. Look for:
- **Resource monopolies**: One strategy generates a resource significantly
faster than all others
- **Risk-free power**: A strategy that is both high-reward and low-risk
(if high-risk strategies exist, they need proportionally higher reward)
- **No trade-offs**: An option that is superior in all dimensions to all others
- **Obvious optimal path**: If any progression choice is "clearly correct",
the others aren't real choices
```
⚠️ Potential Dominant Strategy
combat.md: Ranged attacks deal 80% of melee damage with no risk
combat.md: Melee attacks deal 100% damage but require close range
→ Unless melee has a significant compensating advantage (AOE, stagger,
resource regeneration), ranged is dominant — higher safety, only 20% less
damage. Consider what melee offers that ranged cannot.
```
### 3d: Economic Loop Analysis
Identify all resources across all GDDs (gold, XP, crafting materials, stamina,
health, mana, etc.). For each resource, map its **sources** (how players gain
it) and **sinks** (how players spend it).
Flag dangerous economic conditions:
| Condition | Sign | Risk |
|-----------|------|------|
| **Infinite source, no sink** | Resource accumulates indefinitely | Late game becomes trivially easy |
| **Sink, no source** | Resource drains to zero | System becomes unavailable |
| **Source >> Sink** | Surplus accumulates | Resource becomes meaningless |
| **Sink >> Source** | Constant scarcity | Frustration and gatekeeping |
| **Positive feedback loop** | More resource → easier to earn more | Runaway leader, snowball |
| **No catch-up** | Falling behind accelerates deficit | Unrecoverable states |
```
🔴 Economic Imbalance: Unbounded Positive Feedback
gold economy:
Sources: monster drops (scales with player power), merchant selling (unlimited)
Sinks: equipment purchase (one-time), ability upgrades (finite count)
→ After equipment and abilities are purchased, gold has no sink.
Infinite surplus. Gold becomes meaningless mid-game.
Add ongoing gold sinks (upkeep, consumables, cosmetics, gambling).
```
### 3e: Difficulty Curve Consistency
When multiple systems scale with player progression, they must scale in
compatible directions and at compatible rates. Mismatched scaling curves
create unintended difficulty spikes or trivialisations.
For each system that scales over time, extract:
- What scales (enemy health, player damage, resource cost, area size)
- How it scales (linear, exponential, stepped)
- When it scales (level, time, area)
Compare all scaling curves. Flag mismatches:
```
⚠️ Difficulty Curve Mismatch
combat.md: Enemy health scales exponentially with area (×2 per area)
progression.md: Player damage scales linearly with level (+10% per level)
→ By area 5, enemies have 32× base health; player deals ~1.5× base damage.
The gap widens indefinitely. Late areas will become inaccessibly difficult
unless the curves are reconciled.
```
### 3f: Pillar Alignment
Every system should clearly serve at least one design pillar. A system that
serves no pillar is "scope creep by design" — it's in the game but not in
service of what the game is trying to be.
For each GDD system, check its Player Fantasy section against the design pillars.
Flag any system whose stated fantasy doesn't map to any pillar:
```
⚠️ Pillar Drift
fishing-system.md: Player Fantasy — "peaceful, meditative activity"
Pillars: "Brutal Combat", "Tense Survival", "Emergent Stories"
→ The fishing system serves none of the three pillars. Either add a pillar
that covers it, redesign it to serve an existing pillar, or cut it.
```
Also check anti-pillars — flag any system that does what an anti-pillar
explicitly says the game will NOT do:
```
🔴 Anti-Pillar Violation
Anti-Pillar: "We will NOT have linear story progression — player defines their path"
main-quest.md: Defines a 12-chapter linear story with mandatory sequence
→ This system directly violates the defined anti-pillar.
```
### 3g: Player Fantasy Coherence
The player fantasies across all systems should be compatible — they should
reinforce a consistent identity for what the player IS in this game. Conflicting
player fantasies create identity confusion.
```
⚠️ Player Fantasy Conflict
combat.md: "You are a ruthless, precise warrior — every kill is earned"
dialogue.md: "You are a charismatic diplomat — violence is always avoidable"
exploration.md: "You are a reckless adventurer — diving in without a plan"
→ Three systems present incompatible identities. Players will feel the game
doesn't know what it wants them to be. Consider: do these fantasies serve
the same core identity from different angles, or do they genuinely conflict?
```
---
.claude/skills/review-all-gdds/references/4-scenarios.md
+87
View File
@@ -0,0 +1,87 @@
# /review-all-gdds — Phase 4: Cross-System Scenario Walkthrough
> Part of `/review-all-gdds`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.
## Phase 4: Cross-System Scenario Walkthrough
Walk through the game from the player's perspective to find problems that only
appear at the interaction boundary between multiple systems — things static
analysis of individual GDDs cannot surface.
### 4a: Identify Key Multi-System Moments
Scan all GDDs and identify the 3–5 most important player-facing moments where
multiple systems activate simultaneously. Look specifically for:
- **Combat + Economy overlap**: killing enemies that drop resources, spending
resources during combat, death/respawn interacting with economy state
- **Progression + Difficulty overlap**: level-up triggering mid-fight, ability
unlocks changing combat viability, difficulty scaling at progression milestones
- **Narrative + Gameplay overlap**: dialogue choices locking/unlocking mechanics,
story beats interrupting resource loops, quest completion triggering system
state changes
- **3+ system chains**: any player action that triggers System A, which feeds
into System B, which triggers System C (these are highest-risk interaction paths)
List each identified scenario with a one-line description before proceeding.
### 4b: Walk Through Each Scenario
For each scenario, step through the sequence explicitly:
1. **Trigger** — what player action or game event starts this?
2. **Activation order** — which systems activate, in what sequence?
3. **Data flow** — what does each system output, and is that output a valid
input for the next system in the chain?
4. **Player experience** — what does the player see, hear, or feel at each step?
5. **Failure modes** — are there any of the following?
- **Race conditions**: two systems trying to modify the same state simultaneously
- **Feedback loops**: System A amplifies System B which re-amplifies System A
with no cap or dampener
- **Broken state transitions**: a system assumes a state that a previous
system may have changed (e.g., "player is alive" assumption after a combat
step that could have caused death)
- **Contradictory messaging**: player receives conflicting feedback from two
systems reacting to the same event (e.g., "success" sound + "failure" UI)
- **Compounding difficulty spikes**: two systems both scaling up at the same
progression point, multiplying the intended difficulty increase
- **Reward conflicts**: two systems both reacting to the same trigger with
rewards that together exceed the intended value (double-dipping)
- **Undefined behavior**: the GDDs don't specify what happens in this combined
state (neither system's rules cover it)
```
Example walkthrough:
Scenario: Player kills elite enemy at level-up threshold during active quest
Trigger: Player lands killing blow on elite enemy
→ combat.md: awards kill XP (100 pts)
→ progression.md: XP total crosses level threshold → triggers level-up
Output: new level, stat increases, ability unlock popup
→ quest.md: kill-count criterion met → triggers quest completion event
Output: quest reward XP (500 pts), completion fanfare
→ progression.md (again): quest XP added → triggers SECOND level-up in same frame
⚠️ Data flow issue: quest.md awards XP without checking if a level-up
is already in progress. progression.md has no guard against concurrent
level-up events. Undefined behavior: does the player level up once or twice?
Does the ability popup fire twice? Does the second level use the updated or
pre-update stat baseline?
```
### 4c: Flag Scenario Issues
For each problem found during the walkthrough, categorize severity:
- **BLOCKER**: undefined behavior, broken state transition, or contradictory
player messaging — the experience is broken or incoherent in this scenario
- **WARNING**: compounding spikes, feedback loops without caps, reward conflicts —
the experience works but produces unintended outcomes
- **INFO**: minor ordering ambiguity or messaging overlap — worth noting but
unlikely to cause player-visible problems
Add all findings to the output report under **"Cross-System Scenario Issues"**.
Each finding must cite: the scenario name, the specific systems involved, the
step where the issue occurs, and the nature of the failure mode.
---
.claude/skills/review-all-gdds/references/5-report.md
+118
View File
@@ -0,0 +1,118 @@
# /review-all-gdds — Phase 5: Output the Review Report
> Part of `/review-all-gdds`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.
## Phase 5: Output the Review Report
**In this file:**
- The report template
- `NOT ASSESSED` and where it ranks
```
## Cross-GDD Review Report
Date: [date]
GDDs Reviewed: [N] of [M] present
Not read: [each GDD that could not be read or is present but empty, by file name — or "none"]
Systems Covered: [list]
---
### Consistency Issues
#### Blocking (must resolve before architecture begins)
🔴 [Issue title]
[What GDDs are involved, what the contradiction is, what needs to change]
#### Warnings (should resolve, but won't block)
⚠️ [Issue title]
[What GDDs are involved, what the concern is]
---
### Game Design Issues
#### Blocking
🔴 [Issue title]
[What the problem is, which GDDs are involved, design recommendation]
#### Warnings
⚠️ [Issue title]
[What the concern is, which GDDs are affected, recommendation]
---
### Cross-System Scenario Issues
Scenarios walked: [N]
[List scenario names]
#### Blockers
🔴 [Scenario name] — [Systems involved]
[Step where failure occurs, nature of the failure mode, what must be resolved]
#### Warnings
⚠️ [Scenario name] — [Systems involved]
[What the unintended outcome is, recommendation]
#### Info
ℹ️ [Scenario name] — [Systems involved]
[Minor ordering ambiguity or note]
---
### GDDs Flagged for Revision
| GDD | Reason | Type | Priority |
|-----|--------|------|----------|
| [system-a].md | Rule contradiction with [system-b].md | Consistency | Blocking |
| [system-b].md | Rule contradiction with [system-a].md | Consistency | Blocking |
| [system-c].md | Stale reference to nonexistent mechanic | Consistency | Blocking |
| [system-d].md | No pillar alignment | Design Theory | Warning |
---
### Verdict: [PASS / NOT ASSESSED / CONCERNS / FAIL]
PASS: No blocking issues and no warnings.
NOT ASSESSED: One or more review phases could not run — named below.
CONCERNS: Warnings present that should be resolved, but nothing blocking.
FAIL: One or more blocking issues must be resolved before architecture begins.
### If NOT ASSESSED — what could not be reviewed, and why:
[Name each phase that did not run and the input it needed, and each GDD that could not be read or is present but empty, by file name]
### If FAIL — required actions before re-running:
[Specific list of what must change in which GDD]
```
**`NOT ASSESSED` — a cross-review is only as wide as what it could read.** Rank:
**above PASS**, **below CONCERNS and FAIL**. This skill's whole value is
comparing systems *against each other*, so it is unusually easy for it to look
thorough while covering a fraction of the surface. Emit it when any of:
- **Fewer than two GDDs were readable.** Contradiction-hunting across one document
is not a cross-review; a clean result there means only that nothing was
compared. This is the single most important trigger in this skill.
- **A whole review phase did not run** — consistency, design theory, economy,
pillar drift. A parallel phase that returned nothing has to be distinguished
from one that returned no findings; if a spawned agent produced no report, that
phase is NOT ASSESSED, not clean — an agent can return a fluent sentence,
write nothing, and consume a phase.
- **The design pillars are undefined**, so pillar-drift has no reference to drift
from — the same shape as an accessibility gate with no committed tier.
- **A GDD is present but empty** (headings only, or all placeholders), **or
could not be read**. Present is not the same as reviewable, and a stub
contradicts nothing.
Report the covered set explicitly either way: `GDDs reviewed: [N] of [M] present`
(`[M]` counts the system GDDs present — the Phase 1c set, not `game-concept.md`,
`game-pillars.md`, `systems-index.md` or an earlier `gdd-cross-review-*.md`),
and the `Not read:` line naming every GDD that could not be read or is present but empty, whatever the
verdict — a FAIL found in the GDDs that were read does not make the unread ones
reviewed.
A cross-review that silently skipped half the systems is indistinguishable from
one that found them consistent.
---
.claude/skills/review-all-gdds/references/6-write.md
+49
View File
@@ -0,0 +1,49 @@
# /review-all-gdds — Phase 6: Write Report and Flag GDDs
> Part of `/review-all-gdds`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.
## Phase 6: Write Report and Flag GDDs
Use `AskUserQuestion` for write permission:
- Prompt: "May I write this review to `design/gdd/gdd-cross-review-[date].md`?"
- Options: `[A] Yes — write the report` / `[B] No — skip`
> **`[date]` here means ISO 8601 — `YYYY-MM-DD`, e.g.
> `gdd-cross-review-2026-08-19.md`. This is not a style preference.**
> `.claude/scripts/review-scope.sh` picks the prior review with
> `sort | tail -1`, so lexical order IS chronological order only for ISO dates.
> Written as `aug-19-2026` or `19-08-2026`, the wrong file is chosen as the
> baseline, the changed-set is computed from it, and GDDs modified since the
> real last review silently escape the next one. That is the same
> quiet-escape failure the three fixes documented at the top of that script
> exist to prevent.
If any GDDs are flagged for revision, use a second `AskUserQuestion`:
- Prompt: "Should I update the systems index to mark these GDDs as needing revision? ([list of flagged GDDs])"
- Options: `[A] Yes — update systems index` / `[B] No — leave as-is`
- If yes: update each flagged GDD's Status field in systems-index.md to "Needs Revision".
(Do NOT append parentheticals to the status value — other skills match "Needs Revision"
as an exact string and parentheticals break that match.)
### 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 / NOT ASSESSED / CONCERNS / FAIL]
- GDDs reviewed: [N of M present]
- Phases not run: [names, or "None"]
- 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 ← only if user approved the write
- Report: (not written — user declined at [date]) ← only if user declined the write
Use the appropriate line based on the user's response to the write-permission widget in Phase 6.
If `active.md` does not exist, create it with this block as the initial content.
Confirm in conversation: "Session state updated."
---
.claude/skills/review-all-gdds/references/7-handoff.md
+32
View File
@@ -0,0 +1,32 @@
# /review-all-gdds — Phase 7: Handoff
> Part of `/review-all-gdds`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.
## Phase 7: Handoff
After all file writes are complete, use `AskUserQuestion` for a closing widget.
Before building options, check project state:
- Are there any Warning-level items that are simple edits (flagged with "30-second edit", "brief addition", or similar)? → offer inline quick-fix option
- Are any GDDs in the "Flagged for Revision" table? → offer /design-review option for each
- Read systems-index.md for the next system with Status: Not Started → offer /design-system option
- Is the verdict PASS or CONCERNS? → offer /gate-check or /create-architecture
Build the option list dynamically — only include options that apply:
**Option pool:**
- `[_] Apply quick fix: [W-XX description] in [gdd-name].md — [effort estimate]` (one option per simple-edit warning; only for Warning-level, not Blocking)
- `[_] Run /design-review [flagged-gdd-path] — address flagged warnings` (one per flagged GDD, if any)
- `[_] Run /design-system [next-system] — next in design order` (always include, name the actual system)
- `[_] Run /create-architecture — begin architecture (verdict is PASS/CONCERNS)` (include only if the verdict is PASS or CONCERNS — never on FAIL or NOT ASSESSED)
- `[_] Run /gate-check — validate Systems Design phase gate` (include if verdict is PASS)
- `[_] Stop here`
Assign letters A, B, C… only to included options. Mark the most pipeline-advancing option as `(recommended)`.
In collaborative and guided modes, never end the skill with plain text — always
close with this widget. In autonomous mode, print the verdict and recommended
next step, then record via `log_decision` (no widget).
---