stack/skills/mosaic-prdy/SKILL.md

---
name: mosaic-prdy
description: 'Create, update, validate, and manage Product Requirements Documents (PRDs) using the Mosaic PRDy system. Use when planning features, writing requirements, validating PRDs against standards, or checking PRD status. Triggers on: create a prd, write prd, prdy init, prdy validate, plan this feature, requirements document, spec out.'
---

# Mosaic PRDy

PRDy is Mosaic's PRD (Product Requirements Document) lifecycle manager. Create structured PRDs from templates, validate them against quality standards, and track their status through draft → review → approved → archived.

---

## Commands

### Initialize a New PRD

```
/skill:mosaic-prdy init --name "Feature Name"
```

Or describe what you want to build and PRDy will guide you through it:

```
/skill:mosaic-prdy init "Build a notification system with email and in-app channels"
```

### Update an Existing PRD

```
/skill:mosaic-prdy update
```

Scans the project for existing PRDs and offers to update sections.

### Validate a PRD

```
/skill:mosaic-prdy validate
```

Checks all PRDs against Mosaic quality standards:

- Required sections present
- Acceptance criteria are specific and verifiable
- Non-goals defined
- Success metrics measurable

### Check Status

```
/skill:mosaic-prdy status
```

Lists all PRDs in the project with their current status.

---

## The Job

### Step 1: Clarifying Questions

Ask 3-5 essential questions with lettered options (user responds "1A, 2C, 3B"):

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

2. Who is the target user?
   A. New users only
   B. All users
   C. Admin users
   D. Other: [specify]

3. What is the scope?
   A. Minimal viable version
   B. Full-featured
   C. Backend/API only
   D. UI only
```

### Step 2: Generate PRD

Using the Mosaic PRD template with these required sections:

1. **Introduction/Overview** — problem statement and what this solves
2. **Goals** — specific, measurable objectives
3. **User Stories** — with acceptance criteria (see format below)
4. **Functional Requirements** — numbered (FR-1, FR-2, ...)
5. **Non-Functional Requirements** — security, performance, reliability, observability
6. **Non-Goals (Out of Scope)** — explicit boundaries
7. **Design Considerations** — UI/UX, mockups, reusable components
8. **Technical Considerations** — constraints, dependencies, integrations
9. **Success Metrics** — measurable outcomes
10. **Open Questions** — unresolved items

### Step 3: Save

Save to `tasks/prd-[feature-name].md` (kebab-case).

---

## User Story Format

Each story must be small enough to implement in one focused session:

```markdown
### US-001: [Title]

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

**Acceptance Criteria:**

- [ ] Specific verifiable criterion (not "works correctly")
- [ ] Another criterion with measurable outcome
- [ ] Typecheck/lint passes
- [ ] **[UI stories]** Verify in browser using dev-browser skill
```

**Rules:**

- Acceptance criteria must be verifiable, not vague
- "Button shows confirmation dialog before deleting" ✅
- "Works correctly" ❌
- UI stories always include browser verification
- Each story gets a unique ID (US-001, US-002, ...)

---

## PRD Lifecycle

```
draft → review → approved → archived
```

| Status     | Meaning                                        |
| ---------- | ---------------------------------------------- |
| `draft`    | Work in progress, not ready for implementation |
| `review`   | Ready for stakeholder review                   |
| `approved` | Approved for implementation — the contract     |
| `archived` | Completed or abandoned                         |

**Key rule:** Implementation that diverges from an approved PRD without updating the PRD first is a blocker. Change control: update PRD → update plan → then implement.

---

## Templates

PRDy ships with built-in templates:

| Template         | Use When                            |
| ---------------- | ----------------------------------- |
| `feature`        | New feature or capability (default) |
| `integration`    | Third-party integration or API      |
| `infrastructure` | DevOps, deployment, scaling         |
| `refactor`       | Technical debt, architecture change |

Specify a template:

```
/skill:mosaic-prdy init --name "Auth Integration" --template integration
```

---

## Validation Rules

`/skill:mosaic-prdy validate` checks:

- [ ] Has introduction/overview
- [ ] Has at least one goal
- [ ] Has at least one user story with acceptance criteria
- [ ] Functional requirements are numbered
- [ ] Non-goals section exists and is non-empty
- [ ] Acceptance criteria are specific (flags vague terms: "works correctly", "handles properly", "is fast")
- [ ] Success metrics are measurable
- [ ] No TODO/TBD markers in approved PRDs

---

## Integration with Forge

When used with Mosaic Forge (`/skill:mosaic-forge`):

1. PRDy creates the PRD (this skill)
2. Forge decomposes the PRD into briefs
3. Board reviews each brief
4. Pipeline builds each brief through specialist stages

PRDy is the **input** to the Forge pipeline. A well-written PRD means less rework in planning stages.

---

## Standalone CLI

If the `mosaic` CLI is available:

```bash
mosaic prdy init --name "Feature Name"
mosaic prdy update
mosaic prdy validate
mosaic prdy status

# With runtime selection
mosaic prdy --pi init --name "Feature Name"
mosaic prdy --claude init --name "Feature Name"
```

---

## Writing for Junior Developers

PRDs may be read by junior developers or AI agents. Therefore:

- Be explicit and unambiguous
- Avoid jargon or explain it
- Provide enough detail to understand purpose and core logic
- Number requirements for easy reference
- Use concrete examples where helpful

---

## Example

```markdown
# PRD: Task Priority System

## Introduction

Add priority levels to tasks so users can focus on what matters most.

## Goals

- Allow assigning priority (high/medium/low) to any task
- Provide clear visual differentiation between priority levels
- Enable filtering and sorting by priority

## User Stories

### US-001: Add priority field to database

**Description:** As a developer, I need to store task priority persistently.
**Acceptance Criteria:**

- [ ] Add priority column: 'high' | 'medium' | 'low' (default 'medium')
- [ ] Migration runs successfully
- [ ] Typecheck passes

### US-002: Display priority indicator

**Description:** As a user, I want to see task priority at a glance.
**Acceptance Criteria:**

- [ ] Colored badge: red=high, yellow=medium, gray=low
- [ ] Priority visible without hovering
- [ ] Verify in browser

## Functional Requirements

- FR-1: Add `priority` field ('high'|'medium'|'low', default 'medium')
- FR-2: Display colored priority badge on each task card
- FR-3: Priority filter dropdown in task list header

## Non-Goals

- No priority-based notifications
- No automatic priority assignment
- No priority inheritance for subtasks

## Success Metrics

- Users can change priority in under 2 clicks
- High-priority tasks visible at top of lists
```