create-spec

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 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 an obligation?
5. Every exit keeps the promise. Walk the error return, the retry, the timeout, the partial write, the concurrent caller, the second entry. The guarantee must survive all of them, not just the happy path.
6. The refusals are real. What does this door make impossible? Are the illegal states unrepresentable, or merely checked and trusted?
7. The trust transition is explicit and singular. If untrusted becomes trusted or authority increases, does it happen here — and only here?
8. Irreversible effects pass one chokepoint. Is this the single dominating door for the effect it guards? If the effect can be reached another way, that other way is the bug.
9. The airlock is at the boundary. Validation, authorization, conversion, and the error boundary live at the door, leaving the inside free to trust its own invariants. Defensive code deep within means the boundary is misplaced.
10. A stranger could reconstruct intent. Could someone read this door alone — name and signature, not the body — and know what it is for and what it owes?

The joint is the same at every boundary

settle_payment in process, POST /v1/payment_intents/{id}/capture over REST, and Billing.SettlePayment over gRPC are one door, three transports, one name. When the function, the route, and the RPC method disagree about what the joints are, at least one of them is naming a tool — flag it. On the wire, the HTTP verb is honesty the protocol gives you for free (GET is safe, PUT/DELETE are idempotent, POST is neither — which is exactly why money doors carry an Idempotency-Key), and the status code is the door's honest exit (201 created, 204 done, 202 accepted; 409/412 are real refusals). The cardinal lie is 200 OK wrapping {"error": ...}. Authentication is one gate at the edge so every handler behind it may trust it speaks to a known caller.

<EXTREMELY_IMPORTANT>

• Please use your ask_user_question tool to provide a rich interface to ask the user for their input on a question.
• Please DO NOT implement anything in this stage, just create the comprehensive spec as described below.
• When writing the spec, DO NOT include information about concrete dates/timelines (e.g. # minutes, hours, days, weeks, etc.) and favor explicit phases (e.g. Phase 1, Phase 2, etc.).
• The spec MUST treat its entrypoint set as a first-class artifact. Section 5 is built around the doors (typed signatures, named failures, refusals expressed in types) and must pass the rubric above. Do not let intent leak into mechanism: a reviewer should reconstruct the system's purpose from §4.4 and §5.1 alone.
• If the spec is for a workflow with reviewer gates plus final actions (for example PR/MR/review creation, release tagging, deployment, or publication), explicitly separate implementation/review acceptance from those post-approval final actions. The workflow design should tell reviewers/reducers to approve and stop the implementation loop when implementation and validation criteria are proven and only an explicitly authorized final action remains; carry that remainder as a next action/final-action field instead of another implementation iteration.
• If the spec is for a workflow or workflow prompt refactor, require local, action-oriented stage/reviewer/reducer prompts. A model stage sees its prompt, artifacts, tools, and reads — not the workflow graph's name or surrounding implementation details unless explicitly provided — so prefer instructions like "review the current code delta" or "create/update the review request" over implementation-specific workflow nicknames unless a name is user-visible context or materially changes behavior.
• Once the spec is generated ask questions one at a time OR in logical groups:
  • Refer to section "## 9. Open Questions / Unresolved Issues", go through each question one by one, and use contrastive clarification (presenting 2-3 specific options with concrete tradeoffs) rather than open-ended questions. This means presenting interpretations like "(A) Option X — tradeoff Y" and "(B) Option Z — tradeoff W" instead of asking "what do you think about X?". Update the spec with the user's answers as you walk through the questions.
  • Interview the user relentlessly about every aspect of this plan/spec until you reach a shared understanding with them. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer (i.e., contrastive clarification). Pay special attention to the doors: every disagreement about what a joint is, what a door promises, what it refuses, or where a dangerous effect is funneled is a question worth resolving with the user.
  • If a question can be answered by exploring the codebase, explore the codebase instead and confirm with the user that this is their inferred intent.
• Finally, once the spec is generated and after open questions are answered, provide an executive summary of the spec to the user including the path to the generated spec document in the specs/ directory.
  • In the summary, list the door set by name alone (the stranger-across-time view) and call out which doors guard irreversible effects.
  • Encourage the user to review the spec for best results and provide feedback or ask any follow-up questions they may have.

</EXTREMELY_IMPORTANT>

Shape-first visual language

Specs stay in Markdown, but their visuals should use the smallest view that makes the key point clear. Skip a preamble, keep prose brief, and place each visual next to the short text it supports. Use one or several of these as needed; do not use all of them every time:

• Show logic or algorithms as indented text pseudocode, not prose alone.
• Show runtime control flow as an indented call tree.
• Show UI structure as a tsx component tree, including the state and module boundaries that matter.
• Show file responsibility or a broad refactor as a shallow text file tree.
• Show component interaction, control flow, or data flow with Mermaid.
• Use diff when the surrounding shape already exists and the point is what changes. Match the diff to the topic: component tree, file tree, call tree, or state/control flow.
• Show the whole block when most of it is new, omitted context would hide ownership or order, or the reader needs a copyable target shape.

For a visual UI, layout, state comparison, or concept too dense for Mermaid, allow one focused show-me-{description}.html artifact (diagram, infographic, or short slide deck). Match the product's colors, type, spacing, components, labels, and data; support desktop and mobile. Specs remain Markdown in specs/; HTML is an optional extra only when the page is the point. Open it with Atomic's bash tool and a portable opener:

if [ "$(uname -s)" = "Darwin" ] && command -v open >/dev/null 2>&1; then
  open "path/to/show-me-{description}.html"
elif [ "$(uname -s)" = "Linux" ] && command -v xdg-open >/dev/null 2>&1; then
  xdg-open "path/to/show-me-{description}.html"
else
  printf 'Open this file: %s\n' "path/to/show-me-{description}.html"
fi

[Project Name] Technical Design Document / RFC

Document Metadata	Details
Author(s)	!git config user.name
Status	Draft (WIP) / In Review (RFC) / Approved / Implemented / Deprecated / Rejected
Team / Owner
Created / Last Updated

1. Executive Summary

Instruction: A "TL;DR" of the document. Assume the reader is a VP or an engineer from another team who has 2 minutes. Summarize the Context (Problem), the Solution (Proposal), and the Impact (Value). Name the one or two doors at the heart of the change. Keep it under 200 words.

Example: This RFC proposes replacing our current nightly batch billing system with an event-driven architecture. Currently, billing delays cause a 5% increase in customer support tickets. The proposed solution introduces two money doors — authorize_charge (reversible hold) and settle_payment (irreversible capture) — as the single chokepoint for outbound money, reducing billing latency from 24 hours to <5 minutes while making double-charges structurally impossible.

2. Context and Motivation

Instruction: Why are we doing this? Why now? Link to the Product Requirement Document (PRD) and cite the relevant research/ documents.

2.1 Current State

Instruction: Describe the existing architecture and be honest about the flaws — including which existing doors leak (named for tools, dishonest compression, scattered danger). Pick the smallest view that makes the current state clear: a shallow file tree for ownership, a call tree for runtime flow, a component tree for UI structure, or Mermaid for interaction/data flow. Place the visual next to the short explanation and do not force a diagram when prose is clearer.

• Architecture: Currently, Service A communicates with Service B via a shared SQL database.
• Limitations: This creates a tight coupling; when Service A locks the table, Service B times out.
• Leaking doors (today): e.g. chargeCard(token, cents) is reachable from checkout, the retry job, and the admin panel — no one owns "charge exactly once." processPayment(...) -> bool collapses a declined card, a network failure, and a duplicate submission into the same false.

2.2 The Problem

Instruction: What is the specific pain point?

• User Impact: Customers cannot download receipts during the nightly batch window.
• Business Impact: We are losing $X/month in churn due to billing errors.
• Technical Debt: Danger is scattered; the boundary is misplaced, with defensive code deep inside the core instead of at the door.

3. Goals and Non-Goals

Instruction: This is the contract / Definition of Success. Be precise.

3.1 Functional Goals

• Users must be able to export data in CSV format.
• System must support multi-tenant data isolation.

3.2 Non-Goals (Out of Scope)

Instruction: Explicitly state what you are NOT doing. Remember: intent lives in what the door refuses — the doors you deliberately do not build are as much a statement of purpose as the ones you do. This prevents scope creep.

• We will NOT support PDF export in this version (CSV only).
• We will NOT migrate data older than 3 years.
• We will NOT expose a second path to move money; settle_payment remains the only chokepoint.

4. Proposed Solution (High-Level Design)

Instruction: The "Big Picture." Choose the smallest fitting view from the shape-first visual language above; use one or several only when each answers a different question. Types, trees, diffs, or Mermaid should define the shape, while brief prose explains why. Do not use a heavy styled diagram when a simpler view communicates the boundary.

4.1 System Architecture Diagram

Instruction: Show the system boundary and mark the airlock (the single edge where untrusted input becomes a trusted request). Use Mermaid for component interaction or data flow, a shallow file tree for module responsibility, a call tree for runtime control flow, or a component tree for UI structure. Show the whole block when most of it is new or omitted context would hide ownership or order.

flowchart TB
    User((User)) -->|untrusted request| Gateway["Gateway<br/>auth · validate · authorize<br/>airlock"]
    Gateway -->|trusted request| API["Core service<br/>trusts its invariants"]
    API --> DB[(Primary DB)]
    API -.-> Worker[Worker]
    Worker -.-> Ext["External provider<br/>irreversible effect"]

4.2 Architectural Pattern

Instruction: Name the pattern (e.g., "Event Sourcing", "BFF — Backend for Frontend", "Publisher-Subscriber").

• We are adopting a Publisher-Subscriber pattern where the Order Service publishes OrderCreated events, and the Billing Service consumes them asynchronously.

4.3 Key Components

Component	Responsibility	Technology Stack	Justification
Ingestion Service	Validates incoming webhooks	Go, Gin Framework	High concurrency performance needed.
Event Bus	Decouples services	Kafka	Durable log, replay capability.
Projections DB	Read-optimized views	MongoDB	Flexible schema for diverse receipt formats.