# Spec Create

> Use when turning a conversation or idea into docs/plans/<name>/spec.md. Synthesizes existing context into user stories, module design, testing decisions. Do NOT interview — just synthesize.

- Skill: `neumie/spec-create` (Agent Skill)
- Install (CLI): `npx skillmds@latest add neumie/spec-create`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neumie/spec-create/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: neumie (https://skillmd.com/u/neumie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/neumie/spec-create

---


# Spec Create

Synthesize the current conversation context and codebase understanding into a spec. Do NOT interview the user; just synthesize what you already know.

## Process

These commands run automatically when the skill loads — output replaces each line below:

- Current branch: !`git branch --show-current 2>/dev/null || true`
- CONTEXT.md: !`cat CONTEXT.md 2>/dev/null || true`

### 0. Determine `<name>`

Before anything else:

1. If the user passed a name as an argument (e.g. `/spec-create auth-system`), use that as `<name>`.
2. Otherwise derive `<name>` from the current branch above by stripping a leading type prefix (`feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `test/`, `ci/`, `perf/`). Example: `feat/auth-system` → `auth-system`.
3. If on `main`/`master`/`develop` with no argument passed, ask the user for an explicit name before continuing.

If this session included a `/grill-me` grilling, those crystallized decisions are in the conversation — use them. If `CONTEXT.md` content is present, use its vocabulary throughout the spec. Respect ADRs in the area you're touching. Also explore the repo to understand the current state of the codebase, if you haven't already.

### 1. Sketch modules and testing seams

Sketch out the seams where the feature should be tested. Prefer existing seams to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. Fewer seams are better; one seam is ideal.

Also sketch the major modules you will need to build or modify to complete the implementation. Follow the `codebase-design` skill for seam, interface, and deep-module vocabulary.

Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.

### 2. Write the spec

Use the template below and save it to `docs/plans/<name>/spec.md`:

```bash
mkdir -p docs/plans/<name>
```

Report the file path (`docs/plans/<name>/spec.md`) so the user can pass it to `/to-tickets` or directly to `/loop`.

## Spec Template

```markdown
## Problem Statement

The problem that the user is facing, from the user's perspective.

## Solution

The solution to the problem, from the user's perspective.

## User Stories

A LONG, numbered list of user stories. Each user story should be in the format of:

1. As an <actor>, I want a <feature>, so that <benefit>

This list should be extremely extensive and cover all aspects of the feature.

## Implementation Decisions

A list of implementation decisions that were made. This can include:

- The modules that will be built/modified
- The interfaces of those modules that will be modified
- Technical clarifications from the developer
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions

Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.

Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo.

## Testing Decisions

A list of testing decisions that were made. Include:

- A description of what makes a good test (only test external behavior, not implementation details)
- Which modules will be tested
- Prior art for the tests (i.e. similar types of tests in the codebase)

## Out of Scope

A description of the things that are out of scope for this spec.

## Further Notes

Any further notes about the feature.
```