/create-spec

name: create-spec
description: "Create a detailed execution plan/spec/PRD for implementing features or refactors in a codebase, designed around the program's entrypoints, the doors that carry domain intent, by leveraging existing research in the codebase."
license: MIT
metadata:
    author: Atomic
    method-source: https://github.com/dmmulroy/skills/blob/main/tech-spec/SKILL.md

You are tasked with creating a spec for implementing a new feature or system change in the codebase by leveraging existing research in the **$ARGUMENTS** path. If no research path is specified, use the entire `research/` directory. IMPORTANT: Research documents are located in the `research/` directory — do NOT look in the `specs/` directory for research. Follow the template below to produce a comprehensive specification as output in the `specs/` folder using the findings from RELEVANT research documents found in `research/`. The spec file MUST be named using the format `YYYY-MM-DD-topic.md` (e.g., `specs/2026-03-26-my-feature.md`), where the date is the current date and the topic is a kebab-case summary. Tip: It's good practice to use the `codebase-research-locator` and `codebase-research-analyzer` agents to help you find and analyze the research documents in the `research/` directory. It is also HIGHLY recommended to cite relevant research throughout the spec for additional context.

Ask Clarifying Questions Before You Start

• If the user's request is vague or lacks necessary details, ask clarifying questions to gather more information before starting the spec creation process. This will help ensure that the spec is comprehensive and aligned with the user's needs.

Determine the compatibility posture

• Before decomposing the spec creation request, identify whether this project must preserve backward compatibility for real downstream users.
• If the user explicitly allows breaking changes, public API changes, cleanup, or says there are no real users/downstream dependencies, allow breaking changes.
• If the user mentions production users, published APIs, downstream consumers, migration safety, or compatibility requirements, disallow breaking changes.
• If the posture is not inferable from the request, ask the user once before continuing, using the available structured question tool when possible.
• Carry this posture into the spec creation plan, the final spec frontmatter, and a `## Backwards Compatibility` section in the final spec.
• When allowing breaking changes, document existing legacy behavior, compatibility shims, optional flags, and public APIs as current state, not as constraints future specs must preserve unless the user explicitly asks for preservation.
• When not allowing breaking changes, document public APIs, compatibility-sensitive surfaces, downstream callers, migration constraints, and behavior that future work must preserve.

Choose a working path before drafting

First inspect the context already available: the conversation, the requested research path, the `research/` documents, local docs, and the codebase. Choose the path that matches what is actually known:

• **Path A — Convert context to spec:** use this when the available conversation, research, docs, or code contain enough background to describe the problem, constraints, affected code, and acceptance criteria.
• **Path B — Grill first:** use this when the user wants a spec but the problem, constraints, design direction, affected code, or acceptance criteria are not yet clear. Do not invent architectural decisions.

If the codebase can answer a question, inspect it instead of asking the user. For Path B, do not write a full spec yet: state what context is missing, then use the existing `ask_user_question` and contrastive-clarification rules below (one question at a time or a logical group, with a recommended answer and concrete trade-offs). Once the answers and repository evidence provide enough context, run Path A.

Path A working method

When Path A is selected, work in this order and map the results into the numbered document headings below:

1. **Load standards and local context.** Inspect local vocabulary, module layout, domain concepts, errors, adapters, observability, runtime patterns, and test style. Check precedent before introducing a pattern, library, adapter, schema style, or test strategy; ground the findings in §2.1 and the door names. 2. **Extract the design problem.** Record current state, users and callers, pain point, goals, non-goals, constraints, invariants, affected systems, likely doors, operational concerns, risks, and open questions in §2, §3, and §9. Unknowns stay open questions. 3. **Explore materially different alternatives before locking the recommendation.** Compare interface shape, seam placement, ownership, call stack, runtime topology, and module boundaries—not just names. Record the comparison in §6 even though §6 appears after the recommended design in the document. 4. **Specify typed contracts.** Define the recommended doors, types, APIs, named failures, and refusals in §5.1–§5.3 while preserving the door rubric. 5. **Specify call stacks and data flow.** Put current and proposed paths, failure behavior, retry, cancellation, and idempotency where reachable into §5.4 using the visual formats below. 6. **Map files and modules.** List add/change/delete/test/config files and the responsibility each owns under §4 or §5. 7. **Plan vertical RGR TDD slices.** In §8, take each important public door or seam through a red behavior test, the smallest green implementation, and a refactor that preserves the behavior; do not write a horizontal all-tests-first plan. 8. **Produce the design-only spec.** Write `specs/YYYY-MM-DD-topic.md`; do not implement the change in this skill.

Design philosophy: a spec is a theory of its doors

The entrypoints of a program, read together, are the program's **theory of its own purpose**. Everything inside the boundary is mechanism — the *how*. Only at the