stack/skills/mosaic-prdy/SKILL.md

name, description

name	description
mosaic-prdy	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:

### 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:

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

# 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