All Skills
/to-spec Phase 1: Understanding the Problem

The /to-spec Skill

Deconstructs business requirements into mathematically sound technical specifications, strict immutable DTO contracts, negative invariant barriers, and decoupled Clean Architecture seams.

"First. You have to understand the problem. What is the unknown? What are the data? What is the condition? Is it possible to satisfy the condition?" — George Pólya, How to Solve It (1945)
TERMINAL OR CHAT PROMPT 
/to-spec @docs/discovery/checkout-discovery.md Formulate formal technical specification, DTO contracts, and Clean Architecture seams.

What it does

to-spec grounds development in George Pólya's foundational theorem: "It is foolish to answer a question that you do not understand." It transforms user stories or discovery notes into formal, mathematically unambiguous specifications, decoupled Clean Architecture boundaries (Entities → Use Cases → Adapters → Frameworks), immutable DTO contracts, and the 5 UI States Matrix (Loading, Empty, Error, Partial, Populated).

It rigorously enforces the condition sanity check: it proves whether the condition is sufficient to determine the unknown, or if it is redundant or contradictory. It writes strictly one specification file to docs/spec/{slug}-spec.md and refuses to emit production code.

When to reach for it

Where the work currently lives decides whether this is the right skill:

The work is… Reach for
An approved PRD or discovery document ready for technical architecture /to-spec @docs/prd/{slug}-prd.md
A feature idea needing formal DTO schemas, ports, and invariants /to-spec
A bug rooted in a fundamentally broken architecture or contract /to-spec (architectural redesign)
A completed spec full of provisional assumptions needing interrogation /to-clarify @docs/spec/{slug}-spec.md
An approved spec ready to be decomposed into tracer bullets /to-plan @docs/spec/{slug}-spec.md
A routine mechanical change (≤ 2 files) /to-quick-fix

Prerequisites

  • Upstream Requirements: Discovery notes in docs/discovery/ or an approved PRD in docs/prd/.
  • Living Architecture Grounding: Inspects docs/ARCHITECTURE.md to respect existing module seams, naming conventions, and quality ratchets.
  • Strict Specification-Only Rule: Forbidden from modifying application source code in /src or /lib during this phase.

What one run does

A single specification authoring run follows six mathematical steps:

  1. Problem Triad Deconstruction: Maps user stories into technical requirements (REQ-XXX) and explicitly defines The Unknown, The Known Data, and The Condition.
  2. Condition Sufficiency Audit & Value Sourcing: Names the exact source for every persisted or computed value in the Positive Input Coverage Table.
  3. Clean Architecture Seam Mapping: Decouples domain entities from use cases, interface adapters, and external infrastructure drivers.
  4. Type-Driven Notation & 5 UI States Matrix: Makes invalid states unrepresentable via Value Objects; details Loading, Empty, Error, Partial, and Populated states.
  5. Reductio ad Absurdum (Negative Invariants): Assumes the negation of invariants to expose defensive barriers: unauthorized callers, payload corruptions, race conditions, and timeout cancellations.
  6. Single Specification Persistence: Writes strictly one canonical specification file to docs/spec/{slug}-spec.md.

Common questions

Can I jump straight from /to-spec into writing code?

No! The Pólya SDLC strictly forbids writing code directly after specification. An approved specification must first be planned into vertical tracer bullets via /to-plan and confirmed at The Pause Rule before coding begins.

Why does /to-spec insist on the 5 UI States for simple components?

Over 80% of frontend edge-case bugs stem from unhandled Empty or Error states. Specifying all 5 states up front guarantees that frontend views handle loading spinners, empty collections, and network retries gracefully.

What if some technical requirements are still uncertain?

The agent explicitly tags unverified decisions with > [!WARNING] [ASSUMPTION-XXX] tags. These assumptions are then systematically interrogated and resolved during /to-clarify.

It's working if

  • Exactly one specification file is written to docs/spec/{slug}-spec.md (zero shadow copies).
  • Every output attribute has an explicit source in the Positive Input Coverage Table.
  • Invalid states are rendered unrepresentable through strict typing and discriminated unions.
  • All provisional choices are explicitly tagged with numbered [ASSUMPTION-XXX] tags.
  • It writes zero application code in /src or /lib.

Where it fits

to-spec is Phase 1 in the main idea-to-ship pipeline: 

/to-explore → /to-prd → 📐 /to-spec → 🥊 /to-grill-me → /to-clarify → /to-plan → 🛑 PAUSE → /to-code → /to-review → /to-docs

It receives discovery notes from /to-explore or user stories from /to-prd. Once generated, it hands off to /to-grill-me for turn-by-turn sparring and /to-clarify for assumption interrogation or directly to /to-plan for tracer-bullet planning.