planning

Original source / Raw SKILL.md

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

Generate and optimize Product Requirements Documents (PRDs) and Implementation Plans as AI artifacts - file-based context caches optimized for AI agent consumption.

## Purpose

- Generate comprehensive PRDs from feature requests
- Create phased Implementation Plans with subagent task assignments
- Optimize existing planning docs by breaking into token-efficient files
- Set up progress tracking (delegates to artifact-tracking skill)

## Key Benefits

| Benefit | Description |
|---------|-------------|
| Token Efficiency | Max ~800 lines per file for optimal AI context |
| Progressive Disclosure | Summary → Detail pattern with linked files |
| Subagent Integration | Automatic task assignment to specialists |
| MP Architecture | Plans follow layered architecture |

---

## Quick Start

### Create PRD
```bash
User: "Create a PRD for advanced filtering on the prompts page"
# Output: docs/project_plans/PRDs/[category]/advanced-filtering-v1.md
```

### Create Implementation Plan
```bash
User: "Create implementation plan for docs/project_plans/PRDs/features/advanced-filtering-v1.md"
# Output: Main plan + phase files (if >800 lines)
```

### Optimize Existing Plan
```bash
User: "Optimize docs/project_plans/implementation_plans/harden-polish/sidebar-polish-v1.md"
# Breaks 1200-line plan into summary + 3 phase files
```

### Create Progress Tracking
```bash
User: "Create progress tracking for data-layer-fixes PRD"
# Delegates to artifact-tracking skill
```

---

## Core Workflows

| # | Workflow | Input | Output | Details |
|---|----------|-------|--------|---------|
| 1 | Create PRD | Feature request | PRD file | [./workflows/create-prd.md](./workflows/create-prd.md) |
| 2 | Create Implementation Plan | PRD path | Plan + phase files | [./workflows/create-implementation-plan.md](./workflows/create-implementation-plan.md) |
| 3 | Optimize Existing Plan | Plan path (>800 lines) | Optimized structure | [./workflows/optimize-existing-plans.md](./workflows/optimize-existing-plans.md) |
| 4 | Create Progress Tracking | PRD or Plan | Progress artifacts | [./workflows/create-progress-tracking.md](./workflows/create-progress-tracking.md) |

---

## File Organization

### PRDs
```
docs/project_plans/PRDs/[category]/[feature-name]-v1.md
Categories: harden-polish, features, enhancements, refactors
```

### Implementation Plans
```
docs/project_plans/implementation_plans/[category]/[feature-name]-v1.md
Phase files (if >800 lines): [feature-name]-v1/phase-[N]-[name].md
```

See [./references/file-structure.md](./references/file-structure.md) for complete structure.

---

## Templates

| Template | Purpose | Location |
|----------|---------|----------|
| PRD | Standard PRD structure | [./templates/prd-template.md](./templates/prd-template.md) |
| Implementation Plan | Phased plan with tasks | [./templates/implementation-plan-template.md](./templates/implementation-plan-template.md) |
| Phase Breakdown | Individual phase file | [./templates/phase-breakdown-template.md](./templates/phase-breakdown-template.md) |

---

## References

| Reference | Purpose |
|-----------|---------|
| [Subagent Assignments](./references/subagent-assignments.md) | Task type to subagent mapping |
| [File Structure](./references/file-structure.md) | Directory and naming conventions |
| [Optimization Patterns](./references/optimization-patterns.md) | Strategies for breaking up large files |
| [Best Practices](./references/best-practices.md) | Guidelines for effective planning |
| [Workflow Examples](./references/workflow-examples.md) | Detailed usage examples |

---

## Subagent Integration

Plans integrate with 50+ project subagents. Key assignments:

| Domain | Primary Subagents |
|--------|-------------------|
| Database | data-layer-expert |
| Repository | python-backend-engineer, data-layer-expert |
| Service | backend-architect, python-backend-engineer |
| API | python-backend-engineer, backend-architect |
| Frontend | ui-engineer-enhanced, frontend-developer |
| Testing | testing specialist (varies by type) |
| Documentation | documentation-writer, documentation-complex |

See [./references/subagent-assignments.md](./references/subagent-assignments.md) for complete mapping.

---

## Token Efficiency

### Before Optimization
```
Load 1200-line plan for any query = 1200 lines context
```

### After Optimization
```
Overview query: Load 200-line summary only (83% reduction)
Phase query: Load 200 + 400-line phase = 600 lines (50% reduction)
```

See [./references/optimization-patterns.md](./references/optimization-patterns.md) for patterns.

---

## When to Use This Skill

| Scenario | Use This Skill |
|----------|---------------|
| Creating PRDs for new features | Yes |
| Generating implementation plans from PRDs | Yes |
| Breaking down long plans (>800 lines) | Yes |
| Setting up progress tracking | Yes (delegates to artifact-tracking) |
| Optimizing existing plans for AI consumption | Yes |

---

## Related Skills

| Skill | Purpose |
|-------|---------|
| artifact-tracking | Progress tracking and context artifacts |
| skill-builder | Create new custom skills |
| symbols | Token-efficient codebase indexing |
| codebase-explorer | Fast pattern discovery |

## Related Agents

| Agent | Purpose |
|-------|---------|
| lead-pm | SDLC orchestration |
| prd-writer | PRD creation |
| implementation-planner | Detailed planning |
| lead-architect | Architecture decisions |

---

## Request-Log Integration

When feature requests come from request-log items (REQ-YYYYMMDD-*), update their status:

```bash
# Mark item as planned when implementation plan is created
meatycapture log item update DOC ITEM --status planned

# Add note linking to the plan
meatycapture log note add DOC ITEM -c "PRD: docs/project_plans/PRDs/... Implementation plan: docs/project_plans/implementation_plans/..."
```

Use `/mc update` and `/mc note` for token-efficient operations.

---

## Version History

| Date | Changes |
|------|---------|
| 2026-01-06 | Added request-log integration for status updates via `/mc` commands |
| 2025-12-30 | Optimized for progressive disclosure; broke workflows into separate files |
| 2025-12-01 | Removed Tracking Creation; delegated to artifact-tracking skill |
| 2025-11-11 | Initial skill creation with 4 workflows |


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### workflows/create-prd.md

```markdown
# Workflow: 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
- 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`

**Generated 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

[Return to Planning Skill](../SKILL.md)

```

### workflows/create-implementation-plan.md

```markdown
# Workflow: 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

**Common Phase Sequence**:
- Database → Repository → Service → API → UI → Testing → Docs → Deployment

**Grouping Strategy**:
- Group related tasks into phases
- 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

Reference: `../references/subagent-assignments.md`

**Assignment by 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`

**Format**: 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`

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

**Phase Files (if plan >800 lines)**:
- `realtime-collaboration-v1/phase-1-3-backend.md`
- `realtime-collaboration-v1/phase-4-5-frontend.md`
- `realtime-collaboration-v1/phase-6-8-validation.md`

[Return to Planning Skill](../SKILL.md)

```

### workflows/optimize-existing-plans.md

```markdown
# Workflow: 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:

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

- Maintain quality gates summary in parent

### 5. Validate Optimization

Checklist:
- [ ] 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**:

```
sidebar-polish-v1.md (200 lines - summary + links)
├── 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
│   ├── phase-4-5-frontend.md (400 lines)
│   │   - Phase 4: API - Endpoints for sidebar state
│   │   - Phase 5: UI - Sidebar component, animations
│   └── 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

[Return to Planning Skill](../SKILL.md)

```

### workflows/create-progress-tracking.md

```markdown
# Workflow: Create Progress Tracking

**Input**: PRD or Implementation Plan

## Delegation

This workflow delegates to the **artifact-tracking** skill.

Progress tracking and context artifacts have specific optimizations and structures defined in the artifact-tracking skill. Do NOT create these files directly from the planning skill.

## How to Use

When progress tracking is needed:

1. Invoke the artifact-tracking skill
2. Provide the PRD or Implementation Plan path
3. The artifact-tracking skill will create properly structured files at:
   - `.claude/progress/[feature-name]/all-phases-progress.md`
   - Or phase-specific progress files as needed

## Why Delegate?

The artifact-tracking skill provides:
- YAML+Markdown hybrid format with 95% token reduction
- Proper task breakdown with subagent assignments
- Status tracking (pending, in-progress, completed, blocked)
- Session handoff generation
- Validation against schema

## Quick Reference

```bash
# User invokes artifact-tracking skill
User: "Create progress tracking for the advanced-filtering PRD"

# Or use the skill directly
/artifact-tracking CREATE progress for advanced-filtering
```

## Related

- **artifact-tracking skill**: Primary skill for progress artifacts
- **Implementation Plan**: Source for task breakdown
- **PRD**: Source for feature scope and acceptance criteria

[Return to Planning Skill](../SKILL.md)

```

### references/file-structure.md

```markdown
# File Structure Reference

## Directory Organization

### PRDs (Product Requirements Documents)

**Location**: `docs/project_plans/PRDs/[category]/[feature-name]-v1.md`

**Categories**:
- `harden-polish/` - Bug fixes, polish, hardening
- `features/` - New features
- `enhancements/` - Feature enhancements
- `refactors/` - Architecture refactors

**Naming Convention**:
- Format: `[feature-name]-v1.md`
- Use kebab-case (lowercase with hyphens)
- Include version number (-v1, -v2, etc.)
- Descriptive name (e.g., `advanced-filtering-v1.md`)

**Example**:
```
docs/project_plans/PRDs/
├── harden-polish/
│   ├── data-layer-fixes-filtering-v1.md
│   ├── prompt-modal-improvements-v1.md
│   └── sidebar-functionality-polish-v1.md
├── features/
│   ├── realtime-collaboration-v1.md
│   └── advanced-filtering-v1.md
├── enhancements/
│   └── search-improvements-v1.md
└── refactors/
    └── authentication-refactor-v1.md
```

---

### Implementation Plans

**Location**: `docs/project_plans/implementation_plans/[category]/[feature-name]-v1.md`

**Category**: Matches PRD category

**Naming Convention**:
- Format: `[feature-name]-v1.md` (matches PRD name)
- Version synchronized with PRD

**Phase Breakouts**: When plan >800 lines, create subdirectory

**Location**: `docs/project_plans/implementation_plans/[category]/[feature-name]-v1/`

**Phase File Naming**:
- Single phase: `phase-[N]-[name].md`
- Grouped phases: `phase-[N]-[M]-[name].md`
- Descriptive name: `database`, `backend`, `frontend`, `validation`

**Example**:
```
docs/project_plans/implementation_plans/
├── harden-polish/
│   ├── data-layer-fixes-filtering-v1.md       # Main plan (< 800 lines)
│   ├── prompt-modal-improvements-v1.md         # Main plan (summary + links)
│   └── prompt-modal-improvements-v1/           # Phase breakouts
│       ├── phase-1-3-backend.md                # Grouped phases
│       ├── phase-4-5-frontend.md
│       └── phase-6-8-validation.md
├── features/
│   ├── realtime-collaboration-v1.md
│   └── realtime-collaboration-v1/
│       ├── phase-1-database.md                 # Individual phases
│       ├── phase-2-repository.md
│       ├── phase-3-service.md
│       ├── phase-4-api.md
│       ├── phase-5-ui.md
│       ├── phase-6-testing.md
│       ├── phase-7-documentation.md
│       └── phase-8-deployment.md
└── enhancements/
    └── search-improvements-v1.md
```

---

## Naming Conventions Summary

### PRDs
```
Format: [feature-name]-v1.md
Example: data-layer-fixes-filtering-v1.md
Rules:
  - kebab-case (lowercase, hyphens)
  - descriptive name
  - version number (-v1, -v2)
```

### Implementation Plans
```
Format: [feature-name]-v1.md
Example: data-layer-fixes-filtering-v1.md
Rules:
  - matches PRD name exactly
  - same version as PRD
```

### Phase Files
```
Single Phase:
  Format: phase-[N]-[name].md
  Example: phase-1-database.md

Grouped Phases:
  Format: phase-[N]-[M]-[name].md
  Example: phase-1-3-backend.md

Rules:
  - sequential numbering
  - descriptive name (database, backend, frontend, validation)
  - lowercase, hyphens
```

---

## File Size Guidelines

### Optimal Sizes

| File Type | Target Size | Maximum Size | Action if Exceeded |
|-----------|-------------|--------------|-------------------|
| PRD | 400-600 lines | 800 lines | Move sections to appendices |
| Implementation Plan | 400-600 lines | 800 lines | Break into phase files |
| Phase File | 300-500 lines | 800 lines | Split into sub-phases |

### Breakout Strategy

**When to Break Out**:
- PRD >800 lines: Move detailed sections to appendices
- Implementation Plan >800 lines: Break into phase files
- Phase File >800 lines: Split into logical sub-sections

**How to Break Out**:
1. Identify natural boundaries (phases, domains, features)
2. Create subdirectory: `[feature-name]-v1/`
3. Create phase files with descriptive names
4. Update parent with table of contents linking to phase files
5. Keep summary in parent (200-300 lines)

---

## Cross-Linking Pattern

### From PRD to Implementation Plan

**In PRD**:
```markdown
## Implementation

See implementation plan: `docs/project_plans/implementation_plans/[category]/[feature-name]-v1.md`
```

### From PRD to Progress Tracking

**In PRD**:
```markdown
## Implementation

See progress tracking: `.claude/progress/[feature-name]/phase-{PHASE}-progress.md`
```

### From Implementation Plan to Phase Files

**In Parent Plan**:
```markdown
## Phase 2: Repository Layer

See [Phase 2 Implementation Details](./[feature-name]-v1/phase-2-repository.md)
```

### From Phase File to Parent

**At Bottom of Phase File**:
```markdown
[Return to Parent Plan](../[feature-name]-v1.md)
```

---

## YAML Frontmatter Requirements

### PRDs - Required

```yaml
---
title: "Feature Name - PRD"
description: "Brief summary (1-2 sentences)"
audience: [ai-agents, developers]
tags: [relevant, tags]
created: YYYY-MM-DD
updated: YYYY-MM-DD
category: "product-planning"
status: draft|published
related:
  - /docs/path/to/related.md
---
```

### Implementation Plans - Required

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

### Phase Files - Optional

Frontmatter optional for phase files (internal organization).

---

## Token Efficiency Through Structure

### Before Optimization

```
Single 1200-line implementation plan
│
└─ Load entire file for any query = 1200 lines context
```

### After Optimization

```
Parent plan (200 lines) + Phase files (400 lines each)
│
├─ Query about Phase 1 = Load 200 + 400 = 600 lines (50% reduction)
├─ Query about Phase 2 = Load 200 + 400 = 600 lines (50% reduction)
└─ Overview query = Load 200 lines only (83% reduction)
```

### Progressive Disclosure

1. **Level 1**: PRD summary (400 lines)
2. **Level 2**: Implementation plan summary (200 lines)
3. **Level 3**: Specific phase details (400 lines)
4. **Level 4**: Context files for deep dive (varies)

**Total context for targeted work**: ~1000 lines vs. 2000+ without structure

---

## Directory Tree Examples

### Small Feature (No Breakout)

```
project_plans/
├── PRDs/features/
│   └── small-feature-v1.md                     (400 lines)
└── implementation_plans/features/
    └── small-feature-v1.md                     (600 lines)

.claude/progress/
└── small-feature/
    └── all-phases-progress.md
```

### Medium Feature (Phase Breakout)

```
project_plans/
├── PRDs/features/
│   └── medium-feature-v1.md                    (500 lines)
└── implementation_plans/features/
    ├── medium-feature-v1.md                    (200 lines - summary)
    └── medium-feature-v1/
        ├── phase-1-3-backend.md                (500 lines)
        ├── phase-4-5-frontend.md               (400 lines)
        └── phase-6-8-validation.md             (300 lines)

.claude/
├── progress/
│   └── medium-feature/
│       └── all-phases-progress.md
└── worknotes/
    └── medium-feature/
        ├── phase-1-context.md
        └── phase-2-context.md
```

### Large Feature (Full Breakout)

```
project_plans/
├── PRDs/features/
│   └── large-feature-v1.md                     (600 lines)
└── implementation_plans/features/
    ├── large-feature-v1.md                     (250 lines - summary)
    └── large-feature-v1/
        ├── phase-1-database.md                 (400 lines)
        ├── phase-2-repository.md               (450 lines)
        ├── phase-3-service.md                  (500 lines)
        ├── phase-4-api.md                      (400 lines)
        ├── phase-5-ui.md                       (500 lines)
        ├── phase-6-testing.md                  (450 lines)
        ├── phase-7-documentation.md            (300 lines)
        └── phase-8-deployment.md               (250 lines)

.claude/
├── progress/
│   └── large-feature/
        ├── phase-1-progress.md
        ├── phase-2-progress.md
        ├── phase-3-progress.md
        ├── phase-4-progress.md
        └── phase-5-progress.md
└── worknotes/
    └── large-feature/
        ├── phase-1-context.md
        ├── phase-2-context.md
        ├── phase-3-context.md
        ├── phase-4-context.md
        └── phase-5-context.md
```

---

## Best Practices

1. **Match Names**: PRD, plan, and progress directory names should match
2. **Version Sync**: PRD and plan versions should match
3. **Logical Grouping**: Group related short phases (1-3, 4-5, 6-8)
4. **Token Efficiency**: Keep files <800 lines for optimal AI loading
5. **Progressive Disclosure**: Summary in parent, details in phase files
6. **Cross-Link**: Always link related documents
7. **Descriptive Names**: Use intention-revealing names for phase files
8. **Consistent Structure**: Follow templates for consistency

---

## Anti-Patterns to Avoid

❌ Generic phase names (`phase-1.md` instead of `phase-1-database.md`)
❌ Mismatched PRD/plan names
❌ Missing cross-links between documents
❌ Files >800 lines without breakout
❌ Deep nesting (keep structure flat)
❌ Version mismatches between PRD and plan
❌ Inconsistent naming conventions

```

### templates/prd-template.md

```markdown
---
title: "PRD: Feature Name"
description: "High-level summary of the feature being proposed"
audience: [ai-agents, developers]
tags: [prd, planning, feature]
created: YYYY-MM-DD
updated: YYYY-MM-DD
category: "product-planning"
status: draft
related: []
---

# Feature Brief & Metadata

**Feature Name:**

> [Feature Name Here]

**Filepath Name:**

> `[feature-name-v1]` (kebab-case)

**Date:**

> YYYY-MM-DD

**Author:**

> [Author Name/Agent]

**Related Epic(s)/PRD ID(s):**

> [Epic ID or related PRD references]

**Related Documents:**

> - [Architecture Decision Record (if applicable)]
> - [Related PRDs or guides]
> - [Symbol references]

---

## 1. Executive Summary

A concise paragraph (2-3 sentences) explaining what this feature delivers and why it matters. Provide just enough context to orient the reader.

**Priority:** [CRITICAL | HIGH | MEDIUM | LOW]

**Key Outcomes:**
- Outcome 1: [What users will be able to do]
- Outcome 2: [What problem is solved]
- Outcome 3: [What metric improves]

---

## 2. Context & Background

### Current State

[Describe the current state of the system]

### Problem Space

Describe the problem that motivates this feature. What pain points do users experience? What gaps exist in the current system?

### Current Alternatives / Workarounds

Explain what exists today and why it is insufficient. What workarounds do users employ? Why are they inadequate?

### Market / Competitive Notes (Optional)

Include relevant market trends or competitor features if applicable.

### Architectural Context

[Reference MeatyPrompts layered architecture]
- **Routers** - HTTP + validation, return DTOs
- **Services** - Business logic, return DTOs only
- **Repositories** - All DB I/O, RLS enforcement, cursor pagination
- **ErrorResponse** - Envelope for all failures
- **Cursor Pagination** - `{ items, pageInfo }` format

---

## 3. Problem Statement

State the core gap or pain point in plain language.

**User Story Format:**
> "As a [user type], when I [action], I [problem] instead of [desired outcome]."

**Technical Root Cause (if known):**
- [Root cause 1]
- [Root cause 2]
- [Files involved]

---

## 4. Goals & Success Metrics

### Primary Goals

**Goal 1: [Goal Name]**
- Description of goal
- Measurable success criteria

**Goal 2: [Goal Name]**
- Description of goal
- Measurable success criteria

**Goal 3: [Goal Name]**
- Description of goal
- Measurable success criteria

### Success Metrics

| Metric | Baseline | Target | Measurement Method |
|--------|----------|--------|-------------------|
| [Metric 1] | [Current value] | [Target value] | [How to measure] |
| [Metric 2] | [Current value] | [Target value] | [How to measure] |

---

## 5. User Personas & Journeys

### Personas

**Primary Persona: [Name]**
- Role: [User role]
- Needs: [What they need from this feature]
- Pain Points: [Current frustrations]

**Secondary Persona: [Name]**
- Role: [User role]
- Needs: [What they need from this feature]
- Pain Points: [Current frustrations]

### High-level Flow

[Optional: Include a Mermaid diagram to show the user journey or system flow]

```mermaid
graph TD
    A[User Action] --> B[System Response]
    B --> C[Outcome]
```

---

## 6. Requirements

### 6.1 Functional Requirements

| ID | Requirement | Priority | Notes |
| :-: | ----------- | :------: | ----- |
| FR-1 | [Requirement description] | Must | [Additional context] |
| FR-2 | [Requirement description] | Should | [Additional context] |
| FR-3 | [Requirement description] | Could | [Additional context] |

### 6.2 Non-Functional Requirements

**Performance:**
- [Performance requirement 1]
- [Performance requirement 2]

**Security:**
- [Security requirement 1]
- [Security requirement 2]

**Accessibility:**
- [Accessibility requirement 1]
- [Accessibility requirement 2]

**Reliability:**
- [Reliability requirement 1]
- [Reliability requirement 2]

**Observability:**
- OpenTelemetry spans for all operations
- Structured JSON logs with trace_id, span_id, user_id
- Error tracking and monitoring

---

## 7. Scope

### In Scope

- [Component/feature 1 in scope]
- [Component/feature 2 in scope]
- [Component/feature 3 in scope]

### Out of Scope

- [Deliberately excluded area 1]
- [Deliberately excluded area 2]
- [Future considerations]

---

## 8. Dependencies & Assumptions

### External Dependencies

- **Library/Service 1**: [Description and version]
- **Library/Service 2**: [Description and version]

### Internal Dependencies

- **Feature/System 1**: [Description and status]
- **Feature/System 2**: [Description and status]

### Assumptions

- [Assumption 1]
- [Assumption 2]
- [Assumption 3]

### Feature Flags

- [Feature flag name]: [Description]

---

## 9. Risks & Mitigations

| Risk | Impact | Likelihood | Mitigation |
| ----- | :----: | :--------: | ---------- |
| [Risk description] | High/Med/Low | High/Med/Low | [Mitigation strategy] |
| [Risk description] | High/Med/Low | High/Med/Low | [Mitigation strategy] |

---

## 10. Target State (Post-Implementation)

Describe how the system will behave after the feature is delivered.

**User Experience:**
- [How users interact with the feature]
- [What workflows are enabled]

**Technical Architecture:**
- [How components interact]
- [Data flow and storage]
- [Integration points]

**Observable Outcomes:**
- [What metrics change]
- [What behaviors are enabled]
- [What problems are solved]

---

## 11. Overall Acceptance Criteria (Definition of Done)

### Functional Acceptance

- [ ] All functional requirements (FR-1 through FR-N) implemented
- [ ] User workflows complete end-to-end
- [ ] All edge cases handled

### Technical Acceptance

- [ ] Follows MeatyPrompts layered architecture
- [ ] All APIs return DTOs (no ORM models)
- [ ] Cursor pagination for all lists
- [ ] ErrorResponse envelope for all errors
- [ ] OpenTelemetry spans for all operations
- [ ] Structured logging with trace_id, span_id, user_id

### Quality Acceptance

- [ ] Unit tests achieve >80% coverage
- [ ] Integration tests cover all API endpoints
- [ ] E2E tests cover critical user journeys
- [ ] Performance benchmarks met
- [ ] Accessibility WCAG 2.1 AA compliance
- [ ] Security review passed

### Documentation Acceptance

- [ ] API documentation complete
- [ ] Component documentation complete
- [ ] User guides created
- [ ] ADRs updated for architectural decisions

---

## 12. Assumptions & Open Questions

### Assumptions

- [Assumption 1 made during planning]
- [Assumption 2 made during planning]

### Open Questions

- [ ] **Q1**: [Question text]
  - **A**: [Answer or "TBD"]
- [ ] **Q2**: [Question text]
  - **A**: [Answer or "TBD"]

---

## 13. Appendices & References

### Related Documentation

- **ADRs**: [Links to Architecture Decision Records]
- **Design Specifications**: [Links to design docs]
- **Technical Audits**: [Links to audit reports]
- **Flow Diagrams**: [Links to flow documentation]

### Symbol References

- **API Symbols**: [Relevant symbols from ai/symbols-api.json]
- **UI Symbols**: [Relevant symbols from ai/symbols-ui.json]

### Prior Art

- [Link to similar implementations]
- [Link to research or SPIKE documents]

---

## Implementation

### Phased Approach

**Phase 1: [Phase Name]**
- Duration: [X days]
- Tasks:
  - [ ] Task 1: [Description]
  - [ ] Task 2: [Description]

**Phase 2: [Phase Name]**
- Duration: [X days]
- Tasks:
  - [ ] Task 1: [Description]
  - [ ] Task 2: [Description]

**Phase 3: [Phase Name]**
- Duration: [X days]
- Tasks:
  - [ ] Task 1: [Description]
  - [ ] Task 2: [Description]

### Epics & User Stories Backlog

| Story ID | Short Name | Description | Acceptance Criteria | Estimate |
|----------|-----------|-------------|-------------------|----------|
| [ID-001] | [Name] | [Description] | [Criteria] | [Points] |
| [ID-002] | [Name] | [Description] | [Criteria] | [Points] |

---

**Progress Tracking:**

See progress tracking: `.claude/progress/[feature-name]/all-phases-progress.md`

---

Use this template as a starting point for every new feature PRD. Tailor the sections to suit the project while retaining the overall structure and ensuring MeatyPrompts architecture compliance.

```

### templates/implementation-plan-template.md

```markdown
---
title: "Implementation Plan: Feature Name"
description: "Detailed phased implementation with task breakdown and subagent assignments"
audience: [ai-agents, developers]
tags: [implementation, planning, phases, tasks]
created: YYYY-MM-DD
updated: YYYY-MM-DD
category: "product-planning"
status: draft
related:
  - /docs/project_plans/PRDs/category/feature-name-v1.md
---

# Implementation Plan: [Feature Name]

**Plan ID**: `IMPL-{YYYY-MM-DD}-{FEATURE-NAME}`
**Date**: YYYY-MM-DD
**Author**: [Implementation Planner Agent]
**Related Documents**:
- **PRD**: `/docs/project_plans/PRDs/[category]/[feature-name]-v1.md`
- **ADRs**: [Links to relevant Architecture Decision Records]

**Complexity**: [Small | Medium | Large | XL]
**Total Estimated Effort**: [Total story points]
**Target Timeline**: [Start date] - [End date]

## Executive Summary

[2-3 sentences describing the implementation approach, key milestones, and success criteria]

## Implementation Strategy

### Architecture Sequence

Following MeatyPrompts layered architecture:
1. **Database Layer** - Tables, indexes, RLS policies
2. **Repository Layer** - DB I/O, transactions, cursor pagination
3. **Service Layer** - Business logic, DTOs, validation
4. **API Layer** - FastAPI routers, endpoints, OpenAPI docs
5. **UI Layer** - React components from @meaty/ui
6. **Testing Layer** - Unit, integration, E2E
7. **Documentation Layer** - API docs, component docs, guides
8. **Deployment Layer** - Feature flags, monitoring, rollout

### Parallel Work Opportunities

[Identify tasks that can be done in parallel to optimize timeline]

### Critical Path

[Identify the critical path that determines overall timeline]

## Phase Breakdown

### Phase 1: Database Foundation

**Duration**: [X days]
**Dependencies**: None
**Assigned Subagent(s)**: data-layer-expert

| Task ID | Task Name | Description | Acceptance Criteria | Estimate | Subagent(s) | Dependencies |
|---------|-----------|-------------|-------------------|----------|-------------|--------------|
| DB-001 | Schema Design | Create database schema | Schema validates, migrations run cleanly | 3 pts | data-layer-expert | None |
| DB-002 | RLS Policies | Implement Row Level Security | Security enforces correct boundaries | 2 pts | data-layer-expert | DB-001 |
| DB-003 | Indexes & Performance | Add indexes for query optimization | Query performance meets benchmarks | 1 pt | data-layer-expert | DB-001 |

**Phase 1 Quality Gates:**
- [ ] Schema migrations run successfully
- [ ] RLS policies enforce correct boundaries
- [ ] Performance benchmarks met
- [ ] Database backup/recovery tested

---

### Phase 2: Repository Layer

**Duration**: [X days]
**Dependencies**: Phase 1 complete
**Assigned Subagent(s)**: python-backend-engineer, data-layer-expert

| Task ID | Task Name | Description | Acceptance Criteria | Estimate | Subagent(s) | Dependencies |
|---------|-----------|-------------|-------------------|----------|-------------|--------------|
| REPO-001 | Base Repository | Create repository interface | Interface supports CRUD + pagination | 2 pts | python-backend-engineer | DB-003 |
| REPO-002 | Query Methods | Implement specific queries | All queries use cursor pagination | 3 pts | python-backend-engineer | REPO-001 |
| REPO-003 | Transaction Handling | Add rollback on errors | Exceptions trigger automatic rollback | 2 pts | data-layer-expert | REPO-001 |

**Phase 2 Quality Gates:**
- [ ] All CRUD operations working
- [ ] Cursor pagination implemented
- [ ] Transaction rollback working
- [ ] Repository tests achieve >80% coverage

---

### Phase 3: Service Layer

**Duration**: [X days]
**Dependencies**: Phase 2 complete
**Assigned Subagent(s)**: python-backend-engineer, backend-architect

| Task ID | Task Name | Description | Acceptance Criteria | Estimate | Subagent(s) | Dependencies |
|---------|-----------|-------------|-------------------|----------|-------------|--------------|
| SVC-001 | DTO Definitions | Create DTOs for request/response | DTOs validate with schemas | 2 pts | python-backend-engineer | REPO-003 |
| SVC-002 | Business Logic | Implement core business logic | Logic passes unit tests, returns DTOs | 5 pts | backend-architect | SVC-001 |
| SVC-003 | Error Handling | Implement error patterns | Errors use ErrorResponse envelope | 1 pt | python-backend-engineer | SVC-002 |
| SVC-004 | Observability | Add OpenTelemetry spans | Spans/logs for all operations | 2 pts | backend-architect | SVC-002 |

**Phase 3 Quality Gates:**
- [ ] Business logic unit tests pass
- [ ] DTOs validate correctly
- [ ] ErrorResponse envelope used
- [ ] OpenTelemetry instrumentation complete

---

### Phase 4: API Layer

**Duration**: [X days]
**Dependencies**: Phase 3 complete
**Assigned Subagent(s)**: python-backend-engineer, backend-architect

| Task ID | Task Name | Description | Acceptance Criteria | Estimate | Subagent(s) | Dependencies |
|---------|-----------|-------------|-------------------|----------|-------------|--------------|
| API-001 | Router Setup | Create API router with endpoints | Routes defined with OpenAPI docs | 2 pts | python-backend-engineer | SVC-004 |
| API-002 | Request Validation | Implement request validation | Invalid requests return 400 | 2 pts | python-backend-engineer | API-001 |
| API-003 | Response Formatting | Standardize response formats | Consistent envelope, cursor pagination | 1 pt | python-backend-engineer | API-002 |
| API-004 | Authentication | Integrate Clerk authentication | Endpoints properly secured | 2 pts | backend-architect | API-001 |

**Phase 4 Quality Gates:**
- [ ] All endpoints return correct responses
- [ ] OpenAPI documentation complete
- [ ] ErrorResponse envelope consistent
- [ ] Authentication working correctly

---

### Phase 5: UI Layer

**Duration**: [X days]
**Dependencies**: Phase 4 complete (can start design earlier)
**Assigned Subagent(s)**: ui-engineer-enhanced, frontend-developer, ui-designer

| Task ID | Task Name | Description | Acceptance Criteria | Estimate | Subagent(s) | Dependencies |
|---------|-----------|-------------|-------------------|----------|-------------|--------------|
| UI-001 | Component Design | Design/update UI components | Components support all states | 3 pts | ui-designer | API-004 |
| UI-002 | Hooks Implementation | Create state management hooks | Hooks handle loading/error/success | 2 pts | frontend-developer | UI-001 |
| UI-003 | Component Implementation | Implement components in @meaty/ui | Components render correctly | 3 pts | ui-engineer-enhanced | UI-002 |
| UI-004 | API Integration | Integrate with backend API | UI reflects backend functionality | 3 pts | frontend-developer | UI-003 |
| UI-005 | Accessibility | Implement a11y features | WCAG 2.1 AA compliance | 2 pts | ui-engineer-enhanced | UI-004 |
| UI-006 | Responsive Design | Ensure mobile responsiveness | Works on all device sizes | 2 pts | frontend-developer | UI-004 |

**Phase 5 Quality Gates:**
- [ ] Components render in all states
- [ ] User interactions work correctly
- [ ] Accessibility requirements met
- [ ] Mobile responsiveness validated
- [ ] Backend integration working

---

### Phase 6: Testing Layer

**Duration**: [X days]
**Dependencies**: Previous phases complete
**Assigned Subagent(s)**: testing specialists, all developers

| Task ID | Task Name | Description | Acceptance Criteria | Estimate | Subagent(s) | Dependencies |
|---------|-----------|-------------|-------------------|----------|-------------|--------------|
| TEST-001 | Unit Tests | Create unit tests for all layers | >80% code coverage | 5 pts | all developers | UI-006 |
| TEST-002 | Integration Tests | Create API integration tests | All endpoints tested | 3 pts | python-backend-engineer | TEST-001 |
| TEST-003 | Component Tests | Create component tests | All UI interactions tested | 3 pts | frontend-developer | TEST-001 |
| TEST-004 | E2E Tests | Create end-to-end tests | Critical paths covered | 2 pts | testing specialist | TEST-003 |
| TEST-005 | Performance Tests | Create performance benchmarks | Performance targets met | 2 pts | python-backend-engineer | TEST-002 |
| TEST-006 | Accessibility Tests | Automated a11y testing | A11y tests pass | 1 pt | ui-engineer-enhanced | TEST-003 |

**Phase 6 Quality Gates:**
- [ ] Code coverage >80%
- [ ] All tests passing in CI/CD
- [ ] E2E tests cover critical journeys
- [ ] Performance benchmarks met
- [ ] Accessibility compliance validated

---

### Phase 7: Documentation Layer

**Duration**: [X days]
**Dependencies**: Implementation complete
**Assigned Subagent(s)**: documentation-writer, api-documenter

| Task ID | Task Name | Description | Acceptance Criteria | Estimate | Subagent(s) | Dependencies |
|---------|-----------|-------------|-------------------|----------|-------------|--------------|
| DOC-001 | API Documentation | Update API documentation | All endpoints documented | 1 pt | api-documenter | TEST-006 |
| DOC-002 | Component Docs | Create component docs | All components documented | 2 pts | documentation-writer | TEST-006 |
| DOC-003 | User Guides | Create user-facing docs | Users can complete workflows | 2 pts | documentation-writer | TEST-006 |
| DOC-004 | Developer Guides | Create technical docs | Developers can extend/maintain | 2 pts | documentation-writer | TEST-006 |
| DOC-005 | ADR Updates | Update ADRs | All decisions documented | 1 pt | lead-architect | DOC-004 |

**Phase 7 Quality Gates:**
- [ ] API documentation complete
- [ ] Component documentation complete
- [ ] User guides approved
- [ ] Developer docs comprehensive
- [ ] ADRs updated

---

### Phase 8: Deployment Layer

**Duration**: [X days]
**Dependencies**: All phases complete
**Assigned Subagent(s)**: DevOps, lead-pm

| Task ID | Task Name | Description | Acceptance Criteria | Estimate | Subagent(s) | Dependencies |
|---------|-----------|-------------|-------------------|----------|-------------|--------------|
| DEPLOY-001 | Feature Flags | Implement feature flags | Feature can be toggled safely | 1 pt | DevOps | DOC-005 |
| DEPLOY-002 | Monitoring | Add telemetry and monitoring | All operations instrumented | 2 pts | DevOps | DEPLOY-001 |
| DEPLOY-003 | Staging Deployment | Deploy to staging | Feature works in staging | 1 pt | DevOps | DEPLOY-002 |
| DEPLOY-004 | Production Rollout | Execute production rollout | Rollout completed successfully | 2 pts | lead-pm | DEPLOY-003 |
| DEPLOY-005 | Post-Launch Monitoring | Monitor and respond | Feature stable in production | 1 pt | all team | DEPLOY-004 |

**Phase 8 Quality Gates:**
- [ ] Feature flags working
- [ ] Monitoring and alerting active
- [ ] Staging deployment successful
- [ ] Production rollout completed
- [ ] Post-launch metrics healthy

---

## Risk Mitigation

### Technical Risks

| Risk | Impact | Likelihood | Mitigation Strategy |
|------|--------|------------|-------------------|
| Database performance issues | High | Medium | Pre-optimize queries, add indexes |
| Integration failures | High | Low | Isolated testing, rollback procedures |
| UI/UX complexity | Medium | Medium | Early designer review, user testing |

### Schedule Risks

| Risk | Impact | Likelihood | Mitigation Strategy |
|------|--------|------------|-------------------|
| Scope creep | Medium | High | Change request process |
| Resource constraints | High | Medium | Task prioritization, phased delivery |
| Dependency delays | Medium | Medium | Parallel work streams |

---

## Resource Requirements

### Team Composition
- Backend Developer: 2 FTE (phases 1-4), part-time (5-8)
- Frontend Developer: 1 FTE (phase 5), part-time (1-4, 6-8)
- UI/UX Designer: Part-time (phase 5, reviews)
- DevOps Engineer: Part-time (throughout), FTE (phase 8)
- QA Specialist: Part-time (phase 6)

### Skill Requirements
- TypeScript/JavaScript, FastAPI, SQLAlchemy, React, React Query
- PostgreSQL, Git, CI/CD, OpenTelemetry, Storybook
- Accessibility (WCAG 2.1 AA), Performance optimization

---

## Success Metrics

### Delivery Metrics
- On-time delivery (±10%)
- Code coverage >80%
- Performance benchmarks met
- Zero P0/P1 bugs in first week

### Business Metrics
- [Feature-specific metrics]
- Error rate <1%
- User satisfaction >4/5

### Technical Metrics
- 100% API documentation
- 100% WCAG 2.1 AA compliance
- Security review passed

---

## Communication Plan

- Daily standups for progress/blockers
- Weekly status reports on milestones
- Formal phase reviews
- Bi-weekly stakeholder updates

---

## Post-Implementation

- Performance monitoring dashboards
- Error tracking and resolution
- User feedback collection
- Technical debt planning
- Feature iteration based on usage

---

**Progress Tracking:**

See `.claude/progress/[feature-name]/all-phases-progress.md`

---

**Implementation Plan Version**: 1.0
**Last Updated**: YYYY-MM-DD

```

### templates/phase-breakdown-template.md

```markdown
# Phase [N]: [Phase Name]

**Parent Plan**: [Link to parent implementation plan]
**Duration**: [X] days
**Effort**: [X] story points
**Dependencies**: [Phase N-1 complete | None]
**Team Members**: [Developer roles needed]

---

## Phase Overview

[Brief description of what this phase accomplishes and why it's needed]

### Goals

- [Goal 1]
- [Goal 2]
- [Goal 3]

### Architecture Focus

This phase implements the [layer name] following MeatyPrompts architecture:
- **Layer**: [Database | Repository | Service | API | UI | Testing | Documentation | Deployment]
- **Patterns**: [Specific patterns used]
- **Standards**: [Relevant standards]

---

## Task Breakdown

### Epic: [Epic Name]

| Task ID | Task Name | Description | Acceptance Criteria | Estimate | Assigned Subagent(s) | Dependencies |
|---------|-----------|-------------|-------------------|----------|---------------------|--------------|
| [ID-001] | [Task Name] | [Description] | [Criteria] | [X] pts | [subagent-1, subagent-2] | [None or ID] |
| [ID-002] | [Task Name] | [Description] | [Criteria] | [X] pts | [subagent-1] | [ID-001] |
| [ID-003] | [Task Name] | [Description] | [Criteria] | [X] pts | [subagent-1] | [ID-001] |

---

## Detailed Task Specifications

### Task [ID-001]: [Task Name]

**Estimate**: [X] points
**Assigned Subagent(s)**: [subagent-1, subagent-2]
**Dependencies**: [None or other task IDs]

**Description**:
[Detailed description of what needs to be done]

**Acceptance Criteria**:
- [ ] [Criterion 1 with specific, measurable outcome]
- [ ] [Criterion 2 with specific, measurable outcome]
- [ ] [Criterion 3 with specific, measurable outcome]

**Implementation Notes**:
- [Note 1: Technical approach or pattern to use]
- [Note 2: Files to modify or create]
- [Note 3: Integration points to consider]

**Files Involved**:
- `path/to/file1.py` - [What changes are needed]
- `path/to/file2.tsx` - [What changes are needed]

---

### Task [ID-002]: [Task Name]

**Estimate**: [X] points
**Assigned Subagent(s)**: [subagent-1]
**Dependencies**: [ID-001]

**Description**:
[Detailed description]

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

**Implementation Notes**:
- [Note 1]

**Files Involved**:
- `path/to/file.py` - [Changes needed]

---

## Quality Gates

This phase is complete when:

- [ ] **Functional**: [All features working as specified]
- [ ] **Testing**: [Required test coverage achieved]
- [ ] **Performance**: [Performance benchmarks met]
- [ ] **Security**: [Security requirements met]
- [ ] **Documentation**: [Documentation complete]
- [ ] **Code Quality**: [Linting and quality checks pass]
- [ ] **Architecture**: [Follows MeatyPrompts patterns]

---

## Integration Points

### External Systems

- **System 1**: [How this phase integrates]
- **System 2**: [How this phase integrates]

### Internal Systems

- **Component 1**: [Integration details]
- **Component 2**: [Integration details]

---

## Key Files Modified

| File Path | Lines | Purpose | Subagent |
|-----------|-------|---------|----------|
| `path/to/file1.py` | 100-150 | [Purpose] | [subagent-1] |
| `path/to/file2.tsx` | 50-80 | [Purpose] | [subagent-2] |
| `path/to/file3.sql` | - | [Purpose] | [subagent-1] |

---

## Testing Strategy

### Unit Tests

- [What unit tests are needed]
- [Coverage targets]

### Integration Tests

- [What integration tests are needed]
- [What scenarios to cover]

### E2E Tests (if applicable)

- [What E2E tests are needed]
- [What user journeys to cover]

---

## Risk Mitigation

| Risk | Impact | Mitigation |
|------|--------|-----------|
| [Risk 1] | [High/Med/Low] | [How to mitigate] |
| [Risk 2] | [High/Med/Low] | [How to mitigate] |

---

## Success Metrics

- **Completion**: All tasks checked off
- **Quality**: All quality gates passed
- **Performance**: [Specific performance targets]
- **Testing**: [Coverage and passing tests]

---

## Notes

### Implementation Approach

[Notes about the overall approach for this phase]

### Gotchas

- [Gotcha 1]: [What to watch out for]
- [Gotcha 2]: [What to watch out for]

### Learnings

[Capture learnings as phase progresses]

---

**Phase Version**: 1.0
**Last Updated**: YYYY-MM-DD

[Return to Parent Plan](../[feature-name]-v1.md)

```

### references/subagent-assignments.md

```markdown
# Subagent Assignment Reference

## Task Type to Subagent Mapping

This reference helps assign the appropriate specialist subagents to implementation tasks based on task type and domain.

---

## Database Layer Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Schema Design | data-layer-expert | backend-architect | Tables, columns, relationships |
| Migrations | data-layer-expert | python-backend-engineer | Alembic migrations |
| RLS Policies | data-layer-expert | - | Row Level Security |
| Indexes | data-layer-expert | - | Performance optimization |
| Constraints | data-layer-expert | - | Foreign keys, unique constraints |
| Audit Triggers | data-layer-expert | backend-architect | Audit logging triggers |

**Example**:
```markdown
- [ ] DB-001: Schema Design (3 pts)
      Assigned Subagent(s): data-layer-expert, backend-architect
```

---

## Repository Layer Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Base Repository | python-backend-engineer | data-layer-expert | CRUD operations |
| Query Methods | python-backend-engineer | - | Specific queries |
| Cursor Pagination | python-backend-engineer | data-layer-expert | Pagination logic |
| Transaction Handling | data-layer-expert | python-backend-engineer | Rollback patterns |
| RLS Integration | data-layer-expert | python-backend-engineer | Security enforcement |
| ORM Relationships | python-backend-engineer | data-layer-expert | SQLAlchemy relationships |

**Example**:
```markdown
- [ ] REPO-001: Query Methods (3 pts)
      Assigned Subagent(s): python-backend-engineer
```

---

## Service Layer Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| DTO Definitions | python-backend-engineer | backend-architect | Pydantic schemas |
| Business Logic | backend-architect | python-backend-engineer | Core workflows |
| Validation | python-backend-engineer | - | Input validation |
| Error Handling | python-backend-engineer | backend-architect | ErrorResponse patterns |
| Observability | backend-architect | - | OpenTelemetry spans |
| Service Integration | backend-architect | python-backend-engineer | Multi-service orchestration |

**Example**:
```markdown
- [ ] SVC-002: Business Logic (5 pts)
      Assigned Subagent(s): backend-architect, python-backend-engineer
```

---

## API Layer Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Router Setup | python-backend-engineer | backend-architect | FastAPI routers |
| Endpoint Implementation | python-backend-engineer | - | Request handlers |
| Request Validation | python-backend-engineer | - | Pydantic models |
| Response Formatting | python-backend-engineer | - | DTO serialization |
| Authentication | backend-architect | python-backend-engineer | Clerk integration |
| OpenAPI Documentation | api-documenter | python-backend-engineer | Swagger specs |
| API Versioning | backend-architect | - | Version strategy |

**Example**:
```markdown
- [ ] API-001: Router Setup (2 pts)
      Assigned Subagent(s): python-backend-engineer, backend-architect
```

---

## Frontend Layer Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Component Design | ui-designer | ux-researcher | Wireframes, mockups |
| Component Implementation | ui-engineer-enhanced | - | React components |
| State Management | frontend-developer | - | React Query, context |
| Hooks | frontend-developer | - | Custom hooks |
| API Integration | frontend-developer | ui-engineer-enhanced | Backend integration |
| Forms | frontend-developer | ui-engineer-enhanced | Form handling |
| Routing | frontend-developer | nextjs-architecture-expert | Next.js App Router |
| Styling | ui-engineer-enhanced | ui-designer | Tailwind, CSS |

**Example**:
```markdown
- [ ] UI-001: Component Design (3 pts)
      Assigned Subagent(s): ui-designer, ux-researcher
```

---

## Mobile Layer Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Screen Design | ui-designer | ux-researcher | Mobile wireframes |
| Screen Implementation | mobile-app-builder | - | React Native screens |
| Navigation | mobile-app-builder | - | React Navigation |
| Expo Configuration | mobile-app-builder | - | app.json, plugins |
| Native Modules | mobile-app-builder | - | Platform-specific code |
| Push Notifications | mobile-app-builder | backend-architect | Notification setup |

**Example**:
```markdown
- [ ] MOB-001: Screen Implementation (3 pts)
      Assigned Subagent(s): mobile-app-builder
```

---

## Testing Layer Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Unit Tests (Backend) | python-backend-engineer | - | pytest |
| Unit Tests (Frontend) | frontend-developer | - | Jest, Vitest |
| Integration Tests (API) | python-backend-engineer | data-layer-expert | API + DB tests |
| Component Tests | frontend-developer | ui-engineer-enhanced | React Testing Library |
| E2E Tests | testing specialist | frontend-developer | Playwright |
| Performance Tests | python-backend-engineer | backend-architect | Load testing |
| Accessibility Tests | web-accessibility-checker | ui-engineer-enhanced | WCAG compliance |
| Visual Regression | testing specialist | ui-designer | Screenshot tests |

**Example**:
```markdown
- [ ] TEST-002: Integration Tests (3 pts)
      Assigned Subagent(s): python-backend-engineer, data-layer-expert
```

---

## Documentation Layer Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| API Documentation | api-documenter | python-backend-engineer | Endpoint docs |
| Component Documentation | documentation-writer | ui-engineer-enhanced | Storybook docs |
| User Guides | documentation-writer | - | How-to guides |
| Developer Guides | documentation-writer | - | Technical guides |
| Architecture Docs | documentation-complex | lead-architect | Multi-system docs |
| ADRs | lead-architect | backend-architect | Decision records |
| README Files | documentation-writer | - | Package READMEs |
| Changelog | changelog-generator | - | Version history |

**Example**:
```markdown
- [ ] DOC-001: API Documentation (1 pt)
      Assigned Subagent(s): api-documenter, python-backend-engineer
```

---

## Performance & Optimization Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| React Optimization | react-performance-optimizer | frontend-developer | Memoization, lazy loading |
| Database Optimization | data-layer-expert | python-backend-engineer | Query optimization |
| API Performance | backend-architect | python-backend-engineer | Caching, batching |
| Bundle Optimization | frontend-developer | nextjs-architecture-expert | Code splitting |
| Image Optimization | ui-engineer-enhanced | - | Image formats, CDN |

**Example**:
```markdown
- [ ] PERF-001: React Optimization (2 pts)
      Assigned Subagent(s): react-performance-optimizer, frontend-developer
```

---

## Accessibility Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| WCAG Compliance | web-accessibility-checker | ui-engineer-enhanced | Accessibility audit |
| Screen Reader Support | web-accessibility-checker | ui-engineer-enhanced | ARIA labels |
| Keyboard Navigation | web-accessibility-checker | frontend-developer | Focus management |
| Color Contrast | ui-designer | web-accessibility-checker | Contrast ratios |
| Form Accessibility | ui-engineer-enhanced | web-accessibility-checker | Label associations |

**Example**:
```markdown
- [ ] A11Y-001: WCAG Compliance (2 pts)
      Assigned Subagent(s): web-accessibility-checker, ui-engineer-enhanced
```

---

## DevOps & Deployment Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Feature Flags | DevOps | backend-architect | Toggle configuration |
| Monitoring Setup | DevOps | backend-architect | OpenTelemetry config |
| CI/CD Pipeline | DevOps | - | GitHub Actions |
| Deployment | DevOps | lead-pm | Staging/production |
| Docker Configuration | DevOps | - | Containerization |
| Environment Config | DevOps | backend-architect | Env variables |

**Example**:
```markdown
- [ ] DEPLOY-001: Feature Flags (1 pt)
      Assigned Subagent(s): DevOps, backend-architect
```

---

## Refactoring Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Code Refactoring | refactoring-expert | - | Code quality |
| Architecture Refactoring | lead-architect | backend-architect | System redesign |
| Database Refactoring | data-layer-expert | backend-architect | Schema changes |
| UI Refactoring | ui-engineer-enhanced | ui-designer | Component updates |
| API Refactoring | backend-architect | python-backend-engineer | Endpoint redesign |

**Example**:
```markdown
- [ ] REFACTOR-001: Code Refactoring (3 pts)
      Assigned Subagent(s): refactoring-expert
```

---

## Debugging Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Complex Debugging | ultrathink-debugger | - | Deep analysis |
| Backend Debugging | python-backend-engineer | data-layer-expert | API/DB issues |
| Frontend Debugging | frontend-developer | ui-engineer-enhanced | React/UI issues |
| Performance Debugging | backend-architect | react-performance-optimizer | Performance issues |
| Integration Debugging | backend-architect | - | Multi-system issues |

**Example**:
```markdown
- [ ] DEBUG-001: Complex Debugging (5 pts)
      Assigned Subagent(s): ultrathink-debugger
```

---

## Planning & Analysis Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| PRD Writing | prd-writer | lead-pm | Requirements docs |
| Implementation Planning | implementation-planner | lead-architect | Task breakdown |
| Task Decomposition | task-decomposition-expert | - | Story splitting |
| Feature Planning | feature-planner | lead-pm | Feature analysis |
| Research Spikes | spike-writer | - | Investigation docs |
| Architecture Planning | lead-architect | backend-architect | System design |

**Example**:
```markdown
- [ ] PLAN-001: Implementation Planning (3 pts)
      Assigned Subagent(s): implementation-planner, lead-architect
```

---

## Review & Validation Tasks

| Task Type | Primary Subagent(s) | Secondary Subagent(s) | Notes |
|-----------|-------------------|---------------------|-------|
| Code Review | code-reviewer | senior-code-reviewer | Peer review |
| Architecture Review | lead-architect | backend-architect | Design review |
| Task Validation | task-completion-validator | - | Completion check |
| API Review | api-librarian | - | API standards |
| Telemetry Review | telemetry-auditor | - | Observability check |
| Strict QA | karen | - | Enforcement |

**Example**:
```markdown
- [ ] REVIEW-001: Code Review (1 pt)
      Assigned Subagent(s): code-reviewer
```

---

## Default Assignments by Phase

### Phase 1: Database
- Primary: data-layer-expert
- Secondary: backend-architect

### Phase 2: Repository
- Primary: python-backend-engineer
- Secondary: data-layer-expert

### Phase 3: Service
- Primary: backend-architect
- Secondary: python-backend-engineer

### Phase 4: API
- Primary: python-backend-engineer
- Secondary: backend-architect

### Phase 5: UI
- Primary: ui-engineer-enhanced, frontend-developer
- Secondary: ui-designer

### Phase 6: Testing
- Primary: testing specialist
- Secondary: Varies by test type

### Phase 7: Documentation
- Primary: documentation-writer
- Secondary: Varies by doc type

### Phase 8: Deployment
- Primary: DevOps
- Secondary: lead-pm

---

## Assignment Format

**In Implementation Plans**:
```markdown
| Task ID | Task Name | ... | Assignee | ... |
|---------|-----------|-----|----------|-----|
| API-001 | Router Setup | ... | python-backend-engineer | ... |
```

**In Progress Tracking**:
```markdown
- [ ] API-001: Router Setup (2 pts)
      Assigned Subagent(s): python-backend-engineer, backend-architect
```

**In Phase Breakdowns**:
```markdown
**Assigned Subagent(s)**: python-backend-engineer, backend-architect
```

---

## Available Subagents

May not be all-inclusive; refer to subagent registry in context for full list.

### Architecture
- lead-architect
- backend-architect
- nextjs-architecture-expert
- data-layer-expert

### Development
- python-backend-engineer
- frontend-developer
- ui-engineer-enhanced
- mobile-app-builder

### UI/UX
- ui-designer
- ux-researcher

### Review
- code-reviewer
- senior-code-reviewer
- task-completion-validator
- api-librarian
- telemetry-auditor
- karen

### Documentation
- documentation-writer
- documentation-complex
- documentation-planner
- api-documenter
- technical-writer
- openapi-expert
- changelog-generator

### Testing & Quality
- testing specialist
- web-accessibility-checker
- react-performance-optimizer

### Debugging
- ultrathink-debugger
- refactoring-expert

### Planning
- lead-pm
- prd-writer
- implementation-planner
- feature-planner
- spike-writer
- task-decomposition-expert

### DevOps
- DevOps (not a subagent, but role reference)

```

### references/optimization-patterns.md

```markdown
# Optimization Patterns for AI Artifacts

## Core Principle

Files are AI artifacts - optimized for AI agent consumption, not human reading. Goal: Maximum token efficiency through progressive disclosure.

**Target**: ~800 lines max per file
**Why**: Optimal context window for AI agents, enables progressive loading

---

## Pattern 1: Break by Phase (Most Common)

### When to Use
- Implementation plans with 8+ phases
- Total plan >800 lines
- Phases are logically independent

### Strategy

**Group Related Phases**:
- Backend phases: 1-3 (Database, Repository, Service)
- API phase: 4 (API Layer)
- Frontend phase: 5 (UI Layer)
- Validation phases: 6-8 (Testing, Documentation, Deployment)

### Example

**Before Optimization**: `sidebar-polish-v1.md` (1200 lines)
```
Phase 1: Database (150 lines)
Phase 2: Repository (150 lines)
Phase 3: Service (150 lines)
Phase 4: API (150 lines)
Phase 5: UI (200 lines)
Phase 6: Testing (150 lines)
Phase 7: Documentation (100 lines)
Phase 8: Deployment (150 lines)
```

**After Optimization**:
```
sidebar-polish-v1.md (200 lines - summary + links)
├── phase-1-3-backend.md (450 lines)
│   ├── Phase 1: Database (150 lines)
│   ├── Phase 2: Repository (150 lines)
│   └── Phase 3: Service (150 lines)
├── phase-4-5-frontend.md (350 lines)
│   ├── Phase 4: API (150 lines)
│   └── Phase 5: UI (200 lines)
└── phase-6-8-validation.md (400 lines)
    ├── Phase 6: Testing (150 lines)
    ├── Phase 7: Documentation (100 lines)
    └── Phase 8: Deployment (150 lines)
```

### Token Efficiency
- **Before**: Load 1200 lines for any query
- **After**: Load 200-line summary + specific phase (450 max) = 650 lines (46% reduction)
- **For overview**: Load 200 lines only (83% reduction)

---

## Pattern 2: Break by Domain

### When to Use
- Large feature spanning multiple domains
- Natural separation between backend and frontend
- Complex integration scenarios

### Strategy

**Domain Grouping**:
- Backend domain: Database → Repository → Service → API
- Frontend domain: UI components → State → Integration
- Validation domain: Testing → Documentation → Deployment

### Example

**Before Optimization**: `realtime-collaboration-v1.md` (1400 lines)
```
Phase 1: Database (200 lines)
Phase 2: Repository (200 lines)
Phase 3: Service (250 lines)
Phase 4: WebSocket API (250 lines)
Phase 5: Collaborative Editor (300 lines)
Phase 6: Testing (200 lines)
```

**After Optimization**:
```
realtime-collaboration-v1.md (250 lines - summary)
├── backend-implementation.md (700 lines)
│   ├── Phase 1: Database (200 lines)
│   ├── Phase 2: Repository (200 lines)
│   ├── Phase 3: Service (250 lines)
│   └── Integration notes (50 lines)
├── frontend-implementation.md (550 lines)
│   ├── Phase 4: WebSocket API (250 lines)
│   ├── Phase 5: Collaborative Editor (300 lines)
│   └── Real-time UI patterns
└── validation-deployment.md (200 lines)
    └── Phase 6: Testing + Deployment
```

### Token Efficiency
- **Before**: Load 1400 lines for any query
- **After**: Load 250 + specific domain (700 max) = 950 lines (32% reduction)
- **For targeted work**: Load only relevant domain (50%+ reduction)

---

## Pattern 3: Break by Task Type

### When to Use
- Implementation and testing/docs are distinct efforts
- Can parallelize implementation and validation work
- Clear separation of concerns

### Strategy

**Type Grouping**:
- Implementation tasks: Phases 1-5
- Validation tasks: Phases 6-8

### Example

**Before Optimization**: `advanced-filtering-v1.md` (1100 lines)
```
Phase 1-5: Implementation (800 lines)
Phase 6-8: Validation (300 lines)
```

**After Optimization**:
```
advanced-filtering-v1.md (200 lines - summary)
├── implementation-tasks.md (800 lines)
│   ├── Phase 1: Database
│   ├── Phase 2: Repository
│   ├── Phase 3: Service
│   ├── Phase 4: API
│   └── Phase 5: UI
└── validation-tasks.md (300 lines)
    ├── Phase 6: Testing
    ├── Phase 7: Documentation
    └── Phase 8: Deployment
```

### Token Efficiency
- **Before**: Load 1100 lines for any query
- **After**: Load 200 + specific type (800 max) = 1000 lines (9% reduction)
- **For validation queries**: Load 200 + 300 = 500 lines (55% reduction)

---

## Pattern 4: Keep Together (Important)

### Always in Parent Plan

**Executive Content** (keep in main plan):
- Executive Summary (50-100 lines)
- Implementation Strategy (50-100 lines)
- Phase Overview Table (20-50 lines)
- Risk Mitigation Summary (50-100 lines)
- Success Metrics Overview (50 lines)
- Resource Requirements (50 lines)

**Total Parent Size**: 200-300 lines

### Always in Phase Files

**Detailed Content** (move to phase files):
- Complete task breakdown tables
- Detailed acceptance criteria
- Technical implementation notes
- Specific integration points
- Per-task subagent assignments
- Quality gates per phase
- Key files with line ranges

---

## Pattern 5: Single Phase Breakout

### When to Use
- One phase is exceptionally large (>400 lines)
- Rest of plan is reasonable size
- Phase has complex sub-tasks

### Strategy

Break only the large phase into its own file, keep rest in parent.

### Example

**Before**: `authentication-refactor-v1.md` (900 lines)
```
Phase 1: Database (100 lines)
Phase 2: Repository (100 lines)
Phase 3: Auth Service (500 lines) ← Large!
Phase 4: API (100 lines)
Phase 5: UI (100 lines)
```

**After**:
```
authentication-refactor-v1.md (400 lines - includes all but Phase 3)
└── phase-3-auth-service.md (500 lines - detailed auth implementation)
```

### Token Efficiency
- **Before**: Load 900 lines for any query
- **After - Phase 3 query**: Load 400 + 500 = 900 lines (no change for this phase)
- **After - Other phases**: Load 400 lines only (56% reduction)

---

## Progressive Disclosure Strategy

### 3-Level Loading

**Level 1: Overview** (200-300 lines)
- Load: Parent plan only
- Contains: Executive summary, phase table, high-level strategy
- **Use Case**: "What is this feature? What phases are there?"

**Level 2: Phase Summary** (400-500 lines)
- Load: Parent + specific phase file
- Contains: Detailed tasks, acceptance criteria, subagent assignments
- **Use Case**: "Implement Phase 3 tasks"

**Level 3: Full Context** (600-800 lines)
- Load: Parent + phase file + related context
- Contains: All details + integration notes + gotchas
- **Use Case**: "Complex implementation with cross-phase dependencies"

### Example Loading

**Query**: "Show me the UI implementation tasks"

**Level 1 Response** (200 lines):
```
Load: Parent plan
See: Phase 5 overview in phase table
Indicate: Details in phase-4-5-frontend.md
```

**Level 2 Response** (200 + 400 = 600 lines):
```
Load: Parent plan + phase-4-5-frontend.md
Show: Complete Phase 5 task breakdown
Ready: For implementation
```

**Level 3 Response** (200 + 400 + 200 = 800 lines):
```
Load: Parent + phase file + context
Show: Tasks + integration points + gotchas
Ready: For complex implementation
```

---

## Token Efficiency Formulas

### Traditional Approach

```
Token Usage = Full File Lines × Token Multiplier
Example: 1200 lines × 2.5 tokens/line = 3000 tokens
```

### Optimized Approach

```
Overview Query:
  Token Usage = Parent Lines × Token Multiplier
  Example: 200 lines × 2.5 = 500 tokens
  Savings: 83%

Targeted Query:
  Token Usage = (Parent + Phase) × Token Multiplier
  Example: (200 + 400) × 2.5 = 1500 tokens
  Savings: 50%

Deep Dive:
  Token Usage = (Parent + Phase + Context) × Token Multiplier
  Example: (200 + 400 + 200) × 2.5 = 2000 tokens
  Savings: 33%
```

### Average Savings

Across typical queries with phase breakout:
- **50-70% token reduction** for most queries
- **Enables working with larger features** without context overflow
- **Faster AI response times** due to smaller context

---

## Implementation Checklist

### When Optimizing a Plan

- [ ] **Analyze Size**: Count total lines
- [ ] **Identify Breakpoints**: Find natural boundaries (phases, domains, types)
- [ ] **Choose Pattern**: Select appropriate pattern (phase, domain, type)
- [ ] **Create Structure**: Set up directories and files
- [ ] **Split Content**: Move content to phase files
- [ ] **Update Parent**: Add summary and links
- [ ] **Cross-Link**: Link phase files back to parent
- [ ] **Validate**: Ensure all content preserved
- [ ] **Test Loading**: Verify token efficiency with test queries

### Quality Gates for Optimization

- [ ] Each file <800 lines
- [ ] Parent plan 200-300 lines (summary + links)
- [ ] All phase files linked from parent
- [ ] All content preserved (nothing lost)
- [ ] Logical grouping maintained
- [ ] Cross-links work correctly
- [ ] Token efficiency >50% for targeted queries
- [ ] Progressive disclosure achievable

---

## Anti-Patterns to Avoid

### ❌ Over-Optimization

**Problem**: Breaking files too small (<200 lines per file)
**Result**: Too many files, overhead of loading multiple files
**Fix**: Group related content, aim for 300-500 lines per phase file

### ❌ Arbitrary Splits

**Problem**: Breaking mid-phase or mid-task
**Result**: Loss of cohesion, harder to understand
**Fix**: Split only on logical boundaries (phase, domain, task type)

### ❌ No Summary in Parent

**Problem**: Parent plan just has links, no overview
**Result**: Must load phase files to understand feature
**Fix**: Keep executive summary, phase table, strategy in parent

### ❌ Duplicate Content

**Problem**: Repeating content in parent and phase files
**Result**: Inconsistency, wasted tokens
**Fix**: Summary in parent, details in phase files only

### ❌ Missing Cross-Links

**Problem**: Phase files don't link back to parent
**Result**: Lost context, hard to navigate
**Fix**: Always link phase files back to parent plan

### ❌ Inconsistent Structure

**Problem**: Each phase file has different format
**Result**: Harder for AI to parse and understand
**Fix**: Use templates for all phase files

---

## Real-World Examples

### Example 1: Data Layer Fixes (No Breakout Needed)

**File**: `data-layer-fixes-filtering-v1.md` (650 lines)

**Analysis**:
- 5 phases, ~130 lines each
- Total 650 lines (under 800 threshold)
- **Decision**: No breakout needed

**Optimization**: None required, file is already optimal size

---

### Example 2: Prompt Modal Improvements (Breakout Required)

**File**: `prompt-modal-improvements-v1.md` (1200 lines)

**Analysis**:
- 8 phases, ~150 lines each
- Total 1200 lines (exceeds 800 threshold)
- Natural grouping: Backend (1-3), Frontend (4-5), Validation (6-8)

**Optimization Pattern**: Break by Phase (Pattern 1)

**Result**:
```
prompt-modal-improvements-v1.md (200 lines)
├── phase-1-3-backend.md (450 lines)
├── phase-4-5-frontend.md (400 lines)
└── phase-6-8-validation.md (350 lines)
```

**Token Savings**: 50-70% for targeted queries

---

### Example 3: Realtime Collaboration (Domain Breakout)

**File**: `realtime-collaboration-v1.md` (1500 lines)

**Analysis**:
- Complex feature spanning backend and frontend
- Natural domain separation
- Different teams working on different domains

**Optimization Pattern**: Break by Domain (Pattern 2)

**Result**:
```
realtime-collaboration-v1.md (250 lines)
├── backend-implementation.md (700 lines)
├── frontend-implementation.md (550 lines)
```

**Token Savings**: 60%+ for domain-specific queries

---

## Automation Opportunities

### Script Support

Create `optimize-plan.sh` script to:
1. Count lines in plan
2. Identify phases
3. Suggest breakout strategy
4. Create phase files
5. Update parent with links
6. Validate optimization

### AI Agent Support

AI agents can:
- Analyze plan size automatically
- Suggest optimal breakout pattern
- Generate phase files with correct structure
- Update parent plan with links
- Validate token efficiency

---

## Measuring Success

### Metrics

**Before Optimization**:
- Average query context: 1200 lines
- Token usage: ~3000 tokens
- AI response time: Slower due to large context

**After Optimization**:
- Average query context: 600 lines (50% reduction)
- Token usage: ~1500 tokens (50% reduction)
- AI response time: Faster due to smaller context

### Validation

Query the optimized plan with typical questions:
- "What tasks are in Phase 3?"
  - Should load: Parent (200) + Phase file (400) = 600 lines ✓
- "Give me an overview of this feature"
  - Should load: Parent only (200 lines) ✓
- "Show me backend implementation details"
  - Should load: Parent (200) + Backend phases (450) = 650 lines ✓

If queries consistently load <800 lines, optimization successful ✓

---

**Key Takeaway**: Optimize for progressive disclosure. AI agents load only what they need, when they need it. This enables working with larger features while maintaining token efficiency.

```

### references/best-practices.md

```markdown
# Planning Skill 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
- Format: `[feature-name]-v1.md`
- Use kebab-case (lowercase with hyphens)
- Include version number (-v1, -v2)
- Example: `advanced-filtering-v1.md`

### Implementation Plans
- Format: `[feature-name]-v1.md`
- Match PRD naming
- Same category as PRD
- Version synchronized with PRD

### Phase Files
- Format: `phase-[N]-[name].md`
- Sequential numbering (phase-1, phase-2)
- Can group: `phase-1-3-backend.md`
- Descriptive name (database, repository, frontend)

---

## Directory Organization

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

### Implementation Plans
- Location: `docs/project_plans/implementation_plans/[category]/`
- Match PRD category
- Phase breakouts in subdirectory: `[plan-name]/`

---

## 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
```yaml
---
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
---
```

### Implementation Plans
```yaml
---
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
---
```

---

## Architecture Compliance

All plans follow MP layered architecture:
- **Routers** - HTTP + validation, return DTOs
- **Services** - Business logic, return DTOs only
- **Repositories** - All DB I/O, RLS enforcement, cursor pagination
- **ErrorResponse** - Envelope for all failures
- **Cursor Pagination** - `{ items, pageInfo }` format

---

## Documentation Policy

Follows CLAUDE.md documentation policy:
- PRDs are product-planning docs (allowed)
- Implementation Plans are product-planning docs (allowed)
- NO reports, summaries, etc unless explicitly requested
- One progress file per phase

---

## Anti-Patterns to Avoid

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Generic phase names | `phase-1.md` unclear | Use `phase-1-database.md` |
| Mismatched names | PRD/plan names differ | Keep names synchronized |
| Missing cross-links | Lost navigation | Always link related docs |
| Files >800 lines | Token inefficiency | Break into phase files |
| Deep nesting | Hard to navigate | Keep structure flat |
| Version mismatch | Confusion | Sync PRD/plan versions |

[Return to Planning Skill](../SKILL.md)

```

### references/workflow-examples.md

```markdown
# Planning Skill 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`

```markdown
# 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)

```markdown
# 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
4. Update parent plan: Keep summary, add links (200 lines)

### Output

**Updated**: `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: Full Feature Planning Flow

### Input
```
User: "Plan the complete user analytics dashboard feature"
```

### Full Flow

**Step 1: Create PRD**
```
Output: docs/project_plans/PRDs/features/analytics-dashboard-v1.md
```

**Step 2: Create Implementation Plan**
```
Output: docs/project_plans/implementation_plans/features/analytics-dashboard-v1.md
Phase files (if needed):
- analytics-dashboard-v1/phase-1-3-backend.md
- analytics-dashboard-v1/phase-4-5-frontend.md
- analytics-dashboard-v1/phase-6-8-validation.md
```

**Step 3: Create Progress Tracking (via artifact-tracking)**
```
Output: .claude/progress/analytics-dashboard/all-phases-progress.md
```

**Result**: Complete planning documentation with progressive disclosure

[Return to Planning Skill](../SKILL.md)

```