design-review

Resolve every role through ../../../.codex/docs/plugin-agent-delegation.md; do not require a repository-local .codex/agents/ or .codex/agent-packs/ tree. Before default delegation, run python3 ../../../tools/codex_studio/agent_delegation.py resolve --project-root <project-root> --role <role> and use only its returned role contract.

Codex-native operating rules

Keep repository source artifacts read-only during analysis and cite concrete file evidence for every finding. Ask at most one user question per turn and wait for the answer. A report or tracking update may be written only after its exact changeset and paths are approved. Do not fix reviewed source artifacts unless the user separately approves the proposed fix changeset.

Phase 0: Parse Arguments

Extract --depth [full|lean|solo] if present. Default is full when no flag is given.

Note: --depth controls the analysis depth of this skill (how many specialist agents are consulted). It is independent of the persistent review_mode in .codex/studio.toml, which controls director gate delegation. These are two different concepts — --depth is about how thoroughly this skill analyses the document.

• full: Complete review — all phases + specialist agent delegation (Phase 3b)
• lean: All phases, no specialist agents — faster, single-session analysis
• solo: Phases 1-4 only, no delegation, no Phase 5 next-step prompt — use when called from within another skill

Phase 1: Load Documents

Read the target design document in full. Read AGENTS.md to understand project context and standards. Read related design documents referenced or implied by the target doc (check design/gdd/ for related systems).

Dependency graph validation: For every system listed in the Dependencies section, search the repository to check whether its GDD file exists in design/gdd/. Flag any that don't exist yet — these are broken references that downstream authors will hit.

Lore/narrative alignment: If design/gdd/game-concept.md or any file in design/narrative/ exists, read it. Note any mechanical choices in this GDD that contradict established world rules, tone, or design pillars. Pass this context to game-designer in Phase 3b.

Prior review check: Check whether design/gdd/reviews/[doc-name]-review-log.md exists. If it does, read the most recent entry — note what verdict was given and what blocking items were listed. This session is a re-review; track whether prior items were addressed.

Phase 2: Completeness Check

Evaluate against the Design Document Standard checklist:

• Has Overview section (one-paragraph summary)
• Has Player Fantasy section (intended feeling)
• Has Detailed Rules section (unambiguous mechanics)
• Has Formulas section (all math defined with variables)
• Has Edge Cases section (unusual situations handled)
• Has Dependencies section (other systems listed)
• Has Tuning Knobs section (configurable values identified)
• Has Acceptance Criteria section (testable success conditions)

Phase 3: Consistency and Implementability

Internal consistency:

• Do the formulas produce values that match the described behavior?
• Do edge cases contradict the main rules?
• Are dependencies bidirectional (does the other system know about this one)?

Implementability:

• Are the rules precise enough for a programmer to implement without guessing?
• Are there any "hand-wave" sections where details are missing?
• Are performance implications considered?

Cross-system consistency:

• Does this conflict with any existing mechanic?
• Does this create unintended interactions with other systems?
• Is this consistent with the game's established tone and pillars?

Phase 3b: Adversarial Specialist Review (full mode only)

Skip this phase in lean or solo mode.

This phase is MANDATORY in full mode. Do not skip it.

Before delegating to any agents, print this notice:

"Full review: delegating to specialist agents in parallel. This typically takes 8–15 minutes. Use --review lean for faster single-session analysis."

Step 1 — Identify all domains the GDD touches

Read the GDD and identify every domain present. A GDD can touch multiple domains simultaneously — be thorough. Common signals:

Delegate to game-designer for all GDDs that describe gameplay mechanics or player-facing rules. Delegate to systems-designer for all GDDs that contain formulas or system interaction rules. These are the most common baselines — but not required for pure UI specs, audio specs, or lore documents. Use the domain table above to determine which specialists are truly relevant.

Step 2 — Delegate to all relevant specialists in parallel

CRITICAL: Delegation in this skill must target the named Codex custom-agent roles. Each role receives its own bounded context. Do not simulate specialist perspectives and claim that roles were consulted; a simulated review is not a specialist review.

Issue all Codex custom-agent delegations simultaneously. Start independent delegations together; do not wait for one before starting another.

Prompt each specialist adversarially:

"Here is the GDD for [system] and the main review's structural findings so far. Your job is NOT to validate this design — your job is to find problems. Challenge the design choices from your domain expertise. What is wrong, underspecified, likely to cause problems, or missing entirely? Be specific and critical. Disagreement with the main review is welcome."

Additional instructions per agent type:

• game-designer: Anchor your review to the Player Fantasy stated in Section B of this GDD. Does this design actually deliver that fantasy? Would a player feel the intended experience? Flag any rules that serve implementability but undermine the stated feeling.
• systems-designer: For every formula in the GDD, plug in boundary values (minimum and maximum plausible inputs). Report whether any outputs go degenerate — negative values, division by zero, infinity, or nonsensical results at the extremes.
• qa-lead: Review every acceptance criterion. Flag any that are not independently testable — phrases like "feels balanced", "works correctly", "performs well" are not ACs. Suggest concrete rewrites for any that fail this test.

Step 3 — Senior lead review

After all specialists respond, delegate to creative-director as the senior reviewer:

• Provide: the GDD, all specialist findings, any disagreements between them
• Ask: "Synthesise these findings. What are the most important issues? Do you agree with the specialists? What is your overall verdict on this design?"
• The creative-director's synthesis becomes the final verdict in Phase 4.

Step 4 — Surface disagreements

If specialists disagree with each other or with the creative-director, do NOT silently pick one view. Present the disagreement explicitly in Phase 4 so the user can adjudicate.

Mark every finding with its source: [game-designer], [economy-designer], [creative-director] etc.

Phase 4: Output Review

## Design Review: [Document Title]
Specialists consulted: [list agents consulted]
Re-review: [Yes — prior verdict was X on YYYY-MM-DD / No — first review]

### Completeness: [X/8 sections present]
[List missing sections]

### Dependency Graph
[List each declared dependency and whether its GDD file exists on disk]
- ✓ enemy-definition-data.md — exists
- ✗ loot-system.md — NOT FOUND (file does not exist yet)

### Required Before Implementation
[Numbered list — blocking issues only. Each item tagged with source agent.]

### Recommended Revisions
[Numbered list — important but not blocking. Source-tagged.]

### Specialist Disagreements
[Any cases where agents disagreed with each other or with the main review.
Present both sides — do not silently resolve.]

### Nice-to-Have
[Minor improvements, low priority.]

### Senior Verdict [creative-director]
[Creative director's synthesis and overall assessment.]

### Scope Signal
Estimate implementation scope based on: dependency count, formula count,
systems touched, and whether new ADRs are required.
- **S** — single system, no formulas, no new ADRs, <3 dependencies
- **M** — moderate complexity, 1-2 formulas, 3-6 dependencies
- **L** — multi-system integration, 3+ formulas, may require new ADR
- **XL** — cross-cutting concern, 5+ dependencies, multiple new ADRs likely
Label clearly: "Rough scope signal: M (producer should verify before sprint planning)"

### Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED]

This skill is read-only — no files are written during Phase 4.

Phase 5: Next Steps

Ask one concise question and wait for the answer for ALL closing interactions. Never plain text.

First prompt — what to do next:

If APPROVED (first-pass, no revision needed), proceed directly to the systems-index prompt, review-log prompt, then the final closing prompt. Do not show a separate "what to do" prompt — the final closing prompt covers next steps.

If NEEDS REVISION or MAJOR REVISION NEEDED, options:

• [A] Revise the GDD now — address blocking items together
• [B] Stop here — revise in a separate session
• [C] Accept as-is and move on (only if all items are advisory)

If user selects [A] — Revise now:

Work through all blocking items, asking for design decisions only where you cannot resolve the issue from the GDD and existing docs alone. Ask each required design-decision question in its own turn and wait for the answer. After the decisions are complete, present the exact proposed fix changeset and paths. Do not edit the GDD until the user separately authorizes that changeset.

After all revisions are complete, show a summary table (blocker → fix applied) and ask one concise question and wait for the answer for a post-revision closing prompt:

• Prompt: "Revisions complete — [N] blockers resolved. What next?"
• Note current context usage: if context is above ~50%, add: "(Recommended: a fresh task before re-review — this session has used X% context. A full re-review runs 5 agents and needs clean context.)"
• Options:
  • [A] Re-review in a new session — run $design-review [doc-path] after a fresh task
  • [B] Accept revisions and mark Approved — update systems index, skip re-review
  • [C] Move to next system — $design-system [next-system] (#N in design order)
  • [D] Stop here

Never end the revision flow with plain text. Always close with this prompt.

Tracking decisions — one decision per turn:

Ask the systems-index decision first and wait for the answer:

• Prompt: "May I update design/gdd/systems-index.md to mark [system] as [In Review / Approved]?"
• Options: [A] Yes — update it / [B] No — leave it as-is

Then ask the review-log decision and wait for the answer:

• Prompt: "May I append this review summary to design/gdd/reviews/[doc-name]-review-log.md? This creates a revision history so future re-reviews can track what changed."
• Options: [A] Yes — append to review log / [B] No — skip

Never combine these into a multi-select or "select any" prompt. Apply each write only after its own answer. If the review-log update is approved, append an entry in this format:

## Review — [YYYY-MM-DD] — Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED]
Scope signal: [S/M/L/XL]
Specialists: [list]
Blocking items: [count] | Recommended: [count]
Summary: [2-3 sentence summary of key findings from creative-director verdict]
Prior verdict resolved: [Yes / No / First review]

Final closing prompt — always show after all file writes complete:

Once the systems-index and review-log prompts are answered, check project state and show one final one-question prompt:

Before building options, read:

• design/gdd/systems-index.md — find any system with Status: In Review or NEEDS REVISION (other than the one just reviewed)
• Count .md files in design/gdd/ (excluding game-concept.md, systems-index.md) to determine if $review-all-gdds is worth offering (≥2 GDDs)
• Find the next system with Status: Not Started in design order

Build the option list dynamically — only include options that are genuinely next:

• [_] Run $design-review [other-gdd-path] — [system name] is still [In Review / NEEDS REVISION] (include if another GDD needs review)
• [_] Run $consistency-check — verify this GDD's values don't conflict with existing GDDs (always include if ≥1 other GDD exists)
• [_] Run $review-all-gdds — holistic design-theory review across all designed systems (include if ≥2 GDDs exist)
• [_] Run $design-system [next-system] — next in design order (always include, name the actual system)
• [_] Stop here

Assign letters A, B, C… only to included options. Mark the most pipeline-advancing option as (recommended).

Never end the skill with plain text after file writes. Always close with this prompt.