create-spec

What this skill does

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.

## 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 boundary does the code speak in terms of meaning — the *what* and the *why*. So the single most important thing this spec defines is not the mechanism inside the system, but the **set of doors** the system keeps: the functions, routes, and RPC methods through which untrusted input arrives and irreversible effects happen.

Two acts hide inside that claim, and a good spec performs both. One is *finding* the doors — discovering where the domain is already jointed, using the research in `research/` to learn what actually matters in the world the software serves. The other is *crafting* them — naming and shaping each door so it tells the truth about what lies behind it. Treat entrypoint design as the spine of the spec: a reviewer should be able to read the door set alone and reconstruct what the system is *for* before reading a single implementation detail.

Apply the five principles below to every entrypoint the spec introduces or changes, and run the rubric on each.

### The five principles

1. **Name a joint, not a tool.** A domain has seams — places reality is already divided into meaningful units (*authenticate a user, settle a payment, revoke access, publish a draft*). These exist before your code does. Name each door after such a joint, never after the mechanism behind it (`run the query`, `call the service`, `update the row`). A door named for a tool lets a reader learn *how it works* without ever learning *what it is for* — an ontological mismatch no clean mechanism repairs. Listen to the domain (and to the research), not to the code.

2. **Compress honestly, or not at all.** A door's value is roughly the ratio of mechanism hidden to surface exposed — *but only when the name promises exactly what the body delivers.* No less (so it hides no danger or incompleteness), no more (so it implies no guarantee it does not keep). A `save()` that sometimes silently doesn't, a `delete()` that soft-deletes, a `validate()` that mutates, a `getUser()` that creates one — each is a lie at the boundary, and lies at the boundary compound across every caller who reasons from the name. Encode cost and risk in the vocabulary (cheap-borrow vs allocate vs consume; `read` vs `read_exact`; panic-risk in the name).

3. **Intent lives in what the door refuses.** A boundary communicates as much by what it forbids as by what it allows. The *shape* of the door set — what it makes easy, what it makes impossible — is a direct statement of what the designers held sacred. Prefer making the illegal **unrepresentable** (in types and structure) over merely *checked* at runtime: a door that checks a rule trusts the caller; a door that makes the rule structurally necessary need trust no one. Use newtypes (`AccountId`, `OrderId`) over primitives, sum types over independent booleans, and capability-carrying types (an `AdminSession`, an `AuthorizedCharge`) that can only be produced by the door that earns them.

4. **Write for the stranger across time.** You craft the door not for the machine but for a competent stranger who arrives years from now, never meets you, and must understand the system's purpose before they dare change it. The governing test: **could they reconstruct the purpose of the system from the entrypoints alone, without reading a single body?** If they would have to read implementations to learn what the system *means*, intent has leaked out of the doors into the mechanism.

5. **Keep the dangerous doors few and honest.** The maturity of a system is visible in how few doors guard its irreversible effects — and how truthfully those doors are named. Every place money moves, access is granted, data is destroyed, a key is minted, a message is broadcast: funnel each effect through **one honestly-named chokepoint**, so the promise that guards it has exactly one home. Scatter danger across many small unnamed paths (every handler that can `chargeCard`, broad DB grants reaching `DROP TABLE`, ad-hoc `os.system(...)`, default-public storage) and no one — not even the authors — can say where the weight is carried.

### The rubric you run on every entrypoint in the spec

For each non-trivial entrypoint the spec introduces or changes, walk these in order. Stop at the first one you cannot answer cleanly — that is a finding, and it belongs in the spec (often in §5 as a constraint, or in §9 as an open question). Run it **forward** to audit a door you've drafted, and **backward** — asking what door each obligation deserves — to find the doors the system is still missing.

1. **Joint, not tool.** Is the name a unit of domain intent a non-engineer would recognize — not a description of the mechanism? If you can only name it in implementation terms, it's a step, not a door.
2. **The sentence holds.** Can you state its guarantee in one declarative sentence with no *and*? If not, it's fused (split it) or undefined (the most dangerous case — stop and find out what it actually promises).
3. **The name is honest.** Does it promise exactly what the body will deliver — hiding no danger, implying no guarantee it won't keep? List the ways the name could be read as a lie.
4. **Obligations are discharged.** Read the pre / invariant / post / *never* off the sentence. Does each obligation map to a real step in the design, and each step to a