game-design-doc-creator

name	Game Design Doc Creator
description	Create design documents for Stapledons Voyage game features. Use when user asks to create a design doc, plan a feature, or document game mechanics. Handles both planned/ and implemented/ docs.

Game Design Doc Creator

Create well-structured design documents for Stapledons Voyage game features.

Quick Start

Most common usage:

# User says: "Create a design doc for NPC pathfinding"
# This skill will:
# 1. Ask for key details (priority, complexity)
# 2. Create design_docs/planned/npc-pathfinding.md
# 3. Fill template with proper structure
# 4. Guide you through customization

When to Use This Skill

Invoke this skill when:

• User asks to "create a design doc" or "plan a feature"
• Before implementing new game mechanics
• Documenting world generation algorithms
• Planning NPC AI behaviors
• Designing rendering/visual features

Available Scripts

scripts/create_planned_doc.sh <doc-name> [version]

Create a new design document in design_docs/planned/.

scripts/move_to_implemented.sh <doc-name> <version>

Move a design document from planned/ to implemented/ after completion.

Workflow

1. Gather Requirements

Ask user:

• What game feature are you designing?
• What game systems does it affect? (world, NPCs, rendering, input)
• Estimated complexity? (simple, medium, complex)
• Any AILANG limitations to work around?

2. Game Vision Alignment

Every feature should be scored against the game's core pillars.

IMPORTANT: Before creating any design doc, read these files maintained by game-vision-designer:

File	Purpose	When to Check
core-pillars.md	Authoritative pillar definitions	Always - score feature against each
design-decisions.md	Prior decisions & rationale	Check for relevant constraints
open-questions.md	Unresolved design questions	See if feature touches these
game-vision.md	Full game design document	Deep context when needed

Score against each pillar in core-pillars.md:

Pillar	Question
Time Dilation Consequence	Does this reinforce irreversible time choices?
Civilization Simulation	Does it enhance galaxy-scale simulation?
Philosophical Depth	Does it add moral/philosophical decisions?
Ship & Crew Life	Does it connect to finite crew narrative?
Legacy Impact	Does it contribute to Year 1,000,000 report?
Hard Sci-Fi Authenticity	Does it maintain scientific plausibility?

Feature types:

• Gameplay features should score positively on multiple pillars
• Engine/Infrastructure features can score N/A on most pillars (they're enabling tech)
• No feature should score negatively on any pillar (violates game vision)

Check design-decisions.md for:

• Prior decisions that constrain this feature
• Rejected alternatives (don't re-propose without new justification)
• Related features and how they were resolved

3. Physics-First Design (CRITICAL)

This is a hard sci-fi game. All visual effects must be based on real physics.

Real Physics (USE THESE)

Effect	Physics Basis	When to Use
SR Doppler Shift	Light wavelength changes with relative velocity	Relativistic travel
SR Aberration	Stars appear to bunch forward at high velocity	High-speed scenes
GR Lensing	Light bends around massive objects	Near black holes, neutron stars
GR Redshift	Light escaping gravity wells shifts red	Near massive objects
Time Dilation	γ = 1/√(1-v²/c²)	All relativistic travel
Parallax	Distant objects move slower than near ones	Depth perception

Hollywood Conventions (NEVER USE)

Rejected Effect	Why It's Wrong	What to Use Instead
Star Streaks	Stars are too distant for motion blur	SR aberration (stars bunch forward)
Radial Motion Blur	No physical basis at relativistic speeds	SR Doppler shift (color change)
Warp Tunnels	Pure fantasy, no physics	Actual SR/GR visual distortion
Sound in Space	No medium for sound waves	Silence, or ship interior sounds
Engine Glow Trails	No medium to illuminate in vacuum	Point-source engine light only
Instant Communication	Violates light speed limit	Time-delayed messages
Artificial Gravity Plates	No known physics	Rotation or acceleration

Physics Validation Checklist

Before finalizing any visual/physics design:

• Is this effect based on real physics?
• Can I cite the equation or principle?
• Would a physicist approve?
• If "artistic license" is needed, is there a narrative justification?

Example narrative justification: Lower velocities (0.1c-0.5c instead of 0.9c) because "the AI pilot slows for crew sightseeing" - physics is still accurate, just at visible intensities.

4. Engine Capabilities Reference

Before designing, know what's already available:

Reference	Contents
engine-capabilities.md	Complete engine reference
gr-effects.md	GR physics & shaders
ai-handler-system.md	AI effect & providers

Available Engine Features:

• DrawCmd: Sprite, Rect, Text, IsoTile, IsoEntity, GalaxyBg, Star, Ui, Line, Circle, TextWrapped
• Effects: Debug, Rand, Clock, AI (Claude/Gemini/stub backends)
• Assets: Animated sprites, Audio (OGG/WAV), Fonts (TTF)
• Shaders: SR warp (Doppler, aberration), GR warp (lensing, redshift), bloom, vignette
• Physics: Lorentz factor (γ), time dilation, gravitational redshift, Schwarzschild radius

5. Consider AILANG Constraints

Important for this project: All game logic is written in AILANG. Consider:

• No mutable state - must use functional updates
• No loops - must use recursion (with depth limits!)
• Limited data structures - lists only, no arrays
• Known issues - check CLAUDE.md for current limitations

6. Design Doc Structure

Game-specific sections:

• Game Vision Alignment: Score against core pillars from docs/vision/core-pillars.md
• Prior Decisions: Reference relevant entries from docs/vision/design-decisions.md
• Physics Validation: (for visual features) What real physics principles apply?
• Feature Overview: What gameplay does this enable?
• AILANG Implementation: Types, functions, effects needed
• Engine Integration: How Go/Ebiten renders this
• Performance: Recursion depth, list operations needed
• Testing: How to verify the feature works

When creating a design doc:

1. Read docs/vision/core-pillars.md and score the feature
2. Check docs/vision/design-decisions.md for constraints
3. If this doc makes new design decisions, log them via game-vision-designer

For visual/physics features, include:

## Physics Basis
- Effect: [name]
- Principle: [cite equation or physics concept]
- Reference: [link to physics explanation]

## Rejected Alternatives
| Hollywood Effect | Why Rejected |
|------------------|--------------|
| [effect] | [physics reason] |

7. Example: NPC Movement Design Doc

# NPC Movement System

## Status
- Status: Planned
- Priority: P1
- Estimated: 2 days

## Game Vision Alignment

Checked against [core-pillars.md](docs/vision/core-pillars.md):

| Pillar | Alignment | Notes |
|--------|-----------|-------|
| Time Dilation Consequence | N/A | Infrastructure feature |
| Civilization Simulation | ✅ Supports | NPCs populate civilizations |
| Ship & Crew Life | ✅ Supports | Crew members use this system |
| Hard Sci-Fi Authenticity | N/A | No physics implications |

**Prior Decisions:** None directly relevant in design-decisions.md.

## Feature Overview
NPCs should move around the world grid, avoiding obstacles.

## AILANG Implementation

### Types (in sim/world.ail)
```ailang
type Direction = North | South | East | West
type MoveResult = Moved(Coord) | Blocked(string)

Functions (in sim/npc_ai.ail)

export pure func move(npc: NPC, dir: Direction, world: World) -> MoveResult
export pure func pathfind(npc: NPC, target: Coord, world: World) -> [Direction]

Engine Integration

• Go code reads NPC positions from World state
• Renders sprites at grid positions * tile size

Performance Concerns

• Pathfinding recursion: A* with depth limit
• List operations: O(n) for each tile lookup

Success Criteria

• NPCs can move in 4 directions
• Movement blocked by obstacles
• No recursion overflow with 64x64 grid

## AILANG Feedback Integration

**If you encounter AILANG limitations while designing:**

1. Note the limitation in the design doc
2. Design a workaround
3. Report to AILANG core via `ailang-feedback` skill:
   ```bash
   ~/.claude/skills/ailang-feedback/scripts/send_feedback.sh feature \
     "Feature needed for <game feature>" \
     "Description of what would help" \
     "stapledons_voyage"

Document Locations

design_docs/
├── planned/              # Future features
│   ├── feature.md
│   └── v0_1_0/           # Targeted for game v0.1.0
├── implemented/          # Completed features
│   └── v0_1_0/
└── README.md             # Feature index

Best Practices

1. Start with AILANG Types

Define your data structures first - they drive the implementation.

2. Plan for Recursion Limits

Any operation on 64x64 grid (4096 tiles) needs careful design.

3. Test with ailang check Early

Type-check your planned code snippets before committing to the design.

4. Link to ailang prompt

Reference ailang prompt output when documenting AILANG syntax.

Notes

• All game logic is AILANG, engine is Go/Ebiten
• Design docs should include AILANG code snippets
• Document workarounds for AILANG limitations
• Report feature requests to AILANG core