prd-generator

What this skill does

# PRD Generator

Create Product Requirements Documents that focus on the **"What"** and **"Why"** — not the technical "How". Technical implementation details belong in the Technical Specification (Phase 0 of the full-stack-feature workflow).

> "A PRD should avoid anticipating or defining how the product will do it, in order to later allow designers and engineers to use their expertise to provide the optimal solution." — [Wikipedia](https://en.wikipedia.org/wiki/Product_requirements_document)

---

## The Job

1. Receive a feature description from the user
2. Ask 3-5 clarifying questions about goals, users, and scope
3. Generate a user-focused PRD (no code references!)
4. Save to `docs/prds/prd-[feature-name].md`
5. Present the PRD to the user for approval
6. On approval → Create a GitHub Epic Issue with the PRD content
7. Ask if User Stories should be created as Sub-Issues
8. On approval → Create Sub-Issues for each User Story

**Important:**
- Do NOT analyze the codebase — that's the Architect-Planner's job (Phase 0)
- Do NOT reference specific files, classes, tables, or endpoints
- Focus on user needs, business value, and acceptance criteria

---

## Step 1: Clarifying Questions

Ask only critical questions where the initial prompt is ambiguous. Focus on:

- **Problem/Goal:** What problem does this solve? Why now?
- **Target Users:** Who benefits from this feature?
- **Core Functionality:** What are the key user actions?
- **Scope/Boundaries:** What should it NOT do?
- **Success Criteria:** How do we know it's successful?

### Format Questions Like This:

```
1. What is the primary goal of this feature?
   A. Improve user onboarding experience
   B. Increase user retention
   C. Reduce support burden
   D. Other: [please specify]

2. Who is the target user?
   A. New users only
   B. Existing users only
   C. All users
   D. Admin users only

3. What is the MVP scope?
   A. Minimal — just the core functionality
   B. Standard — core + nice-to-haves
   C. Full — complete feature set
```

This lets users respond with "1A, 2C, 3B" for quick iteration.

---

## Step 2: PRD Structure

Generate the PRD with these sections:

### 1. Overview

Brief description of the feature and the problem it solves. Answer:
- What is being built?
- Why is it needed?
- Who is it for?

### 2. Goals

Specific, measurable objectives (bullet list). What does success look like?

### 3. User Stories

Each story needs:
- **Title:** Short descriptive name
- **Description:** "As a [user], I want [action] so that [benefit]"
- **Acceptance Criteria:** Verifiable checklist from the user's perspective

**Format:**
```markdown
### US-001: [Title]
**Description:** As a [user type], I want [action] so that [benefit].

**Acceptance Criteria:**
- [ ] User can [observable behavior]
- [ ] System displays [expected feedback]
- [ ] [Edge case] is handled gracefully
```

**Rules for User Stories:**
- Write from the **user's perspective**, not the developer's
- Describe **observable behavior**, not implementation
- Keep stories small enough for one focused session
- **NO code references** — no file names, class names, database tables, or API endpoints

**Good Examples:**
- "As a user, I want to see my task's priority at a glance so I can focus on what's urgent"
- "As an admin, I want to export user data as CSV so I can analyze it in Excel"

**Bad Examples (too technical):**
- ~~"Add `priority` field to Task model"~~ → This belongs in Technical Spec
- ~~"Extend `OrderService` with `cancelOrder()` method"~~ → This belongs in Technical Spec
- ~~"Create migration to add column"~~ → This belongs in Technical Spec

### 4. Functional Requirements

Numbered list of **what** the system must do (not how):
- "FR-1: The system must allow users to..."
- "FR-2: When a user performs X, the system must respond with Y..."

Be explicit and unambiguous, but stay at the functional level.

### 5. Non-Goals (Out of Scope)

What this feature will NOT include. Critical for managing scope and expectations.

### 6. User Experience Considerations

- Key user flows and interactions
- Important UI states (loading, empty, error)
- Accessibility requirements
- Mobile/responsive considerations

**Note:** This is NOT a wireframe or design spec. Just describe the expected experience.

### 7. Constraints & Dependencies

High-level constraints that affect the feature:
- Business rules or policies
- External dependencies (third-party services, APIs)
- Timing constraints (must ship before X)
- Compliance requirements (GDPR, accessibility)

**Note:** Do NOT include technical architecture here. That's the Architect-Planner's job.

### 8. Success Metrics

How will success be measured?
- "Reduce time to complete X by 50%"
- "Increase conversion rate by 10%"
- "Decrease support tickets about Y by 30%"

### 9. Open Questions

Remaining questions or areas needing clarification before implementation.

---

## Step 3: User Approval & GitHub Epic Issue

After saving the PRD file, present it to the user and ask:

```
PRD gespeichert unter docs/prds/prd-[feature-name].md

Soll ich ein GitHub Issue (Epic) mit dieser PRD erstellen?
```

### On Approval: Create Epic Issue

Use `gh issue create` to create the Epic issue. The PRD content becomes the issue body.

**Rules:**
- **Title:** `feat: [Feature Name]` (derived from the PRD title)
- **Body:** The complete PRD markdown content (read from the saved file)
- **Labels:** `epic` and `feature` (create if they don't exist)
- **No assignee** — the user assigns manually

**Command pattern:**
```bash
mkdir -p docs/prds
gh label create "epic" --description "Epic - contains multiple user stories" --color "3E4B9E" --force
gh label create "feature" --description "New feature" --color "0E8A16" --force
gh issue create --title "feat: [Feature Name]" --label "epic" --label "feature" --body-file "docs/prds/prd-[feature-name].md"
```

**Important:**
- Always use `--body-file` to pass the PRD content (avoids shell escaping issues)
- Show the created issue URL to the user after creation
- If the user declines, skip issue creation — the PRD file is still saved

---

## Step 4: Sub-Issues for User Stories (Optional)

After creating the Epic issue, ask the user:

```
Epic Issue #[N] erstellt: feat: [Feature Name]

Das Epic enthält [X] User Stories. Soll ich diese als separate Sub-Issues anlegen?
  A. Ja, Sub-Issues erstellen (empfohlen für größere Features)
  B. Nein, als Checkliste im Epic behalten (für kleinere Features)
```

### On Approval: Create Sub-Issues

For each User Story in the PRD, create a Sub-Issue linked to the Epic.

**Rules:**
- **Title:** `[US-00X] [User Story Title]` (e.g., `[US-001] Set task priority`)
- **Body:** The User Story content from the PRD (Description + Acceptance Criteria)
- **Labels:** `user-story` (create if it doesn't exist)
- **Parent:** Link to Epic issue using `gh issue develop` or body reference

**Command pattern for each User Story:**
```bash
gh label create "user-story" --description "User story - implementable unit of work" --color "C2E0C6" --force

# Create Sub-Issue with reference to Epic
gh issue create --title "[US-001] [Title]" --label "user-story" --body "$(cat <<'EOF'
Parent Epic: #[EPIC_NUMBER]

## [US-001]: [Title]

**Description:** As a [user type], I want [action] so that [benefit].

**Acceptance Criteria:**
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
EOF
)"
```

**After creating all Sub-Issues:**
1. Update the Epic issue body to replace the User Stories section with links to Sub-Issues
2. Show summary to user:

```
Sub-Issues erstellt:
- #[N1] [US-001] Set task priority
- #[N2] [US-002] See priority at a glance
- #[N3] [US-003] Filter by priority
- #[N4] [US-004] Sort by priority

Jede User Story kann jetzt einzeln mit /byt8:full-stack-feature #[N] implementiert werden.
```

### Update Epic with Sub-Issue Links

After creating Sub-Issues, update the Epic's User Stories section:

```bash
# Read current Epic body, replace User Stories section wit