planning

name

planning

description

Generate and optimize PRDs, Implementation Plans, and Progress Tracking documents optimized as AI artifacts for development agents. Use when creating new feature plans, breaking down long planning docs (>800 lines), or setting up progress tracking. Supports: 1) Create PRD from feature request, 2) Create Implementation Plan from PRD with phase breakdown and subagent assignments, 3) Optimize existing plans by breaking into phase-specific files, 4) Create progress tracking with task assignments. Example: "Create a PRD for user authentication feature" or "Break down the sidebar-polish implementation plan into phase files" or "Create progress tracking for data-layer-fixes PRD".

Planning Skill

About This Skill

The Planning Skill generates and optimizes Product Requirements Documents (PRDs) and Implementation Plans as AI artifacts - file-based context caches optimized for AI agent consumption rather than human reading.

Purpose

• Generate comprehensive PRDs from feature requests following MP template
• Create phased Implementation Plans with subagent task assignments
• Optimize existing planning docs by breaking into token-efficient files
• Set up progress tracking structures for multi-phase implementations

Key Benefits

• Token Efficiency: Max ~800 lines per file for optimal AI context loading
• Progressive Disclosure: Summary → Detail pattern with linked files
• Subagent Integration: Automatic task assignment to appropriate specialists
• MP Architecture Compliance: Plans follow layered architecture (routers → services → repositories → DB)
• Structured Tracking: One progress file per phase following CLAUDE.md policy

When to Use This Skill

• Creating PRDs for new features or enhancements
• Generating detailed implementation plans from PRDs
• Breaking down long planning documents (>800 lines) into manageable files
• Setting up progress tracking for multi-phase work
• Optimizing existing plans for better AI agent consumption

Quick Start

Create PRD from Feature Request

# User provides feature description
User: "Create a PRD for advanced filtering on the prompts page"

# Skill generates PRD at:
# docs/project_plans/PRDs/[category]/advanced-filtering-v1.md

Create Implementation Plan from PRD

# Provide PRD path
User: "Create implementation plan for docs/project_plans/PRDs/harden-polish/advanced-filtering-v1.md"

# Skill generates:
# - Main plan: docs/project_plans/implementation_plans/harden-polish/advanced-filtering-v1.md
# - Phase files (if needed): docs/project_plans/implementation_plans/harden-polish/advanced-filtering-v1/phase-[N]-[name].md

Optimize Existing Plan

# Provide existing plan path
User: "Optimize docs/project_plans/implementation_plans/harden-polish/sidebar-polish-v1.md"

# Skill:
# 1. Analyzes plan length (e.g., 1200 lines)
# 2. Breaks into phase-specific files (~400 lines each)
# 3. Updates parent plan with links to phase files

Create Progress Tracking

# Provide PRD or Implementation Plan
User: "Create progress tracking for data-layer-fixes PRD"

# Skill generates:
# .claude/progress/[feature-name]/all-phases-progress.md
# With task breakdown, subagent assignments, completion tracking

Core Workflows

Workflow 1: Create PRD from Feature Request

Input: Feature description or request from user

Process:

1. Analyze Request

   • Extract feature name, scope, goals
   • Identify related systems and components
   • Determine priority and complexity

2. Structure PRD

   • Use template: ./templates/prd-template.md
   • Follow MP architecture patterns (see ./references/mp-architecture.md)
   • Include frontmatter with proper metadata
   • Organize into standard PRD sections

3. Add Implementation Context

   • Break into phased approach
   • Identify architectural layers involved
   • Note dependencies and risks
   • Define success criteria and acceptance tests

4. Determine Location

   • Category: docs/project_plans/PRDs/[category]/
   • Categories: harden-polish, features, enhancements, refactors
   • Naming: [feature-name]-v1.md (kebab-case)

5. Generate File

   • Write PRD to determined location
   • Include YAML frontmatter with metadata
   • Link to related docs (ADRs, guides, etc.)
   • Add to project tracking if needed

Output:

• PRD file at: docs/project_plans/PRDs/[category]/[feature-name]-v1.md
• Follows template structure
• Ready for implementation planning

Example:

Input: "Add real-time collaboration features to prompt editing"

Output Location: docs/project_plans/PRDs/features/realtime-collaboration-v1.md

Sections:
1. Executive Summary - Real-time collaborative editing
2. Context & Background - Current single-user editing limitations
3. Problem Statement - Users can't collaborate on prompts
4. Goals & Success Metrics - Multiple concurrent editors, conflict resolution
5. Requirements - WebSocket connections, operational transforms, presence indicators
6. Implementation Phases - Phase 1: Backend infrastructure, Phase 2: Frontend integration
... (full PRD structure)

Workflow 2: Create Implementation Plan from PRD

Input: Path to existing PRD or newly created PRD

Process:

1. Analyze PRD

   • Read full PRD content
   • Extract key requirements
   • Identify architectural layers needed
   • Determine phase breakdown strategy

2. Plan Phase Structure

   • Follow MP layered architecture: routers → services → repositories → DB
   • Group related tasks into phases
   • Common phases: Database → Repository → Service → API → UI → Testing → Docs → Deployment
   • Consider parallel work opportunities
   • Identify critical path

3. Generate Task Breakdown

   • Use template: ./templates/implementation-plan-template.md
   • Create tasks for each phase
   • Format: Task tables with ID, Name, Description, Acceptance Criteria, Estimate
   • Include quality gates for each phase

4. Assign Subagents

   • Use reference: ./references/subagent-assignments.md
   • Assign based on task type:
     • Database: data-layer-expert
     • Backend API: python-backend-engineer, backend-architect
     • Frontend: ui-engineer-enhanced, frontend-developer
     • UI Components: ui-designer, ui-engineer
     • Testing: appropriate testing agents
     • Docs: documentation-writer, documentation-complex
   • Add to each task: "Assigned Subagent(s): agent-1, agent-2"

5. Optimize for Token Efficiency

   • If total plan >800 lines: break into phase-specific files
   • Pattern: [feature-name]-v1/phase-[N]-[name].md
   • Parent plan links to phase files
   • Each phase file <800 lines
   • See ./references/optimization-patterns.md

6. Generate Files

   • Main plan: docs/project_plans/implementation_plans/[category]/[feature-name]-v1.md
   • Phase files (if needed): docs/project_plans/implementation_plans/[category]/[feature-name]-v1/phase-[N]-[name].md
   • Link phase files from parent plan

Output:

• Implementation Plan at determined location
• Phase breakdown with subagent assignments
• Linked phase files if plan >800 lines
• Quality gates and success criteria per phase

Example:

Input PRD: docs/project_plans/PRDs/features/realtime-collaboration-v1.md

Output:
Main Plan: docs/project_plans/implementation_plans/features/realtime-collaboration-v1.md

Phase Breakdown:
- Phase 1: Database Layer (websocket_sessions, edit_locks tables) - data-layer-expert
- Phase 2: Repository Layer (session management, lock management) - python-backend-engineer
- Phase 3: Service Layer (operational transforms, conflict resolution) - backend-architect
- Phase 4: API Layer (WebSocket endpoints, presence API) - python-backend-engineer
- Phase 5: UI Layer (collaborative editor, presence indicators) - ui-engineer-enhanced, frontend-developer
- Phase 6: Testing (unit, integration, E2E conflict scenarios) - testing agents
- Phase 7: Documentation (API docs, user guides) - documentation-writer
- Phase 8: Deployment (feature flags, monitoring) - DevOps

Phase Files (if plan >800 lines):
- realtime-collaboration-v1/phase-1-database.md
- realtime-collaboration-v1/phase-2-repository.md
- realtime-collaboration-v1/phase-3-5-backend.md (grouped related phases)
- realtime-collaboration-v1/phase-6-8-validation.md (grouped related phases)

Workflow 3: Optimize Existing Plans

Input: Path to existing PRD or Implementation Plan that's >800 lines

Process:

1. Analyze Plan

   • Read full plan
   • Count total lines
   • Identify natural break points (phases, sections)
   • Determine optimal split strategy

2. Determine Breakout Strategy

   • Primary: Break by phase (most common)
   • Secondary: Break by domain (backend vs frontend)
   • Tertiary: Break by task type (implementation vs testing)
   • Goal: Each file <800 lines, logically cohesive

3. Create Breakout Files

   • Pattern: [plan-name]/phase-[N]-[name].md
   • Alternative: [plan-name]/[domain]-tasks.md
   • Each file includes:
     • Phase/section overview
     • Relevant tasks with subagent assignments
     • Quality gates for that section
     • Links back to parent plan

4. Update Parent Plan

   • Add table of contents linking to breakout files
   • Keep executive summary and overview in parent
   • Replace detailed sections with links:

     ## Phase 2: Repository Layer
     See [Phase 2 Implementation Details](./[plan-name]/phase-2-repository.md)
     

   • Maintain quality gates summary in parent

5. Validate Optimization

   • Each file <800 lines ✓
   • All content preserved ✓
   • Links work correctly ✓
   • Logical grouping maintained ✓
   • Progressive disclosure achieved ✓

Output:

• Optimized parent plan (summary + links)
• Breakout files for detailed content
• Improved token efficiency (95%+ reduction in single-load context)

Example:

Input: docs/project_plans/implementation_plans/harden-polish/sidebar-polish-v1.md (1200 lines)

Analysis:
- 8 phases, ~150 lines each
- Can group related phases: 1-3 (backend), 4-5 (frontend), 6-8 (validation)

Output:
Parent: sidebar-polish-v1.md (200 lines - summary + links)
Phase Files:
- sidebar-polish-v1/phase-1-3-backend.md (450 lines)
- sidebar-polish-v1/phase-4-5-frontend.md (400 lines)
- sidebar-polish-v1/phase-6-8-validation.md (350 lines)

Token Efficiency:
- Before: Load 1200 lines for any query
- After: Load 200-line summary, then specific phase (450 max) = 67% reduction

Workflow 4: Create Progress Tracking

Input: PRD or Implementation Plan

Process:

1. Extract Implementation Tasks

   • Read Implementation Plan (or "Implementation" section of PRD)
   • Extract all tasks by phase
   • Capture task IDs, names, descriptions, estimates

2. Structure Progress File

   • Use template: ./templates/progress-tracking-template.md
   • Follow CLAUDE.md policy: ONE file per feature (all phases)
   • Location: .claude/progress/[feature-name]/all-phases-progress.md
   • Format: Phase overview table + detailed phase sections

3. Add Subagent Assignments

   • Use ./references/subagent-assignments.md
   • Add to each task based on type
   • Format: "Assigned Subagent(s): agent-1, agent-2"
   • Example task types:
     • Database schema: data-layer-expert
     • API endpoints: python-backend-engineer, backend-architect
     • React components: ui-engineer-enhanced, frontend-developer
     • Testing: testing specialists
     • Documentation: documentation-writer

4. Set Up Tracking Structure

   • Phase Overview table with status/completion
   • Per-phase sections with:
     • Completion checklist (tasks as checkboxes)
     • Subagent assignments
     • Success criteria
     • Key files involved
   • Status tracking: NOT STARTED, IN PROGRESS, BLOCKED, COMPLETE

5. Link from PRD

   • Update PRD's "Implementation" section
   • Add link to progress tracking file
   • Format: See progress tracking: .claude/progress/[feature-name]/all-phases-progress.md

Output:

• Progress tracking file at: .claude/progress/[feature-name]/all-phases-progress.md
• Linked from PRD
• Tasks organized by phase
• Subagent assignments on every task
• Ready for implementation tracking

Example:

Input PRD: docs/project_plans/PRDs/harden-polish/data-layer-fixes-filtering-v1.md

Output: .claude/progress/data-layer-fixes-filtering-v1/all-phases-progress.md

Structure:
# All-Phases Progress: Data Layer Fixes & Filtering

**Status**: NOT STARTED
**Last Updated**: 2025-11-11
**Completion**: 0% (0 of 24 story points)

## Phase Overview
| Phase | Title | Effort | Status | Completion |
|-------|-------|--------|--------|-----------|
| 1 | Repository Layer - Transaction Mgmt | 8 pts | NOT STARTED | 0% |
| 2 | Repository Layer - Filter Queries | 8 pts | NOT STARTED | 0% |
| 3 | Service Layer - Validation & DTOs | 5 pts | NOT STARTED | 0% |
| 4 | Frontend Layer - React Query | 5 pts | NOT STARTED | 0% |

## Phase 1: Repository Layer - Transaction Management
**Assigned Subagent(s)**: data-layer-expert, python-backend-engineer

### Completion Checklist
- [ ] TX-001: Fix BaseRepository Rollback (3 pts)
      Assigned Subagent(s): data-layer-expert
- [ ] TX-002: Update PromptRepository Error Handling (3 pts)
      Assigned Subagent(s): python-backend-engineer
- [ ] TX-003: Add Transaction Telemetry (1 pt)
      Assigned Subagent(s): backend-architect
- [ ] TX-004: Integration Tests (1 pt)
      Assigned Subagent(s): testing-specialist

### Success Criteria
- [ ] All repository exceptions trigger automatic rollback
- [ ] Transaction state correctly reset after errors
...

Templates Reference

prd-template.md

Location: ./templates/prd-template.md

Based On: /docs/docs-v2/templates/PRD-TEMPLATE.md

Purpose: Standard PRD structure for MeatyPrompts features

Key Sections:

• Feature Brief & Metadata (name, date, author, related docs)
• Executive Summary (1-2 paragraphs)
• Context & Background (problem space, current state)
• Problem Statement (clear gap or pain point)
• Goals & Success Metrics (measurable outcomes)
• Requirements (functional and non-functional)
• Scope (in-scope vs out-of-scope)
• Dependencies & Assumptions
• Risks & Mitigations
• Target State (post-implementation)
• Acceptance Criteria (definition of done)
• Implementation (phased breakdown with tasks)

When to Use: Creating any new PRD

implementation-plan-template.md

Location: ./templates/implementation-plan-template.md

Based On: /claude-export/templates/pm/implementation-plan-template.md

Purpose: Detailed phased implementation with task breakdown

Key Sections:

• Executive Summary (approach, milestones, success criteria)
• Implementation Strategy (architecture sequence, parallel work, critical path)
• Phase Breakdown (8 standard phases with task tables)
• Risk Mitigation (technical and schedule risks)
• Resource Requirements (team composition, skills, infrastructure)
• Success Metrics (delivery, business, technical)
• Communication Plan (status reporting, escalation)
• Post-Implementation Plan (monitoring, maintenance)

When to Use: Creating implementation plan from PRD

progress-tracking-template.md

Location: ./templates/progress-tracking-template.md

Purpose: Track implementation progress across all phases

Key Sections:

• Status header (overall status, completion %, last updated)
• Phase Overview table (phase, title, effort, status, completion)
• Per-phase sections (completion checklist, success criteria, key files)
• Subagent assignments per task
• Links to PRD and Implementation Plan

When to Use: Setting up progress tracking for multi-phase work

phase-breakdown-template.md

Location: ./templates/phase-breakdown-template.md

Purpose: Template for individual phase files when breaking up long plans

Key Sections:

• Phase overview (duration, dependencies, team)
• Task breakdown table (ID, name, description, acceptance criteria, estimate, assignee)
• Subagent assignments
• Quality gates
• Key files and integration points
• Link back to parent plan

When to Use: Breaking long implementation plans into phase-specific files

Scripts Reference

All scripts are in ./scripts/ directory and use Node.js (NOT Python).

generate-prd.sh

Purpose: Generate PRD from feature request

Usage:

./scripts/generate-prd.sh "Feature description" "category"

Process:

1. Parse feature description
2. Determine category and filename
3. Load PRD template
4. Generate PRD content
5. Write to docs/project_plans/PRDs/[category]/[feature-name]-v1.md

Output: PRD file path

generate-impl-plan.sh

Purpose: Generate implementation plan from PRD

Usage:

./scripts/generate-impl-plan.sh "path/to/prd.md"

Process:

1. Read PRD content
2. Extract requirements and phases
3. Generate task breakdown
4. Add subagent assignments
5. Determine if plan needs breakout (>800 lines)
6. Write main plan and phase files

Output: Implementation plan file path(s)

optimize-plan.sh

Purpose: Break long plan into phase-specific files

Usage:

./scripts/optimize-plan.sh "path/to/plan.md"

Process:

1. Read plan and count lines
2. Determine optimal breakout strategy
3. Create phase-specific files
4. Update parent plan with links
5. Validate all content preserved

Output: List of created phase files

assign-subagents.sh

Purpose: Add subagent assignments to tasks in plan

Usage:

./scripts/assign-subagents.sh "path/to/plan.md"

Process:

1. Read plan and extract tasks
2. Determine task type (database, API, frontend, etc.)
3. Map to appropriate subagents using ./references/subagent-assignments.md
4. Add assignment note to each task
5. Update plan file

Output: Updated plan with subagent assignments

create-progress-tracking.sh

Purpose: Create progress tracking document from plan

Usage:

./scripts/create-progress-tracking.sh "path/to/plan.md"

Process:

1. Read implementation plan
2. Extract all phases and tasks
3. Generate progress tracking structure
4. Add subagent assignments
5. Write to .claude/progress/[feature-name]/all-phases-progress.md
6. Update PRD with link to progress file

Output: Progress tracking file path

References

mp-architecture.md

Location: ./references/mp-architecture.md

Purpose: Summary of MeatyPrompts layered architecture

Content:

• Layered architecture: routers → services → repositories → DB
• Repositories own all DB I/O and RLS
• Services return DTOs only
• Routers handle HTTP + validation
• ErrorResponse envelope for errors
• Cursor pagination for lists: { items, pageInfo }
• OpenTelemetry spans and structured logging

Used By: PRD generation, implementation planning

subagent-assignments.md

Location: ./references/subagent-assignments.md

Purpose: Mapping of task types to appropriate subagents

Content:

Task Type	Subagents	Notes
Database Schema	data-layer-expert	Tables, indexes, RLS policies
Database Migrations	data-layer-expert, python-backend-engineer	Alembic migrations
Repository Layer	python-backend-engineer, data-layer-expert	DB I/O, transactions
Service Layer	python-backend-engineer, backend-architect	Business logic, DTOs
API Endpoints	python-backend-engineer, backend-architect	FastAPI routers
Frontend Components	ui-engineer-enhanced, frontend-developer	React components
UI Design	ui-designer, ux-researcher	Design system, wireframes
Testing	testing specialists	Unit, integration, E2E
Documentation	documentation-writer, documentation-complex	Based on complexity
Performance	react-performance-optimizer	React optimization
Accessibility	web-accessibility-checker	WCAG compliance

Used By: Implementation planning, progress tracking creation

file-structure.md

Location: ./references/file-structure.md

Purpose: Directory structure conventions for plans and progress

Content:

docs/project_plans/
├── PRDs/
│   ├── harden-polish/         # Bug fixes, polish
│   ├── features/              # New features
│   ├── enhancements/          # Feature enhancements
│   └── refactors/             # Architecture refactors
│
└── implementation_plans/
    ├── harden-polish/
    │   ├── feature-name-v1.md              # Main plan
    │   └── feature-name-v1/                # Phase breakouts
    │       ├── phase-1-database.md
    │       ├── phase-2-3-backend.md
    │       └── phase-4-5-frontend.md
    ├── features/
    ├── enhancements/
    └── refactors/

.claude/
└── progress/
    └── feature-name/
        └── all-phases-progress.md          # ONE file per feature

Naming Conventions:

• PRDs: [feature-name]-v1.md (kebab-case)
• Implementation Plans: [feature-name]-v1.md
• Phase Files: phase-[N]-[name].md or phase-[N]-[M]-[name].md (grouped)
• Progress: all-phases-progress.md (one per feature)

Used By: File creation, optimization

optimization-patterns.md

Location: ./references/optimization-patterns.md

Purpose: Patterns for breaking up long files into token-efficient chunks

Content:

Pattern 1: Break by Phase (Most Common)

• Split implementation plan by phase (1-3, 4-5, 6-8)
• Each phase file <800 lines
• Parent links to phase files
• Progressive disclosure: Load summary, then specific phase

Pattern 2: Break by Domain

• Backend phases (Database, Repository, Service, API)
• Frontend phases (UI, Components, State)
• Validation phases (Testing, Docs, Deployment)

Pattern 3: Break by Task Type

• Implementation tasks
• Testing tasks
• Documentation tasks
• Deployment tasks

Pattern 4: Keep Together

• Always keep in parent plan:
  • Executive summary
  • Phase overview table
  • Risk mitigation summary
  • Success metrics overview
• Move to phase files:
  • Detailed task breakdowns
  • Specific acceptance criteria
  • Technical implementation notes

Token Efficiency Gains:

• Before: Load entire 1200-line plan
• After: Load 200-line summary + 400-line phase = 50% reduction
• For targeted queries: Load only relevant phase = 67%+ reduction

Used By: Plan optimization workflow

Best Practices

File Size Management

Guideline: No file should exceed ~800 lines

Rationale:

• Optimal token efficiency for AI context loading
• Enables progressive disclosure pattern
• Reduces cognitive load for agents
• Faster file parsing and analysis

Strategies:

1. Break plans by phase when >800 lines
2. Group short related phases (1-3, 4-5)
3. Keep summaries in parent, details in phase files
4. Use links for cross-references

Naming Conventions

PRDs: [feature-name]-v1.md

• Use kebab-case (lowercase with hyphens)
• Include version number (-v1, -v2)
• Descriptive name (e.g., advanced-filtering-v1.md)

Implementation Plans: [feature-name]-v1.md

• Match PRD naming
• Same category as PRD
• Version synchronized with PRD

Phase Files: phase-[N]-[name].md

• Sequential numbering (phase-1, phase-2)
• Can group: phase-1-3-backend.md
• Descriptive name (database, repository, frontend)

Progress Files: all-phases-progress.md

• ONE file per feature (all phases together)
• Location: .claude/progress/[feature-name]/

Directory Organization

PRDs:

• docs/project_plans/PRDs/[category]/
• Categories: harden-polish, features, enhancements, refactors

Implementation Plans:

• docs/project_plans/implementation_plans/[category]/
• Match PRD category
• Phase breakouts in subdirectory: [plan-name]/

Progress Tracking:

• .claude/progress/[feature-name]/
• One directory per feature
• Contains: all-phases-progress.md

Subagent Assignment Strategy

Match Task Type to Specialist:

• Database work → data-layer-expert
• API implementation → python-backend-engineer, backend-architect
• React components → ui-engineer-enhanced, frontend-developer
• UI design → ui-designer, ux-researcher
• Testing → appropriate testing specialists
• Documentation → documentation-writer (90%), documentation-complex (10%)

Assignment Format:

- [ ] TASK-001: Task Name (3 pts)
      Assigned Subagent(s): python-backend-engineer, backend-architect

Multiple Agents:

• Primary agent first
• Supporting agents after
• Consider expertise overlap

Token Efficiency Tips

Progressive Disclosure:

1. Summary in parent plan (200 lines)
2. Link to detailed phase files (400 lines each)
3. Agent loads summary first, then specific phase as needed
4. 50-67% token reduction

Structured References:

• Link to ADRs instead of duplicating architecture info
• Reference existing docs rather than repeating
• Use relative paths for phase file links

Chunk by Logical Units:

• Keep related tasks together
• Don't split mid-phase
• Group short phases if logical
• Maintain quality gates with phases

YAML Frontmatter

PRDs:

---
title: "Feature Name - PRD"
description: "Brief summary (1-2 sentences)"
audience: [ai-agents, developers]
tags: [relevant, tags, for, search]
created: 2025-11-11
updated: 2025-11-11
category: "product-planning"
status: draft|published
related:
  - /docs/architecture/ADRs/relevant-adr.md
  - /docs/guides/relevant-guide.md
---

Implementation Plans:

---
title: "Feature Name - Implementation Plan"
description: "Brief summary of implementation approach"
audience: [ai-agents, developers]
tags: [implementation, planning, phases]
created: 2025-11-11
updated: 2025-11-11
category: "product-planning"
status: draft|in-progress|published
related:
  - /docs/project_plans/PRDs/category/feature-name-v1.md
---

Progress Tracking: No frontmatter required for .claude/progress/ files (per CLAUDE.md)

Examples

Example 1: Create PRD for Advanced Filtering

Input:

User: "Create a PRD for adding advanced filtering to the prompts page. Users need to filter by multiple criteria: model, provider, date range, tags, and favorites."

Process:

1. Extract feature name: "Advanced Filtering"
2. Determine category: "features"
3. Generate PRD using template
4. Structure sections:
   • Problem: Users can only filter by single criteria
   • Goals: Multi-criteria filtering, saved filter sets
   • Requirements: UI for filter builder, backend filter query support
   • Phases: Phase 1 (Backend), Phase 2 (Frontend), Phase 3 (Saved Filters)

Output:

File: docs/project_plans/PRDs/features/advanced-filtering-v1.md

# Advanced Filtering - PRD

**Feature Name**: Advanced Filtering
**Date**: 2025-11-11
**Author**: Claude (Sonnet 4.5)
**Related**: Filtering guides, search ADRs

## 1. Executive Summary
Enable users to filter prompts by multiple criteria simultaneously (model, provider, date range, tags, favorites) with the ability to save and reuse filter sets.

## 2. Context & Background
Current filtering supports single criteria only. Users frequently need to filter by combinations (e.g., "OpenAI models from last week tagged 'production'").

... (full PRD structure)

Example 2: Create Implementation Plan with Phase Breakout

Input:

User: "Create implementation plan for docs/project_plans/PRDs/features/advanced-filtering-v1.md"

Process:

1. Read PRD, extract requirements
2. Plan 7 phases following MP architecture
3. Generate task breakdown with estimates
4. Assign subagents to each task
5. Calculate total: 1100 lines → needs breakout
6. Create phase files:
   • phase-1-3-backend.md (500 lines)
   • phase-4-5-frontend.md (400 lines)
   • phase-6-7-validation.md (300 lines)
7. Update parent plan with links (200 lines)

Output:

Main Plan: docs/project_plans/implementation_plans/features/advanced-filtering-v1.md (200 lines)

# Implementation Plan: Advanced Filtering

## Phase Overview
| Phase | Title | Effort | Files |
|-------|-------|--------|-------|
| 1-3 | Backend Implementation | 18 pts | [Details](./advanced-filtering-v1/phase-1-3-backend.md) |
| 4-5 | Frontend Implementation | 12 pts | [Details](./advanced-filtering-v1/phase-4-5-frontend.md) |
| 6-7 | Validation & Deployment | 8 pts | [Details](./advanced-filtering-v1/phase-6-7-validation.md) |

... (executive summary, strategy)

---

Phase Files Created:
- advanced-filtering-v1/phase-1-3-backend.md (500 lines)
  - Phase 1: Database (filter_sets table, indexes)
  - Phase 2: Repository (query builder, filter sets repo)
  - Phase 3: Service (filter validation, DTO mapping)

- advanced-filtering-v1/phase-4-5-frontend.md (400 lines)
  - Phase 4: API (filter endpoints, saved sets API)
  - Phase 5: UI (filter builder component, saved sets UI)

- advanced-filtering-v1/phase-6-7-validation.md (300 lines)
  - Phase 6: Testing (unit, integration, E2E)
  - Phase 7: Deployment (feature flags, monitoring)

Example 3: Optimize Existing Long Plan

Input:

User: "Optimize docs/project_plans/implementation_plans/harden-polish/sidebar-polish-v1.md - it's 1200 lines"

Process:

1. Read plan: 8 phases, ~150 lines each
2. Determine breakout: Group 1-3 (backend), 4-5 (frontend), 6-8 (validation)
3. Create phase files:
   • phase-1-3-backend.md (450 lines)
   • phase-4-5-frontend.md (400 lines)
   • phase-6-8-validation.md (350 lines)
4. Update parent plan: Keep summary, add links to phase files (200 lines)

Output:

Updated: docs/project_plans/implementation_plans/harden-polish/sidebar-polish-v1.md (200 lines)

Created Phase Files:
- sidebar-polish-v1/phase-1-3-backend.md (450 lines)
  Phase 1: Database - Sidebar state, user preferences
  Phase 2: Repository - State management, RLS
  Phase 3: Service - Preference sync, DTOs

- sidebar-polish-v1/phase-4-5-frontend.md (400 lines)
  Phase 4: API - Endpoints for sidebar state
  Phase 5: UI - Sidebar component, animations

- sidebar-polish-v1/phase-6-8-validation.md (350 lines)
  Phase 6: Testing - Unit, integration, visual
  Phase 7: Documentation - Component docs, API docs
  Phase 8: Deployment - Feature flags, rollout

Token Efficiency: 67% reduction for targeted queries

Example 4: Create Progress Tracking

Input:

User: "Create progress tracking for data-layer-fixes-filtering PRD"

Process:

1. Read PRD: docs/project_plans/PRDs/harden-polish/data-layer-fixes-filtering-v1.md
2. Extract "Implementation" section tasks
3. Organize by 5 phases
4. Assign subagents:
   • Phase 1 (Transaction Mgmt): data-layer-expert, python-backend-engineer
   • Phase 2 (Filter Queries): python-backend-engineer
   • Phase 3 (Service Layer): backend-architect, python-backend-engineer
   • Phase 4 (Frontend): ui-engineer-enhanced, frontend-developer
   • Phase 5 (Testing): testing specialists
5. Create progress file with checkboxes and success criteria
6. Update PRD with link to progress file

Output:

Created: .claude/progress/data-layer-fixes-filtering-v1/all-phases-progress.md

Updated PRD Section:
## Implementation

See progress tracking: `.claude/progress/data-layer-fixes-filtering-v1/all-phases-progress.md`

Progress File Structure:
# All-Phases Progress: Data Layer Fixes & Filtering

**Status**: NOT STARTED
**Last Updated**: 2025-11-11
**Completion**: 0% (0 of 24 story points)

## Phase Overview
| Phase | Title | Effort | Status | Completion |
| 1 | Repository - Transaction Mgmt | 8 pts | NOT STARTED | 0% |
| 2 | Repository - Filter Queries | 8 pts | NOT STARTED | 0% |
...

## Phase 1: Repository Layer - Transaction Management
**Assigned Subagent(s)**: data-layer-expert, python-backend-engineer

### Completion Checklist
- [ ] TX-001: Fix BaseRepository Rollback (3 pts)
      Assigned Subagent(s): data-layer-expert
- [ ] TX-002: Update PromptRepository Error Handling (3 pts)
      Assigned Subagent(s): python-backend-engineer
...

### Success Criteria
- [ ] All repository exceptions trigger automatic rollback
- [ ] Transaction state correctly reset after errors
...

Integration with MeatyPrompts

Architecture Compliance

All plans follow MP layered architecture:

• Routers → Services → Repositories → DB
• Services return DTOs only
• Repositories own all DB I/O and RLS
• Cursor pagination for lists: { items, pageInfo }
• ErrorResponse envelope for errors
• OpenTelemetry spans and structured logging

Subagent Ecosystem

Plans integrate with 50+ MeatyPrompts subagents:

Architecture: lead-architect, backend-architect, data-layer-expert Development: python-backend-engineer, frontend-developer, ui-engineer-enhanced UI/UX: ui-designer, ux-researcher Review: code-reviewer, task-completion-validator Documentation: documentation-writer, documentation-complex Testing: testing specialists Performance: react-performance-optimizer, web-accessibility-checker

Documentation Policy

Follows CLAUDE.md documentation policy:

• PRDs are product-planning docs (allowed)
• Implementation Plans are product-planning docs (allowed)
• Progress Tracking follows structured format (.claude/progress/)
• One progress file per feature (all phases)
• Frontmatter required for /docs/, not for .claude/

File Organization

PRDs: /docs/project_plans/PRDs/[category]/[feature-name]-v1.md Plans: /docs/project_plans/implementation_plans/[category]/[feature-name]-v1.md Progress: .claude/progress/[feature-name]/all-phases-progress.md Phase Files: [plan-name]/phase-[N]-[name].md

Advanced Usage

Customizing Templates

Edit templates in ./templates/ to match project needs:

1. PRD Template Customization:

   • Add project-specific sections
   • Adjust success metrics format
   • Include standard acceptance criteria

2. Implementation Plan Template Customization:

   • Add/remove phases
   • Adjust quality gates
   • Customize risk categories

3. Progress Tracking Template Customization:

   • Add project-specific status values
   • Adjust completion tracking format
   • Include team-specific metadata

Multi-PRD Planning

For complex initiatives spanning multiple PRDs:

1. Create parent epic document
2. Generate individual PRDs for each component
3. Link PRDs to parent epic
4. Create unified progress tracking across PRDs

Spike Integration

For research-heavy features:

1. Create SPIKE document first (using spike-writer agent)
2. Use SPIKE to inform PRD generation
3. Reference SPIKE in PRD "Context & Background"
4. Link SPIKE from Implementation Plan

Continuous Optimization

Regularly optimize plans as work progresses:

1. Update progress tracking with actual completion
2. Adjust estimates based on learnings
3. Break out new sections if plan grows >800 lines
4. Archive completed phases

Troubleshooting

PRD Generation Issues

Problem: PRD missing key sections

Solution:

• Check template is complete: ./templates/prd-template.md
• Verify feature description is detailed enough
• Review example PRDs: /docs/project_plans/PRDs/

Implementation Plan Too Long

Problem: Generated plan exceeds 800 lines

Solution:

• Automatically triggers phase breakout
• Creates phase-specific files
• Updates parent with links
• If still too long: Group fewer phases per file

Subagent Assignment Unclear

Problem: Not sure which subagent to assign to task

Solution:

• Check ./references/subagent-assignments.md
• Look for similar tasks in existing progress files
• Default patterns:
  • Database → data-layer-expert
  • Backend → python-backend-engineer
  • Frontend → ui-engineer-enhanced
  • Docs → documentation-writer

File Organization Confusion

Problem: Not sure where to place generated files

Solution:

• Check ./references/file-structure.md
• PRDs: /docs/project_plans/PRDs/[category]/
• Plans: /docs/project_plans/implementation_plans/[category]/
• Progress: .claude/progress/[feature-name]/
• Phase files: Subdirectory of plan: [plan-name]/

Progress Tracking Not Updating

Problem: Progress file created but not linked from PRD

Solution:

• Manually add link to PRD's "Implementation" section
• Format: See progress tracking: .claude/progress/[feature-name]/all-phases-progress.md
• Ensure progress file exists at expected location

Related Skills

• skill-builder: Create new custom skills
• symbols: Token-efficient codebase indexing
• codebase-explorer: Fast pattern discovery
• explore: Deep codebase analysis

Related Agents

• lead-pm: SDLC orchestration
• prd-writer: PRD creation
• implementation-planner: Detailed implementation planning
• task-decomposition-expert: Task breakdown
• lead-architect: Architecture planning assistance
• documentation-writer: Documentation for plans

Version History

• 2025-11-11: Initial skill creation
  • 4 core workflows (PRD, Plan, Optimize, Progress)
  • 4 templates (PRD, Plan, Progress, Phase)
  • 5 scripts (generate-prd, generate-impl-plan, optimize-plan, assign-subagents, create-progress-tracking)
  • 4 references (architecture, subagents, file-structure, optimization-patterns)