Polish Spec

# Skill: polish-spec

Review a spec file collaboratively with the human. Claude surfaces issues and asks clarifying questions; the human responds; Claude folds answers into the spec. Repeat until the human says stop or no moderate-or-higher issues remain.

## Finding the spec

If a path argument is given, use it. Otherwise, infer from context: look for the spec most recently discussed or the latest `specs/*/spec.md` by modification time.

## What to review

Read the spec fully. Also read `context/Architecture.md` to check for architectural conflicts. Identify every issue and open question. For each, assign a severity:

- **Blocking** — would cause the implementer to make a wrong or contradictory decision, or cannot be implemented as written
- **Significant** — ambiguous, underspecified, or likely to produce bugs or design regret
- **Minor** — polish, clarity, or nice-to-have

## Categories of issues

**Gaps**: something the implementer will need to know that isn't specified (e.g., what happens on error, how a field is initialized, what a term means)

**Contradictions**: two parts of the spec that conflict

**Architectural conflicts**: spec decisions that conflict with `context/Architecture.md`

**Design questions**: choices the spec makes that seem worth examining — not necessarily wrong, but worth confirming the author intended them (e.g., "this means X will never be possible — is that intentional?")

**Clarifications needed**: things Claude genuinely doesn't understand well enough to implement

## Loop

### 1. Present issues

After reading, present findings in a single message:
- List each Blocking/Significant issue with a short description and your proposed resolution or question
- List Minor issues briefly at the end (optional — skip if the list would be overwhelming)
- For design questions, frame as "This implies X — is that intentional?"
- Do NOT edit the spec yet

### 2. Wait for human response

The human will answer questions, accept proposals, reject proposals, or redirect. Do not proceed until they respond.

### 3. Fold in

Based on the human's answers:
- Edit the spec to incorporate confirmed resolutions
- If the human rejects a proposed fix, note it and move on (don't re-argue)
- If an answer reveals new questions, include them in the next round

### 4. Check for remaining issues

After editing, re-read the spec. If any Blocking or Significant issues remain unresolved, go back to step 1 with the remaining issues only. If the human says stop, stop.

## Escalate rather than guess when

- A question touches on game rules, world content, or design intent that Claude cannot infer from context
- Two reasonable interpretations would lead to meaningfully different implementations
- The issue requires looking up reference material Claude doesn't have

## Report format

Start each round with a brief header:

Round N — [count] blocking, [count] significant, [count] minor

Then list issues. Use this format per issue:

[Severity] [Category]: [description] → Proposed: [what Claude would do] — or "Needs your input: [question]"

When done (human says stop or no B/S issues remain), output:
"Spec is ready for planning." with a one-line summary of what changed.