/quick-design

name: quick-design
description: "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."
argument-hint: "[brief description of the change]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion
model: sonnet

Quick Design

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.

---

1. Classify the Change

First, read the argument and determine which category this change falls into:

• **Tuning** — changing numbers or balance values in an existing system with no

behavioral change (most minimal path). Example: "increase jump height from 5 to 6 units", "reduce enemy patrol speed by 10%".

• **Tweak** — a small behavioral change to an existing system that introduces no

new states, branches, or systems. Example: "make dash invincible on frame 1", "allow combo to cancel into roll".

• **Addition** — adding a small mechanic to an existing system that may introduce

1-2 new states or interactions. Example: "add a parry window to the block mechanic", "add a charge variant to the basic attack".

• **New Small System** — a standalone feature small enough that it has no

existing GDD and is under approximately one week of implementation work. Example: "achievement popup system", "simple day/night visual cycle".

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.

If there is no argument, ask the user to describe the change (plain text prompt), then classify it using the criteria above.

Present the inferred classification using `AskUserQuestion`:

• Prompt: "I've classified this as **[inferred type]** — [brief reason]. Is that correct?"
• Options:
• `[A] Yes — [inferred type] is correct`
• `[B] Tuning — changing numbers or balance values only`
• `[C] Tweak — small behavioral change to an existing system`
• `[D] Addition — adding a small mechanic to an existing system`
• `[E] New Small System — standalone feature, under one week of work`
• `[F] This is too large — redirect me to /design-system`

If [F]: stop. Verdict: **REDIRECTED** — use `/design-system` for this change. Otherwise: proceed with the selected type.

---

2. Context Scan

Before drafting anything, read the relevant context:

• Search `design/gdd/` for the GDD most relevant to this change. Read the

sections that this change would affect.

• Check whether `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.

• Check `design/quick-specs/` for any prior quick specs that touched this

system — avoid contradicting them.

• If this is a Tuning change, also check `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.)

---

3. Draft the Quick Design Spec

Use the appropriate spec format for the change category.

For Tuning changes

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]

For Tweak and Addition changes

# 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 re