PRD Mastery: Context-Aware, Expert-Driven, and Token-Efficient Refinement

What this skill does

# PRD Mastery Skills

**Status:** Production Ready  
**Package Manager:** pnpm  
**Key Focus:** Context-aware PRD creation, token efficiency, expert-driven guidance  
**Official References:**
- Marty Cagan - "Inspired: How to Create Tech Products Customers Love"
- Teresa Torres - "Continuous Discovery Habits"
- George Biddle - Product Management Best Practices

---

## Table of Contents

1. [Overview](#overview)
2. [Installation & Setup](#installation--setup)
3. [Workflow Steps](#workflow-steps)
4. [Expert-Driven Questioning Techniques](#expert-driven-questioning-techniques)
5. [Token Efficiency Guidelines](#token-efficiency-guidelines)
6. [PRD Organization Structure](#prd-organization-structure)
7. [Code Examples](#code-examples)
8. [Best Practices](#best-practices)
9. [Templates & Resources](#templates--resources)

---

## Overview

The PRD Mastery skill helps AI agents create high-quality, context-aware Product Requirements Documents (PRDs) that are:

- **Context-Aware**: Adapts to whether the project is new or existing, understanding the current tech stack and architecture
- **Expert-Driven**: Uses questioning techniques from industry leaders like Marty Cagan, Teresa Torres, and George Biddle
- **Token-Efficient**: Optimized for AI readability and minimal token usage while maintaining clarity and completeness
- **Well-Organized**: Maintains a clear folder structure for managing multiple PRDs and related artifacts

### Key Features

✅ Automated repository reconnaissance to understand project context  
✅ Adaptive questioning based on project stage  
✅ Expert-guided user interviews to extract requirements  
✅ Token-optimized output format  
✅ Structured organization system for PRD management  
✅ Reusable templates and examples  

---

## Installation & Setup

### Prerequisites

```bash
# Node.js 20.9+ for running reconnaissance scripts
node --version

# pnpm (recommended)
pnpm --version
```

### Quick Start

1. **Run Repository Reconnaissance**
   ```bash
   node .claude/skills/ba-prd-skills/repo_scan.js
   ```

2. **Review Preliminary Findings**
   ```bash
   cat prelim_summary.md
   ```

3. **Create Your First PRD**
   Follow the workflow steps below to guide the PRD creation process.

---

## Workflow Steps

### Step 1: Initial Reconnaissance

**Goal**: Automatically determine if the project is new or existing, identify tech stack, and document context.

**Process**:
1. Run `repo_scan.js` to analyze:
   - Existing codebase structure
   - Technology stack (frameworks, languages, tools)
   - Architecture patterns (monorepo, microservices, etc.)
   - Dependencies and integrations
   - Documentation state

2. Output is saved to `prelim_summary.md` with:
   - Project type (new/existing)
   - Tech stack summary
   - Architecture overview
   - Key observations
   - Recommended next steps

**Example Output**:
```markdown
# Preliminary Project Summary

**Project Type**: Existing
**Tech Stack**: Next.js 16, React, TypeScript, Prisma ORM
**Architecture**: App Router with server components
**Key Observations**: 
- Well-structured authentication system using Auth.js
- Vector database integration with Upstash
- MCP server pattern implementation
```

---

### Step 2: Identify Project Stage and Tech Context

**Goal**: Understand where the project is in its lifecycle and whether architecture changes are needed.

**Context-Aware Questions**:

For **New Projects**:
- What problem are you solving?
- Who are your target users?
- What are the core user outcomes you want to enable?
- What technical constraints do you have? (team skills, budget, timeline)
- What are your scalability expectations?

For **Existing Projects**:
- What are you trying to improve or add?
- Are there pain points with the current architecture?
- Should we maintain the existing tech stack or consider changes?
- What are the key integration points we need to preserve?
- What are the migration constraints?

**Adaptive Follow-ups**:
- If user provides technical details → Validate against current stack, identify gaps
- If user is non-technical → Translate to technical requirements, suggest options
- If requirements are vague → Use expert questioning to narrow scope

---

### Step 3: Guide the User (Expert-Driven Approach)

**Goal**: Use proven questioning techniques to move from broad ideas to specific, outcome-focused PRDs.

#### Marty Cagan's Outcome-Focused Questions

Inspired by "Inspired", focus on outcomes over features:

1. **Problem Definition**
   - What customer problem are we solving?
   - How do we know this is a real problem?
   - What does success look like for the user?

2. **Discovery Validation**
   - Have we validated this problem with real users?
   - What evidence do we have that this solution will work?
   - What are the risks?

3. **Value Proposition**
   - Why will customers choose this?
   - What makes this solution compelling?
   - How does this align with business objectives?

#### Teresa Torres' Continuous Discovery

Based on "Continuous Discovery Habits":

1. **Opportunity Mapping**
   - What opportunities have we identified?
   - Which opportunity has the biggest impact?
   - How does this connect to the desired outcome?

2. **Assumption Testing**
   - What assumptions are we making?
   - Which assumptions are riskiest?
   - How can we test these quickly?

3. **Customer Interviews**
   - Who should we talk to?
   - What do we need to learn?
   - How will we capture and synthesize insights?

#### George Biddle's Structured Approach

Focus on clarity and completeness:

1. **Stakeholder Alignment**
   - Who needs to approve this?
   - What concerns might stakeholders have?
   - How do we measure success?

2. **Technical Feasibility**
   - Is this technically possible with our stack?
   - What are the technical risks?
   - What dependencies exist?

3. **Implementation Plan**
   - What's the MVP scope?
   - How do we break this into phases?
   - What's the timeline?

---

### Step 4: Apply Best Practices and Organize Output

**Goal**: Create a token-efficient PRD and organize it in a clear folder structure.

#### Folder Structure

```
prds/
├── README.md                          # Index of all PRDs
├── prd-001-user-authentication/
│   ├── prd.md                        # Main PRD document
│   ├── research.md                   # User research findings
│   ├── technical-specs.md            # Technical specifications
│   ├── mockups/                      # Design mockups
│   └── decisions.md                  # Architecture decisions
├── prd-002-vector-search/
│   ├── prd.md
│   ├── research.md
│   ├── technical-specs.md
│   └── decisions.md
└── templates/
    └── prd-template.md               # Template for new PRDs
```

#### PRD Document Structure

Each PRD follows a token-efficient format:

```markdown
# [Feature Name] - PRD

**ID**: PRD-XXX
**Status**: Draft | In Review | Approved | Implemented
**Owner**: [Name]
**Created**: YYYY-MM-DD
**Last Updated**: YYYY-MM-DD

## Summary
[2-3 sentence overview optimized for AI parsing]

## Problem Statement
- User need: [Specific user problem]
- Business goal: [Why this matters]
- Success metric: [How we measure success]

## Target Users
- Primary: [Who benefits most]
- Secondary: [Additional users]

## Key Outcomes
1. [Outcome 1 - user benefit]
2. [Outcome 2 - business benefit]
3. [Outcome 3 - technical benefit]

## Requirements
### Must Have
- [ ] Requirement 1
- [ ] Requirement 2

### Should Have
- [ ] Requirement 3

### Could Have
- [ ] Requirement 4

## Technical Approach
- Stack: [Tech stack]
- Architecture: [High-level approach]
- Integration points: [Key integrations]

## Risks & Assumptions
- Risk: [Risk] | Mitigation: [Plan]
- Assumption: [Assumption] | Validation: [How to test]

## Success Criteria
- Metric 1: [Target]
- Metric 2: [Target]

## Implementation Plan
1. Phase 1: [Scope] - [Timeline]
2. Phase 2: [Scope] - [Timeline]

## Resources
- Design: [Link]
- Research: [Link]
- Technical specs: [Link]
```

---

## Expert-Dri