prd-to-spec

name	prd-to-spec
description	Convert a PRD into a technical specification

Skill: prd-to-spec

Load Context

1. Read $ARGUMENTS for the feature name. If empty, ask the user.
2. Read docs/modules/<feature>/PRD.<feature>.md
3. Read docs/TECH_STACK.md for technology constraints
4. Read docs/modules/_module/SPEC._module.md as the template

Pre-checks

• If PRD does not exist → abort: "Please run /write-a-prd <feature> first."
• If PRD contains unresolved Open Questions → list them and ask: "The following questions are unresolved. Continue drafting the SPEC? Unresolved items will be marked TBD."
• If SPEC already exists → ask whether to overwrite. Abort on n.

Steps

Step 1: Analyse the PRD

Extract and organise internally:

• All Functional Requirements → map to API endpoints or business logic units
• Data entities mentioned → draft model fields
• Non-Functional Requirements → note as architectural constraints
• External dependencies (third-party services, other modules) → list as Dependencies

Step 2: Draft each SPEC section

Fill in sections in template order — do not skip any:

Data Models

• Define fields, types, and constraints (unique, nullable, etc.) for each entity
• Use TypeScript interface format

API Contracts

• For each endpoint: Method + Path, request body, response (success + all error codes)
• Error codes must be specific (400/401/403/404/409/422/500) — do not write "4xx"

Architecture

• Describe internal module layers (Controller / Service / Repository or equivalent)
• Describe the full data flow (request → response)

Dependencies

• Internal: other modules this depends on
• External: third-party packages or services, with purpose noted

Error Handling

• How errors are handled at each layer and how they propagate upward

Security Considerations

• Authentication method
• Input validation points
• Sensitive data handling

Step 3: Resolve ambiguities

If any technical decisions cannot be inferred from the PRD, list them and ask the user, for example:

The following decisions need confirmation:
1. Token storage: stateless JWT or session-based (Redis)?
2. Is password reset in scope for this iteration?

Incorporate answers into the relevant SPEC sections before continuing.

Step 4: Present and confirm

Show the complete SPEC to the user. Wait for confirmation or change requests.

Step 5: Save the file

Write file: docs/modules/<feature>/SPEC.<feature>.md

Inform the user: "SPEC saved. Next step: run /spec-to-tasks <feature>."

Error Handling

Situation	Action
PRD Functional Requirements section is empty	Abort — ask the user to complete the PRD first
Tech stack document is missing	Continue, but add a banner: "Tech stack unconfirmed — verify before implementing"
Cannot determine API structure	Write TODO: define endpoint in the relevant section and record in Open Questions

Done When

• docs/modules/<feature>/SPEC.<feature>.md exists
• All six sections present: Data Models, API Contracts, Architecture, Dependencies, Error Handling, Security
• Every API endpoint has a complete request/response definition
• User has confirmed the content