Plan PRD

Create structured PRDs using the "land then expand" approach with automatic context management for consistency.

Communication Style: In all interactions and commit messages, be extremely concise and sacrifice grammar for the sake of concision.

Philosophy: Land Then Expand

Modern Claude models work best when they establish patterns first, then layer complexity. This skill creates:

1. Core PRDs: Minimal foundation with essential fields only (2-4 substories max)
2. Expansion PRDs: Focused enhancements building on completed core with auto-loaded context

Why: Large comprehensive PRDs lead to incorrect assumptions, token inefficiency, and inconsistent results.

Activation Context

Use when user says things like:

• "plan a feature for..."
• "write a PRD for..."
• "I want to build..."
• "document requirements for..."
• "create a spec for..."
• "plan [feature name]"
• Any request to plan, design, or document new functionality

Workflow

Phase 0: Validate Prerequisites

FIRST: Check for CLAUDE.md

if [[ ! -f "CLAUDE.md" ]]; then
    cat <<EOF
❌ ERROR: CLAUDE.md file not found in project root

This workflow requires a CLAUDE.md file documenting your project conventions.

To create one, start a new Claude Code session and type:
  /init

Then describe your project, and Claude will help create CLAUDE.md.

Exiting...
EOF
    exit 1
fi

Show confirmation:

✅ CLAUDE.md found
📋 Ready to plan PRD

Phase 1: Determine PRD Type and Load Context

Step 1: Ask PRD Type

CRITICAL: Ask user to determine the PRD type:

Is this:
1. 🌱 A new core feature (minimal foundation to establish patterns)
2. 🔧 An expansion of existing feature (builds on completed core)
3. ⚡ A task-based change (infrastructure, migration, optimization, refactor, etc.)

Choose [1/2/3]:

If user chooses "1 - Core Feature":

• Create minimal foundation PRD
• Max 2-4 substories in single phase
• Essential fields only
• File: .claude/prds/YYYY-MM-DD-{feature}-core.md
• Goal: Establish patterns and working code, NOT completeness
• Initialize context: .claude/prds/context/YYYY-MM-DD-{feature}-core.json

If user chooses "2 - Expansion":

• Ask: "Which core feature does this expand?" or auto-detect from .claude/prds/
• VALIDATE CORE PRD EXISTS AND IS COMPLETE:

  # Check core PRD exists
  if [[ ! -f "$core_prd_file" ]]; then
      echo "❌ ERROR: Core PRD not found"
      exit 1
  fi
  
  # Check core PRD is marked complete
  if ! grep -q "Status.*Complete" "$core_prd_file"; then
      echo "⚠️  WARNING: Core PRD not marked complete"
      echo "Expansion PRDs should build on completed cores."
      echo "Continue anyway? [yes/no]"
  fi
  
  # Check context file exists
  if [[ ! -f ".claude/prds/context/{core-prd-name}.json" ]]; then
      echo "⚠️  WARNING: No context file found for core PRD"
      echo "Context may be limited. Continue? [yes/no]"
  fi
  

• AUTOMATICALLY LOAD CORE CONTEXT:
  1. Read core PRD file (parse frontmatter, substories, acceptance criteria)
  2. Load .claude/prds/context/{core-prd-name}.json (structured context)
  3. Extract files_created, patterns, libraries, architectural_decisions
  4. Read actual core implementation files (analyze code patterns)
  5. Document established patterns with examples
  6. Present findings to user before asking questions
• Create focused expansion PRD building on core
• File: .claude/prds/YYYY-MM-DD-{feature}-{expansion-name}.md
• Goal: Add ONE focused aspect using established patterns

If user chooses "3 - Task-based Change":

• Use task-oriented format instead of substories
• File: .claude/prds/YYYY-MM-DD-{task-name}-task.md
• Format: Checklist of concrete steps instead of phases/substories
• Examples: Database migration, CI/CD setup, performance optimization, refactoring, security patch
• Goal: Complete specific technical task with clear acceptance criteria

Step 2: Understand Feature Scope

Ask scoping question:

"Describe the [core feature/expansion] briefly (1-2 sentences):"

For Core PRDs - Enforce Minimalism: If user describes complex multi-part feature, push back:

🌱 Core PRD Mode: Let's start with the absolute minimum.

You described: [user's description]

What's the simplest version with just essential fields?
Example: If building invoices, start with just number, date, amount.
Everything else (customers, line items, tax) comes later as expansions.

Simplest core version:

For Expansion PRDs: Ask specifically what this expansion adds to the core.

Step 3: Explore Existing Codebase

Before asking detailed questions, understand what exists:

# Read project conventions from CLAUDE.md in project root
# This file contains project-specific conventions, tech stack, patterns, etc.
# Example: Read CLAUDE.md

For Core PRDs: Explore to understand project patterns and conventions from CLAUDE.md and existing codebase.

For Expansion PRDs (CRITICAL - AUTO-LOAD):

Execute comprehensive context loading:

# Source context manager
source skills/shared/scripts/context-manager.sh

# 1. Load core PRD file
core_prd_content=$(cat "$core_prd_file")

# 2. Load core context file
core_context=$(read_context "$core_prd_file")

# 3. Extract structured information
core_files=$(echo "$core_context" | jq -r '.files_created[]')
core_patterns=$(echo "$core_context" | jq -r '.patterns')
core_libraries=$(echo "$core_context" | jq -r '.libraries')
core_decisions=$(echo "$core_context" | jq -r '.architectural_decisions[]')

# 4. Read actual implementation files to understand patterns
echo "📖 Reading core implementation files..."
for file in $core_files; do
    if [[ -f "$file" ]]; then
        # Read file to analyze patterns, naming conventions, structure
        # Focus on: class/function naming, code organization, error handling
    fi
done

# 5. Analyze patterns from code
# - Identify naming conventions (e.g., *Service, *Repository, *Controller)
# - Detect architectural patterns (e.g., MVC, service layer, repository pattern)
# - Note error handling approaches
# - Identify validation patterns
# - Observe data flow patterns

Document comprehensive findings:

🔍 Context Analysis Complete:

[For Core PRDs:]
Project Conventions (from CLAUDE.md):
- Tech stack: [framework, language, key technologies]
- Architecture: [architectural pattern from CLAUDE.md]
- Testing: [testing framework and approach]
- Code style: [linting, formatting standards]

Existing Patterns (from codebase exploration):
- Similar features found: [list related features]
- Common patterns: [list patterns observed]
- File organization: [describe structure]
- Naming conventions: [describe conventions]

[For Expansion PRDs - AUTO-LOADED:]
✅ Core Context Loaded: docs/prds/YYYY-MM-DD-{feature}-core.md

Implementation Files ([X] files):
[List actual files with brief description of each]
- path/to/file1.ext - [what it does]
- path/to/file2.ext - [what it does]

Established Patterns ([Y] patterns):
[List specific patterns with examples from code]
- Pattern 1: [name] - [where used, how implemented]
- Pattern 2: [name] - [where used, how implemented]

Libraries in Use ([Z] libraries):
[List with purpose]
- library1 - [purpose in core]
- library2 - [purpose in core]

Architectural Decisions ([W] decisions):
[List key decisions with rationale]
1. [Decision 1]: [rationale from context]
2. [Decision 2]: [rationale from context]

Code Analysis Insights:
- Naming convention: [pattern observed, e.g., "FeatureNameService"]
- Error handling: [approach used, e.g., "Custom exception classes"]
- Validation: [approach used, e.g., "Schema validators"]
- Data access: [pattern used, e.g., "Repository pattern"]

✅ Expansion will extend these patterns consistently.

Phase 1: Requirements Gathering

Adapt questions based on PRD type:

CORE PRD MODE - Ask focused essential questions (5-8 questions):

Start with understanding:

1. Problem & Context:

   • "What problem does this solve?" (User pain point or business need)
   • "Who is this for?" (Target users/personas)

2. Minimal Scope:

   • "What's the simplest version that solves the core problem?" (Essential functionality only)
   • "What are the absolute minimum data/fields needed?" (Core data model)
   • "What's the ONE primary user flow?" (Single happy path)

3. Success & Boundaries:

   • "How will we measure success?" (Success criteria, metrics)
   • "What's explicitly NOT included in v1?" (Out of scope - becomes expansions)

4. Technical Constraints:

   • "Any critical dependencies or integrations?" (Required systems/services)
   • "Any technical constraints we should know about?" (Performance, security, compliance)

Approach: Ask questions conversationally, not as a rigid checklist. If answers suggest complexity, push back:

💡 That sounds complex for a core PRD. Core should be minimal (2-4 substories).

You mentioned: [complex features A, B, C]

Simplest core version: [essential feature only]
Future expansions: [B], [C]

Does that work?

EXPANSION PRD MODE - Ask focused questions about the expansion (6-10 questions):

First, present loaded context:

✅ Core context loaded from: [core PRD name]

Found:
- [X] implementation files
- [Y] established patterns
- [Z] libraries in use
- [W] architectural decisions

I'll ask questions to understand how this expansion builds on these patterns.

Then ask expansion-specific questions:

1. Expansion Goal:

   • "What specific capability does this add to the core?" (Single focused enhancement)
   • "What user need or use case does this address?" (Why this expansion)

2. Data & Integration:

   • "What new data/fields are needed?" (Data model additions)
   • "How does this connect to existing core code?" (Integration points)
   • "Which core files will be extended vs new files?" (Code changes)

3. User Experience:

   • "What new or enhanced user flows?" (User interactions)
   • "How does this change the existing user experience?" (UX impact)

4. Success & Constraints:

   • "How will we know this expansion works?" (Acceptance criteria)
   • "Any performance or security considerations?" (Non-functional requirements)
   • "What's out of scope for THIS expansion?" (Boundaries - next expansion)

Approach: Reference loaded patterns explicitly in questions:

I see the core uses [Pattern X] for [Purpose]. Should this expansion follow the same pattern?

Important:

• Expansion PRDs are FOCUSED on ONE aspect (e.g., customer details OR line items, not both)
• Must build on core patterns, not introduce conflicting approaches
• If scope seems large, suggest splitting into multiple expansions

Phase 2: Document Generation

CRITICAL: Structure differs for core vs expansion PRDs.

Core PRD Structure

File: .claude/prds/YYYY-MM-DD-{feature}-core.md

# [Feature Name] - Core

**Type:** Core Feature
**Created:** YYYY-MM-DD
**Status:** Planning
**Context File:** `.claude/prds/context/YYYY-MM-DD-{feature}-core.json`

## Overview

### Problem Statement
[Clear articulation of problem]

### Core Solution
[Minimal viable solution - essential fields/functionality ONLY]

### Users
[Target users]

### Success Criteria
- [Basic measurable criteria]

### SLC Commitment
**This PRD defines an SLC (Simple, Lovable, Complete) - *not* an MVP.** The release must feel complete, polished, and delightful even with a tight scope.

## Core Requirements

### Essential Data/Fields
[ONLY the minimum viable fields - example: invoice number, date, amount]

### Core User Flow
[Single primary happy path only]

### Out of Scope (Future Expansions)
[List everything NOT in core - these become expansion PRDs]
Examples:
- Customer details → expansion PRD
- Line items → expansion PRD
- Tax calculations → expansion PRD

## Implementation

**RULE**: Maximum ONE phase with 2-4 substories

### Phase 1: Core Foundation
**Goal:** Establish minimal working feature with essential patterns

#### Substory 1.1: [Minimal Model/Component]
**Description:** [Create basic entity with essential fields only]

**Acceptance Criteria:**
- [ ] [Essential field 1] works
- [ ] [Essential field 2] works
- [ ] Basic CRUD operations

**Status:** ⏳ Not Started

#### Substory 1.2: [Basic Interface/API]
**Description:** [Simple create/read operations]

**Acceptance Criteria:**
- [ ] Can create with essential fields
- [ ] Can retrieve

**Status:** ⏳ Not Started

[2-4 substories maximum]

## Project-Specific Notes
[Minimal project-specific details for core only - reference CLAUDE.md]

## Next Expansions
After core is complete, consider these expansion PRDs:
1. [Expansion 1 name]
2. [Expansion 2 name]
3. [Expansion 3 name]

## Context
This PRD has an associated context file at `.claude/prds/context/YYYY-MM-DD-{feature}-core.json` which tracks:
- Architectural decisions
- Patterns established
- Libraries chosen
- Files created

This context is automatically loaded when creating expansion PRDs.

Expansion PRD Structure

File: .claude/prds/YYYY-MM-DD-{feature}-{expansion-name}.md

# [Feature Name] - [Expansion Name]

**Type:** Expansion
**Builds On:** [Link to core PRD: .claude/prds/YYYY-MM-DD-{feature}-core.md]
**Created:** YYYY-MM-DD
**Status:** Planning
**Context File:** `.claude/prds/context/YYYY-MM-DD-{feature}-{expansion}.json` (inherits from core)

## Overview

### What This Expansion Adds
[Specific enhancement to core]

### Core Implementation Reference (AUTO-LOADED)

**Core PRD:** `.claude/prds/YYYY-MM-DD-{feature}-core.md`

**Files created in core:**
[AUTO-POPULATED from context file - actual file paths from your project]

**Patterns established in core:**
[AUTO-POPULATED from context file - actual patterns used in your codebase]

**Libraries in use:**
[AUTO-POPULATED from context file - actual libraries chosen during core implementation]

**Architectural decisions:**
[AUTO-POPULATED from context file - actual decisions made during core implementation]

### Success Criteria
- [Measurable criteria for this expansion]

### SLC Commitment
**This PRD defines an SLC (Simple, Lovable, Complete) - *not* an MVP.** The release must feel complete, polished, and delightful even with a tight scope.

## Expansion Requirements

### New Data/Fields
[What's added to the core data model]

### Enhanced/New User Flows
[How this changes or adds to core flows]

### Integration with Core
[How this connects to existing core implementation]

## Implementation

### Phase 1: [Expansion Name]
**Goal:** [Expansion objective]

#### Substory 1.1: [Enhancement 1]
**Description:** [Building on core patterns]

**Core Files to Modify:**
- [existing file from core]

**Core Patterns to Follow:**
- [reference established patterns from auto-loaded context]

**Acceptance Criteria:**
- [ ] [Criterion 1]

**Status:** ⏳ Not Started

[Add substories as needed for focused expansion]

## Testing Strategy
[Test approach following core's testing framework]

## Security Considerations
[Following core's security patterns]

## Performance Considerations
[Optimizations specific to this expansion]

## Dependencies
**Internal:**
- Requires: [Core PRD completion]

**External:**
- [New third-party services if any]

## Context
This expansion inherits context from core and adds expansion-specific context to `.claude/prds/context/YYYY-MM-DD-{feature}-{expansion}.json`.

Task-Based PRD Structure

File: .claude/prds/YYYY-MM-DD-{task-name}-task.md

# [Task Name]

**Type:** Task
**Created:** YYYY-MM-DD
**Status:** Planning
**Context File:** `.claude/prds/context/YYYY-MM-DD-{task-name}-task.json`

## Overview

### Problem/Goal
[Clear description of what needs to be done and why]

### Success Criteria
- [Measurable criteria for completion]

## Technical Approach

[Describe the approach, technology choices, and reasoning]

## Implementation Checklist

**Each checkbox represents a concrete step:**

### Preparation
- [ ] [Step 1: e.g., Backup database, review current config]
- [ ] [Step 2: e.g., Set up test environment]

### Execution
- [ ] [Step 3: e.g., Create migration scripts]
- [ ] [Step 4: e.g., Update configuration files]
- [ ] [Step 5: e.g., Deploy changes]

### Validation
- [ ] [Step 6: e.g., Run integration tests]
- [ ] [Step 7: e.g., Verify monitoring/alerts]
- [ ] [Step 8: e.g., Document changes]

**Status:** ⏳ Not Started

## Testing Strategy
[How to verify this task is complete]

## Rollback Plan
[How to revert if something goes wrong]

## Dependencies
**Internal:** [Other PRDs or systems affected]
**External:** [Third-party services, tools required]

## Project-Specific Notes
[Any project-specific details from CLAUDE.md]

## Context
Task-based PRDs use simplified context tracking focused on steps completed rather than phases/substories.

Phase 3: Context Initialization

After creating PRD:

# Source context manager
source skills/shared/scripts/context-manager.sh

# Initialize context file
context_file=$(init_context "$prd_file")

# For expansions: inherit core context
if [[ "$prd_type" == "expansion" ]]; then
    # Copy core context as base
    core_context=$(read_context "$core_prd_file")
    # Add expansion-specific fields
    # Update context with expansion name
fi

# For tasks: simpler context structure
if [[ "$prd_type" == "task" ]]; then
    # Task-based context focuses on checklist completion
    # No phases/substories tracking needed
fi

Phase 4: Validation and Next Steps

After Core PRD creation:

• Verify it's truly minimal (2-4 substories max)
• Confirm essential fields only
• Suggest expansion PRDs for excluded features
• Confirm context file created
• Output message:

✅ Core PRD created: .claude/prds/YYYY-MM-DD-{feature}-core.md
📋 Context file: .claude/prds/context/YYYY-MM-DD-{feature}-core.json

📋 Core includes: [brief summary]
🚫 Out of scope (future expansions): [list]

💡 Next steps:
1. "implement" - Build core foundation with auto-testing and review
2. After core is complete, use "plan" again for expansions:
   - Customer details expansion
   - Line items expansion
   - [etc]

After Expansion PRD creation:

• Verify it builds on completed core
• Confirm focused on ONE aspect
• Reference core implementation patterns
• Confirm context inherited and extended
• Output message:

✅ Expansion PRD created: .claude/prds/YYYY-MM-DD-{feature}-{expansion}.md
📋 Context file: .claude/prds/context/YYYY-MM-DD-{feature}-{expansion}.json

🔧 Expands: {core feature name}
📋 Adds: [brief summary]
🎯 Auto-loaded from core:
   - [X] files created
   - [Y] patterns
   - [Z] libraries
   - [W] architectural decisions

💡 Next: "implement" to build this expansion following core patterns

After Task-Based PRD creation:

• Verify checklist is concrete and actionable
• Confirm rollback plan is included
• Confirm success criteria are measurable
• Output message:

✅ Task PRD created: .claude/prds/YYYY-MM-DD-{task-name}-task.md
📋 Context file: .claude/prds/context/YYYY-MM-DD-{task-name}-task.json

⚡ Task: [brief summary]
📋 Steps: [X] concrete steps defined
✅ Success criteria: [brief list]
🔄 Rollback plan: Included

💡 Next: "implement" to execute this task checklist

Guidelines

Critical Rules:

• ALWAYS ask core vs expansion first - This determines everything
• For Core: Enforce minimalism - Push back on complexity, max 2-4 substories
• For Expansion: AUTO-LOAD core context - Read core PRD and context file automatically
• Initialize context files - Always create/update .claude/prds/context/{prd-name}.json
• Naming convention:
  • Core: .claude/prds/YYYY-MM-DD-{feature}-core.md
  • Expansion: .claude/prds/YYYY-MM-DD-{feature}-{expansion-name}.md

Project Conventions:

• Read CLAUDE.md from project root for project-specific conventions
• Use project-defined terminology and patterns from CLAUDE.md
• Follow tech stack, architecture, and coding standards documented in CLAUDE.md

Context Management:

• Create context file on PRD creation
• For expansions: inherit core context automatically
• Store: patterns, libraries, architectural decisions from CLAUDE.md and codebase
• Used by implement skill for consistency

Quality Checks:

• Ensure acceptance criteria are testable
• Document assumptions explicitly
• Reference project patterns from CLAUDE.md and existing codebase
• For expansions: explicitly reference and auto-load core implementation patterns
• Verify context files are created and populated

Auto-Loading Core Context (Expansion Mode)

When creating an expansion PRD, the skill automatically:

1. Validates core PRD:

   • Checks core PRD file exists
   • Warns if core is not marked complete
   • Checks context file exists
   • Verifies context file is valid JSON

2. Loads core information:

   • Reads core PRD file content (parse frontmatter, substories)
   • Reads .claude/prds/context/{core-prd-name}.json file
   • Extracts structured data (files, patterns, libraries, decisions)

3. Analyzes implementation:

   • Reads actual implementation files from files_created
   • Analyzes code patterns: naming conventions, structure, error handling
   • Identifies architectural patterns in use
   • Documents specific examples from code

4. Presents findings before questions:

   ✅ Core context loaded successfully
   
   Implementation files analyzed:
   - src/models/invoice.rb - Core data model with validations
   - src/services/invoice_service.rb - Business logic service
   - src/api/invoices_controller.rb - RESTful API endpoints
   
   Patterns identified:
   - Service objects for business logic (InvoiceService)
   - ActiveRecord models with validations
   - RESTful API with JSON serialization
   - RSpec for testing
   
   Libraries in use:
   - ActiveRecord (ORM)
   - ActiveModel::Serializers (JSON API)
   
   Now I'll ask how this expansion builds on these patterns...
   

5. Uses context during PRD creation:

   • Auto-fills "Core Implementation Reference" section with real data
   • References specific patterns in substory descriptions
   • Suggests extending existing files vs creating new ones
   • Inherits architectural decisions

6. Creates expansion context:

   • Expansion context starts with core context as base
   • Adds expansion-specific patterns, files, decisions
   • Maintains link to core PRD

This ensures expansions are consistent with core through automated context awareness.

Directory Structure

The skill maintains this directory structure:

.claude/prds/
├── YYYY-MM-DD-feature-core.md              # Active PRD files
├── YYYY-MM-DD-feature-expansion.md
├── context/                                 # Active context files
│   ├── YYYY-MM-DD-feature-core.json
│   └── YYYY-MM-DD-feature-expansion.json
└── archive/                                 # Manual archival (user responsibility)
    ├── old-feature.md                       # Archived PRD
    └── context/
        └── old-feature.json                 # Archived context

Archive Usage:

• The archive/ folder is created but managed by users
• When archiving a completed PRD, move both files:
  • .claude/prds/feature.md → .claude/prds/archive/feature.md
  • .claude/prds/context/feature.json → .claude/prds/archive/context/feature.json
• This keeps PRD and context paired together
• Only archive PRDs that are fully complete, shipped, and no longer actively referenced

Directory Initialization

Before creating any PRD, validate and create required directories:

# Ensure .claude directory structure exists
mkdir -p .claude/prds/context
mkdir -p .claude/prds/archive/context
mkdir -p .claude/checkpoints

# Ensure checkpoints are gitignored (created by code-prd skill)
if [[ -f ".gitignore" ]]; then
    if ! grep -q "\.claude/checkpoints" .gitignore; then
        echo ".claude/checkpoints/" >> .gitignore
    fi
fi

# Note: archive/ is for user manual archival only
# Users should move both .md and corresponding .json to archive/
# to keep PRD and context paired together