spec-new

name	spec-new
description	Write a new feature specification in specs/NNN-name/spec.md. Use when asked to "write a spec", "start a spec", "specify a feature", "create a specification", "spec out" a capability, or when a new feature request arrives that has no spec yet. Covers what and why, never how.

Write a specification

Turn a rough request into a specification precise enough that someone else could implement it without asking a single question.

Portable equivalent of the /spec-new prompt file. Prompt files work only in the VS Code Chat view; this skill works there and in the Copilot CLI and the coding agent. Same instructions.

The one hard rule

Write specs/NNN-name/spec.md and nothing else. No source, no tests, no config. If you catch yourself naming a class, a function, or a file path, stop — you have drifted from what into how, and that is the planner's job.

Read anything. Write only under specs/.

Method

1. Look for prior art first. Search the codebase. In this repository the answer to "can we add X" is frequently "X already exists under a different name" — the analytics layer has more in it than it appears from outside. Say what you found either way.

2. Ground it in the real floor if this is an analytics request. Use the slotsight MCP tools to look at actual numbers. A spec written against real data beats one written against assumptions, and you will often discover the premise is wrong.

3. Ask about anything that would change the design. Scope, users, and what "good" looks like — not implementation preferences. One round of questions now is worth ten during implementation.

4. Write acceptance criteria a test could be derived from mechanically.

❌ "The floor map should be fast and easy to read." ✅ "1. Renders 840 machines in under 500 ms on a 90-day window. 2. Each machine is coloured by peer_index band, never raw WPUPD. 3. Colour is paired with a shape or label so it is legible without colour vision."

5. Say what is out of scope. Explicitly. That list prevents more rework than the in-scope one.

Structure

# NNN — <Title>

**Status:** Draft
**Created:** YYYY-MM-DD

## Problem
What is wrong or missing today, and for whom. Evidence if you have it.

## Users
Who is affected. Be specific: "slot floor manager", not "user".

## Desired outcome
What is true after this ships that is not true now.

## Acceptance criteria
1. Numbered. Independently verifiable. Mechanically testable.

## Out of scope
What this deliberately does not do.

## Open questions
Anything that would change the design if answered differently.

## Constraints
Repository rules that bind this work.

Constraints every spec inherits

From the constitution. Restate any that are load-bearing for this feature:

• Analytics stay deterministic and LLM-free. If a spec requires the model to compute something, the spec is wrong.
• Rank and colour on peer_index, never floor_index.
• Money is integer cents.
• No player data. If a request needs PII, say so plainly and stop.
• Anything showing market data must declare it synthetic.

Numbering

Next free specs/NNN-short-name/. Check what exists first. Never reuse a number.

Next

When the spec is written, the next step is to plan it — see the spec-plan skill.