/create-specs

Synced verbatim from the repo on every site build. Edit the source file on GitHub (link in the page footer); do not edit the rendered copy here.

Description

Creates a business-level spec for a new feature or task. Does not require technical knowledge — the developer describes what needs to be done in business terms.

The Spec Analyzer reads existing specs and code if needed to understand the context, and warns about any incompatibilities with existing features before creating the spec.

Invoked by

Developer

Agent

Spec Analyzer

Input

A business description of the feature or task to implement. No technical details required.

Example:

“I want users to be able to invite other users to a board by email”

Steps

1. Receive the business description from the developer
2. Read {project-name}-docs/specs/INDEX.md to understand all existing features at a glance
3. Identify which existing specs might have incompatibilities based on the index (same aggregate, same service, or overlapping UI area) 3b. Duplicate detection (load-bearing). When the new business description’s ## Abstract.business_summary semantically overlaps (~80% or more) with any existing INDEX row whose Status is Implemented or Implemented 📦, STOP and ask the developer via AskUserQuestion how to proceed:
   • (a) Extend the existing spec via /refine-specs on the existing file (and document the extension in ## Refinement history).
   • (b) Create a follow-up -fix-specs.md for non-trivial bug-fix or enhancement that should retain its own spec.
   • (c) Duplicate intentionally — the developer provides a one-paragraph differentiation rationale that goes into the new spec’s ## Abstract.business_summary.
   • (d) Abort — the developer realizes the feature already exists. Never silently create a duplicate spec — duplicate INDEX rows pollute the lifecycle and break the smoke check that asserts INDEX uniqueness.
4. Deep-read only the identified specs — do not read specs that clearly have no overlap
5. Read relevant code if needed to better understand the existing implementation
6. Detect and warn the developer about any incompatibilities with existing features
7. Ask clarifying questions if business information is missing or ambiguous. All multi-option questions MUST be delivered via the AskUserQuestion tool (UI dropdown) — never as inline Choose: a/b/c chat prose. Same rule applies to the duplicate detection in Step 3b, the PII detection in Step 7b, and the caching opportunity check in Step 8. Free-form clarifications (open-ended “what should X mean?”) use chat. 7b. PII detection (load-bearing). Scan the business description and User Stories for keywords that indicate personal data capture: email, phone, name, address, birthday, birthdate, national id, passport, nif, dni, ssn, credit card, iban, account number, geo, location, coordinates, photo, selfie, biometric, fingerprint, medical, health, child, minor, gender, ethnicity, religion. When at least one match exists:
   • Set Abstract.has_pii: true.
   • Populate ## PII Inventory per the schema in templates/feature-specs-template.md § “PII Inventory” — one row per field with Tier (Public / Internal-PII / Sensitive-PII / Derived per standards/gdpr-pii.md), Purpose, Retention, Lawful basis, Sub-processors.
   • Cross-reference with {project-docs}/pii-inventory.md. Surface to the developer (via AskUserQuestion) any field that contradicts an existing inventory row (e.g. tier mismatch — was Internal, now feature stores it for a longer retention that pushes it to Sensitive). When no keyword matches, set Abstract.has_pii: false and omit ## PII Inventory. Skip silently — never ask “do you store PII?” when the description clearly does not.
8. Caching opportunity check (conditional). Evaluate whether this feature has a plausible caching benefit — trigger only if it involves a read-heavy endpoint, a computed value that depends on multiple aggregates or external APIs, a public resource servable at the edge, or a rate-limiter/idempotency mechanism. When triggered, ask the developer: (a) maximum tolerated staleness, (b) the write that invalidates the value, (c) whether the response is shared across users or per-user. Record the answers under Business Rules so refine-specs can later translate them into a concrete cache strategy. If the feature is clearly a write-only flow, one-off admin action, or otherwise not caching-relevant, skip this step silently — never ask for the sake of asking. See ../standards/caching.md → “Spec-time caching decision”
9. Create the spec file once all information is clear
10. Update {project-name}-docs/specs/INDEX.md — add a row for the new spec per the schema declared in templates/feature-specs-template.md § Status (the closed lifecycle enum is the source of truth for the INDEX Status column). Mandatory columns: Aggregate, Spec, Status, Date, Summary. Status value at create-specs time is always Pending implementation.
11. Self-validation gate (light) — before exiting, verify the spec contains: ## Status with value Pending implementation, ## Abstract with all 5 fields populated (business_summary, affected_aggregates, has_pii, has_external_integrations, complexity_estimate), ## Business Description, ## Affected Aggregate(s), ## Affected Service(s), ## User Stories, ## Business Rules, ## Out of Scope, ## Dependencies. When Abstract.has_pii: true, the spec MUST also declare ## PII Inventory with at least one row (per standards/gdpr-pii.md). Technical Details is empty (the create-specs guardrail). Failure exits with ## Status: blocked in the spec — the developer resolves the gap and re-runs /create-specs. The full structural validation runs in /refine-specs Step 14 once Technical Details + plan + task exist; this light gate catches the obvious gaps that would otherwise propagate.

Output

• A business-level spec file: {project-name}-docs/specs/{Aggregate}/{feature-name}-specs.md
• A warning report if incompatibilities with existing features are detected

Token Usage Report

After completing, list the files you read and display: Estimated input tokens: ~{lines_read × 8}

Sections to fill in the spec file

Fill only these sections — use the template at ai-standards/templates/feature-specs-template.md:

Section	Fill?
Status	Yes — always Pending implementation
Abstract	Yes — five fields (business_summary, affected_aggregates, has_pii, has_external_integrations, complexity_estimate). When has_pii: true, also fill ## PII Inventory (see Step 8b below)
Business Description	Yes
Affected Aggregate(s)	Yes
Affected Service(s)	Yes — service names only, no technical detail
User Stories	Yes
Business Rules	Yes
Out of Scope	Yes
Dependencies	Yes — feature-level only (e.g. “Board CRUD must be implemented”)
Technical Details (and all subsections)	NO — leave empty with the placeholder comment

STOP before Technical Details. That section and everything under it (API endpoints, data model, domain architecture, frontend architecture, folder structure, migrations, etc.) is filled exclusively by refine-specs. Writing technical content in create-specs skips a required step and produces specs that have not been validated against the actual codebase.

Context Checkpoint

After completing this command, evaluate whether the conversation context is getting heavy (many files read, long conversation history, multiple features discussed). If so, suggest to the developer:

“The spec is ready. To keep context fresh and avoid token waste, I recommend opening a new session and running: /refine-specs for {spec-file-path}”

If context is still light (e.g. this was a short conversation with a single feature), it’s fine to continue in the same session.