Lightweight design spec for small changes — tuning adjustments, minor mechanics, balance tweaks. Skips full GDD authoring when a system GDD already exists or the change is too small to warrant one. Produces a Quick Design Spec that embeds directly into story files.
This is the lightweight design path for changes that don't need a full GDD.
Full GDD authoring via /design-system is the heavyweight path. Use this skill
for work under approximately 4 hours of implementation — tuning adjustments,
minor behavioral tweaks, small additions to existing systems, or standalone
features too small to warrant a full document.
Output: design/quick-specs/[name]-[date].md
When to run: Anytime a change is too small for /design-system but too
meaningful to implement without a written rationale.
First, read the argument and determine which category this change falls into:
If the change does NOT fit these categories — it introduces a new system with
significant cross-system dependencies, requires more than one week of
implementation, or fundamentally alters an existing system's core rules — stop
and redirect to /design-system instead.
Present the classification to the user and confirm it is correct before proceeding. If there is no argument, ask the user to describe the change.
Before drafting anything, read the relevant context:
design/gdd/ for the GDD most relevant to this change. Read the
sections that this change would affect.design/gdd/systems-index.md exists. If it does, read it to
understand where this system sits in the dependency graph and what tier it
belongs to. If it does not exist, note "No systems index found — skipping
dependency tier check." and continue.design/quick-specs/ for any prior quick specs that touched this
system — avoid contradicting them.assets/data/ for the data file that
holds the relevant values.Report what was found: "Found GDD at [path]. Relevant section: [section name]. No conflicting quick specs found." (or note any conflicts found.)
Use the appropriate spec format for the change category.
Produce a single table:
# Quick Design Spec: [Title]
**Type**: Tuning
**System**: [System name]
**GDD Reference**: `design/gdd/[filename].md` — Tuning Knobs section
**Date**: [today]
## Change
| Parameter | Old Value | New Value | Rationale |
|-----------|-----------|-----------|-----------|
| [param] | [old] | [new] | [why] |
## Tuning Knob Mapping
Maps to GDD Tuning Knob: [knob name and its documented range].
New value is [within / at the edge of / outside] the documented range.
[If outside: explain why the range should be extended.]
## Acceptance Criteria
- [ ] [Parameter] reads [new value] from `assets/data/[file]`
- [ ] Behavior difference is observable in [specific context]
- [ ] No regression in [related behavior]
# Quick Design Spec: [Title]
**Type**: [Tweak / Addition]
**System**: [System name]
**GDD Reference**: `design/gdd/[filename].md`
**Date**: [today]
## Change Summary
[1-2 sentences describing what changes and why.]
## Motivation
[Why is this change needed? What player experience problem does it solve?
Reference the relevant MDA aesthetic or player feedback if applicable.]
## Design Delta
Current GDD says (quoting `design/gdd/[filename].md`, [section]):
> [exact quote of the relevant rule or description]
This spec changes that to:
[New rule or description, written with the same precision as a GDD Detailed
Rules section. A programmer should be able to implement from this text alone.]
## New Rules / Values
[Full unambiguous statement of the replacement content. If this introduces
new states, list them. If it introduces new parameters, define their ranges.]
## Affected Systems
| System | Impact | Action Required |
|--------|--------|-----------------|
| [system] | [how it is affected] | [update GDD / update data file / no action] |
## Acceptance Criteria
- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]
- [ ] No regression: [the original behavior this must not break]
## GDD Update Required?
[Yes / No]
[If yes: which file, which section, and what the update should say.]
Use a trimmed GDD structure. Include only the sections that are directly necessary — skip Player Fantasy, full Formulas, and Edge Cases unless the system specifically requires them.
# Quick Design Spec: [Title]
**Type**: New Small System
**Scope**: [1-2 sentence description of what this system does and doesn't do]
**Date**: [today]
**Estimated Implementation**: [hours]
## Overview
[One paragraph a new team member could understand. What does this system do,
when does it activate, and what does it produce?]
## Core Rules
[Unambiguous rules for the system. Use numbered lists for sequential behavior
and bullet lists for conditions. Be precise enough that a programmer can
implement without asking questions.]
## Tuning Knobs
| Knob | Default | Range | Category | Rationale |
|------|---------|-------|----------|-----------|
| [name] | [value] | [min–max] | [feel/curve/gate] | [why this default] |
All values must live in `assets/data/[appropriate-file].json`, not hardcoded.
## Acceptance Criteria
- [ ] [Functional criterion: does the right thing]
- [ ] [Functional criterion: handles the edge case]
- [ ] [Experiential criterion: feels right — what a playtest validates]
- [ ] [Regression criterion: does not break adjacent system]
## Systems Index
This system is not currently in `design/gdd/systems-index.md`.
[If it should be added: suggest which layer and priority tier.]
[If it is too small to track: state "This system is below systems-index
tracking threshold — quick spec is sufficient."]
Present the draft to the user in full. Then ask:
"May I write this Quick Design Spec to
design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md?"
Use today's date in the filename. The title should be a kebab-case description
of the change (e.g., jump-height-tuning-2026-03-10,
parry-window-addition-2026-03-10).
If yes, create the design/quick-specs/ directory if it does not exist, then
write the file.
If a GDD update is required (flagged in the spec), ask separately after writing the quick spec:
"This spec modifies rules in [System Name]. May I update
design/gdd/[filename].md — specifically the [section name] section?"
Show the exact text that would be changed (old vs. new) before asking. Do not make GDD edits without explicit approval.
After writing the file, output:
Quick Design Spec written to: design/quick-specs/[filename].md
Type: [Tuning / Tweak / Addition / New Small System]
System: [system name]
GDD update: [Required — pending approval / Applied / Not required]
Next step: This spec is ready for `/story-readiness` validation before
implementation. Reference this spec in the story's GDD Reference field.
Verdict: COMPLETE — quick design spec written and ready for implementation.
Quick Design Specs bypass /design-review and /review-all-gdds by
design. They are for small, low-risk, well-scoped changes where the cost of
the full review pipeline exceeds the risk of the change itself.
Redirect to the full pipeline if any of the following are true:
In those cases: "This change has grown beyond quick-spec scope. I recommend
using /design-system to author a full GDD for this."
/story-readiness [story-path] to validate the story before implementation begins — reference this spec in the story's GDD Reference field/dev-story [story-path] to implement once the story passes readiness checks/design-system [system-name] to author a full GDD instead