/prd-to-spec

name: prd-to-spec
description: "Transform a PRD into a technical SPEC document — architecture, API design, data model, error handling, and implementation contracts. Triggers on: prd-to-spec, prd to spec, prd转spec, 需求转设计, 需求转规格, generate spec from prd, design from prd, 技术方案, 设计方案."
user-invocable: true

prd-to-spec — PRD to Technical Specification

Transform a Product Requirements Document (PRD) into a detailed technical SPEC that an engineer or AI agent can implement against. The PRD says *what* to build; the SPEC says *how* to build it.

---

When to Use

• A `/prd` has been generated and you need to bridge the gap to implementation
• You want architecture decisions documented before coding starts
• Multiple developers/agents will implement the feature and need a shared contract
• You need to validate technical feasibility before committing to a PRD
• You want to catch design issues early — before code is written

---

The Job

1. **Locate PRD** — find or receive the PRD document 2. **Analyze context (optional)** — if a codebase exists, scan it to understand current architecture, patterns, and constraints 3. **Ask clarifying questions** — resolve technical ambiguities (max 3-5 questions) 4. **Generate SPEC** — produce a structured technical specification 5. **Review** — present to user for feedback and iteration 6. **Save** — write final SPEC to agreed location

---

Step 1: Locate PRD

Find the input PRD in one of these ways:

Provide the PRD to convert:

A. File path (e.g., tasks/prd-priority-system.md)
B. GitHub Issue URL
C. Paste PRD content directly
D. Auto-detect: scan tasks/ directory for recent PRDs

If auto-detecting, list available PRDs and let the user choose:

Found PRDs in tasks/:
  1. tasks/prd-priority-system.md (2024-03-15)
  2. tasks/prd-user-auth.md (2024-03-10)

Which PRD should I convert? [1/2]

---

Step 2: Analyze Context (Optional)

**Skip this step if no codebase exists yet** (greenfield project). In that case, the SPEC will propose architecture from scratch based on the PRD requirements and clarifying questions.

If a codebase exists, scan it to understand:

• **Existing architecture** — how the current system is structured
• **Tech stack** — languages, frameworks, libraries already in use
• **Patterns** — naming conventions, file organization, error handling approach
• **Database** — current schema, migration tool, ORM
• **API style** — REST/GraphQL/gRPC, authentication method, response format
• **Testing** — test framework, coverage patterns, test utilities

This ensures the SPEC aligns with the existing system rather than proposing incompatible solutions.

---

Step 3: Clarifying Questions

Ask only when the PRD leaves technical decisions ambiguous. Focus on:

• **Architecture choices** — where does this feature live? New service or extend existing?
• **Data storage** — new table? Extend existing? Cache strategy?
• **API design** — new endpoints? Extend existing? Breaking changes?
• **Dependencies** — any new libraries needed? Version constraints?
• **Performance** — expected load? Latency requirements? Batch size limits?

Format:

Technical questions before I generate the SPEC:

1. Where should the priority logic live?
   A. Extend existing TaskService
   B. New PriorityService
   C. Inline in controller
   D. Let me decide based on the codebase

2. Database migration approach?
   A. Add column to existing tasks table
   B. New priority table with FK
   C. JSON field on tasks
   D. Let me decide based on current schema

3. API versioning concern?
   A. Add to existing v1 endpoints
   B. New v2 endpoints
   C. No versioning needed

If user selects "let me decide" options, make the best choice based on codebase analysis and document the rationale in the SPEC.

---

Step 4: SPEC Document Structure

# SPEC: [Feature Name]

> Technical specification derived from: [PRD filename/link]
> Generated: [date] | Target branch: [branch] | Commit: [short-hash]

## 1. Summary

### 1.1 What This SPEC Covers
[One paragraph: what feature this specifies and the scope of implementation]

### 1.2 PRD Reference
- Source: [path or URL to PRD]
- User Stories covered: [US-001, US-002, ...]
- Functional Requirements covered: [FR-1, FR-2, ...]

### 1.3 Design Decisions Summary
| Decision | Choice | Rationale |
|----------|--------|-----------|
| ... | ... | ... |

---

## 2. Architecture

### 2.1 System Context
[Where this feature fits in the overall system — diagram or description]

### 2.2 Component Design
[New components/modules introduced, their responsibilities, and boundaries]

### 2.3 Module Interactions
[How new components interact with existing ones — sequence or data flow]

### 2.4 File Structure
[New files to create and existing files to modify]

src/ ├── services/ │ └── priority.service.ts [NEW] ├── controllers/ │ └── task.controller.ts [MODIFY: add priority endpoints] ├── models/ │ └── priority.model.ts [NEW] └── migrations/ └── 20240315_add_priority.ts [NEW]

---

## 3. Data Model

### 3.1 Schema Changes
[New tables, columns, indexes — with SQL or ORM notation]

### 3.2 Entity Definitions
[TypeScript interfaces / Go structs / Python dataclasses for new entities]

### 3.3 Relationships
[How new entities relate to existing ones — FK, embedded, reference]

### 3.4 Migration Plan
[Migration steps, backward compatibility, rollback strategy]

---

## 4. API Design

### 4.1 Endpoints

| Method | Path | Description | Auth | Request | Response |
|--------|------|-------------|------|---------|----------|
| ... | ... | ... | ... | ... | ... |

### 4.2 Request/Response Schemas
[Detailed shapes with field types, validation rules, and examples]

### 4.3 Error Responses
[Error codes, messages, and HTTP status codes for each failure mode]

### 4.4 Breaking Changes
[Any backward-incompatible changes and migration path for consumers]

---

## 5. Business Logic

### 5.1 Core Algorithms
[Step-by-step logi