agentleFS
Sign inStart free
ShiningPlagueShiningPlague/shiningplague-studio/skills/design-review/SKILL.md

design-review

Skill0 starsChanged 4 months agoMITView on GitHub

Use after authoring or updating a spec, GDD, or design document. Validates completeness, pillar alignment, MDA consistency, and flags design theory violations. Fires after /brainstorming or /design-system completes. ShiningPlague-adopted: adapts to the project's pillars ({{GDD_PATH}} pillars/MDA sections), spec paths, creative-director dispatch with CD-GDD-ALIGN gate.

155 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use playtest-report, brief-to-tasks and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • CoralGameSkill

    playtest-report

    Generates a structured playtest report template or analyzes existing playtest notes into a structured format. Use this to standardize playtest feedback collection and analysis.

    Also in 12 projects that use this

  • julianoczkowskiSkill

    brief-to-tasks

    Break a design brief into an ordered checklist of independently buildable tasks using vertical slices. Saves as a markdown checklist. Use when user wants to break down work, create tasks from a brief, plan implementation order, or mentions "tasks" or "breakdown".

    Also in 7 projects that use this

  • lilangMaxSkill

    soak-test

    Generate a soak test protocol for extended play sessions. Defines what to observe, measure, and log during long play sessions to surface slow leaks, fatigue effects, and edge cases that only appear after sustained play. Primarily used in Polish and Release phases.

    Also in 9 projects that use this

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 1 is distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 129 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the document under review

    line 35
  2. Very specific:

    Read {{GDD_PATH}} pillars section + MDA section

    line 36
  3. Very specific:

    Read data/_schemas/system_registry.json for related systems

    line 37
  4. Very specific:

    If system GDD: also read docs/gdd/systems-index.md for dependency context

    line 38
  5. Very specific:

    Every spec must have ## Expected outcomes at ship per project-local brainstorming convention.

    line 54
  6. Very specific:

    After APPROVE → propose /architecture-decision if the design needs locked decisions.

    line 63
  7. Very specific:

    After APPROVE → propose /writing-plans if the design is ready for implementation.

    line 64
  8. Very specific:

    After CONCERNS/REJECT → revise the spec, then re-run /design-review.

    line 66

“Common” is measured: kept by at least 6 in 10 of the 129 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Design Review

🌱 ShiningPlague-adopted. Originally Donchitos (barebones stub); battle-tested on a shipped Godot project. Upstream was a pointer-only file; the studio version is the full implementation — pillar alignment, MDA validation, creative-director dispatch, Expected Outcomes check.

Validates a design document against project pillars, MDA framework, and design theory. Chain-fires after /brainstorming (spec review) or /design-system (GDD review).

If an artifact named here is absent: say so plainly in one line, skip that step, and continue. Never invent the file to satisfy a checklist, and never fail a close because an optional artifact was never created.

Inputs

  • Document path — the spec or GDD to review
  • Game pillars — from {{GDD_PATH}} (or dedicated pillars doc when it exists)
  • MDA aesthetics — target aesthetic hierarchy from the GDD's MDA section

Procedure

1. Read Context

  • Read the document under review
  • Read {{GDD_PATH}} pillars section + MDA section
  • Read data/_schemas/system_registry.json for related systems
  • If system GDD: also read docs/gdd/systems-index.md for dependency context

2. Dispatch Creative Director

Spawn creative-director with gate CD-GDD-ALIGN from .claude/docs/director-gates.md. Pass: document path, pillars, MDA target, system's Player Fantasy section. Await verdict: APPROVE / CONCERNS / REJECT.

3. Validate Design Theory

Check for:

  • Dominant strategies — is there one option that's always best?
  • Economic imbalance — do costs and rewards make sense?
  • Cognitive overload — too many simultaneous mechanics?
  • Pillar drift — does this move away from what the game IS?
  • Ludonarrative dissonance — do mechanics contradict narrative themes?

4. Check Expected Outcomes

Every spec must have ## Expected outcomes at ship per project-local brainstorming convention. Verify it exists and is concrete (testable by the designer), not vague. Push back on outcomes like "better combat" — outcomes must be concrete enough for a playtester or editor user to verify in a 5-minute session.

5. Present Verdict

  • APPROVE — proceed to ADR or implementation
  • CONCERNS [list] — revise flagged sections, then re-review
  • REJECT [blockers] — fundamental redesign needed

Chain-Propose

After APPROVE → propose /architecture-decision if the design needs locked decisions. After APPROVE → propose /writing-plans if the design is ready for implementation.

After CONCERNS/REJECT → revise the spec, then re-run /design-review.

Project Paths

  • Specs: docs/specs/YYYY-MM-DD-<topic>-design.md
  • GDDs: {{GDD_PATH}} (master) or docs/gdd/<system>.md (per-system when split)
  • ADRs: docs/adr/NNN-<slug>.md
  • Director gates: .claude/docs/director-gates.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free