# Game Improvement Loop

> Runs iterative game-improvement cycles from a player-experience goal: investigate, validate direction, create a PRD, implement, playtest, and feed observations into the next cycle. Use when the user asks to improve game feel, UX, player experience, character/system behavior, or playtest-driven iteration.

- Skill: `gil-1/game-improvement-loop` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add gil-1/game-improvement-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gil-1/game-improvement-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: gil-1 (https://skillmd.com/u/gil-1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gil-1/game-improvement-loop

---


# Game Improvement Loop

Improve this game through short evidence loops. Keep player experience central and adapt the loop to the game's genre, platform, controls, and design promise.

## Defaults

- Cycles: 3 unless user says otherwise.
- Playtest: 30 minutes per cycle unless user says otherwise.
- Log: `.scratch/game-improvement-loop/<YYYY-MM-DD>-<goal-slug>/cycle-N.md`.

Do not shorten a requested/default playtest unless user approves. If full playtest cannot run, mark cycle incomplete.

## Start Gate

Before PRD or code:

1. Read local rules, docs, prior playtests, tickets/PRDs, and code paths relevant to the player-facing behavior.
2. Research external references only when they help the requested goal.
3. Return concise direction brief:
   - player promise
   - behavior to improve
   - recommended direction plus key alternatives
   - likely data/state needs
   - primary player persona
   - observable playtest signs
   - cycle count and playtest duration
4. Wait for user validation.

After validation, continue through all cycles unless blocked or direction becomes impossible.

## Cycle

1. Frame hypothesis: promise, design bet, observable signs.
2. Research: code, docs, prior playtests, useful external sources.
3. Create spec with `to-spec`: hypothesis, persona, experience, non-goals, acceptance criteria, test/playtest plan.
4. Implement the cycle. If the spec already points to implementation-ready tickets, use `handle-tickets` and capture its PRs, branches, checks, blockers, and Codex outcomes. Otherwise use focused ticket-sized work with `implement`, then run `review-fix` and `codex-pr-review` when a PR exists. Keep slices vertical and playable.
5. Choose the playtest target from delivery evidence: delivery worktree, preview URL, merged default branch, or blocked awaiting merge. Playtest in the target runtime for requested duration. Prefer clean session, representative viewport/device, and existing automation harness when available.
6. Record evidence: method, runtime/build/URL, viewport/device, session id, start/end, duration, input count, transcript/log/screenshot paths, state contamination risk, and at least 5 relevant player-facing moments.
7. Decide verdict: `validated`, `mixed`, `invalidated`, or `incomplete`.
8. Turn strongest miss into next-cycle seed.

## Sub-Agents

Use sub-agents when they materially help and the work can be split cleanly. Run cycles sequentially because each cycle seeds the next.

Parallelize independent work inside a cycle: codebase research, design references, test/tooling inspection, asset review, or bounded implementation with non-overlapping files.

Worker brief must include direction, cycle number, persona, log path, ticket/PRD expectations, likely modules, verification commands, playtest duration, dirty-worktree warning, and required handoff.

## Cycle Log

```md
# Cycle N: <goal>

## Approved Direction
## Persona
## Hypothesis
## Research
## PRD
## Implementation
## Verification
## Playtest Evidence
## Observations
## Verdict
## Next Seed
## Blockers Or Fallbacks
```

## Finish

Summarize cycles, PRDs/tickets, PRs, worktrees or preview targets, checks, playtest evidence, verdicts, blockers, and next best improvement. State plainly if any cycle is incomplete.