planning-phase

<objective>
Generate implementation plan with code reuse analysis from spec.md, ensuring alignment with project documentation and maximizing component reuse during the /plan workflow phase.

This skill orchestrates the /plan phase, which runs after /spec (or /clarify) and before /tasks in the feature workflow.

**Core responsibilities**:

- Load all 8 project documentation files from docs/project/ for constraint extraction
- Search codebase for similar features and reusable components (expect 5-15 opportunities)
- Design architecture with components, layers, and design patterns
- Plan data model with entities, relationships, and migrations
- Define API contracts in OpenAPI format (if applicable)
- Plan testing strategy (unit, integration, E2E)
- Estimate complexity (20-30 tasks predicted)

Inputs: spec.md (feature specification), docs/project/\*.md (8 files), existing codebase
Outputs: plan.md (implementation plan), research.md (reuse findings and project context)
Expected duration: 1-3 hours
</objective>

<quick_start>
Execute planning workflow systematically:

1. **Load Project Documentation** - Read all 8 docs/project/\*.md files for constraints (tech stack, architecture, data model, API patterns)
2. **Research Code Reuse** - Search codebase before designing (expect 5-15 reuse opportunities)
3. **Design Architecture** - Components, layers, design patterns (MVC, Repository, etc.)
4. **Plan Data Model** - Entities, relationships, ERD diagram, migrations
5. **Define API Contracts** - Endpoints, schemas, validation (OpenAPI format if applicable)
6. **Plan Testing Strategy** - Unit, integration, E2E coverage with specific test types
7. **Estimate Complexity** - Predict 20-30 tasks based on feature scope

Key principle: Research before designing. Maximize code reuse. Align with project documentation.

See resources/ directory for detailed workflows on each step.
</quick_start>

<prerequisites>
Before beginning planning phase:
- Specification phase completed (spec.md exists in specs/NNN-slug/)
- Feature requirements understood (success criteria, user stories, edge cases)
- Project documentation available (docs/project/*.md) OR brownfield codebase exists
- Git working tree clean (no uncommitted changes)

If specification incomplete, return to /spec or /clarify phase.
</prerequisites>

<workflow>
<step number="1">
**Load Project Documentation**

Read all 8 project documentation files for constraint extraction.

**Files to load** (from docs/project/):

- overview.md - Vision, users, scope, success metrics
- system-architecture.md - C4 diagrams, components, data flows
- tech-stack.md - Database, frontend, backend, deployment platform
- data-architecture.md - ERD, entity schemas, storage strategy
- api-strategy.md - REST/GraphQL patterns, auth, versioning
- capacity-planning.md - Scaling tier, cost model
- deployment-strategy.md - CI/CD pipeline, environments
- development-workflow.md - Git flow, PR process, testing strategy

**Extraction process**:

```bash
# Read all 8 project docs
for doc in docs/project/*.md; do
  echo "Reading: $doc"
  cat "$doc"
done

# Extract key constraints
TECH_STACK=$(grep -A 20 "Technology Stack" docs/project/tech-stack.md)
DATABASE=$(grep -A 5 "Database" docs/project/tech-stack.md)
ARCHITECTURE=$(grep -A 10 "Architecture Style" docs/project/system-architecture.md)
API_STYLE=$(grep -A 5 "API Style" docs/project/api-strategy.md)
```

**Brownfield fallback** (if docs/project/ missing):

- Scan package.json, requirements.txt for tech stack
- Analyze existing database migrations for data model
- Review existing API routes for patterns
- Infer architecture from directory structure

**Output**: Document constraints in research.md under "Project Context" section

See resources/project-docs-integration.md for complete extraction workflow.
</step>

<step number="2">
**Research Code Reuse**

Search codebase for similar features and reusable components before designing.

**Search strategy**:

```bash
# Search for similar features (by name similarity)
grep -r "authentication" src/
grep -r "user profile" src/
grep -r "dashboard" src/

# Search for reusable components (by function)
grep -r "class.*Service" src/  # Service layer
grep -r "export.*Repository" src/  # Repository pattern
grep -r "function validate" src/  # Validation utilities
grep -r "export.*schema" src/  # Data schemas
```

**Expected findings**: 5-15 reuse opportunities per feature

**Reuse categories**:

- **Services**: Authentication, validation, data transformation
- **Components**: Forms, tables, modals, buttons (UI)
- **Utilities**: Date formatting, error handling, logging
- **Schemas**: Database models, API contracts, validation rules
- **Patterns**: Repository pattern, middleware, hooks

**Documentation**:

```markdown
## Reuse Opportunities (research.md)

### Services (3 found)

- src/services/AuthService.ts - Reuse for user authentication flow
- src/services/ValidationService.ts - Reuse for form validation
- src/services/EmailService.ts - Reuse for notification emails

### Components (7 found)

- src/components/UserForm.tsx - Adapt for profile editing
- src/components/DataTable.tsx - Reuse for user list display
  ...
```

**Anti-pattern**: Designing from scratch without searching for reuse (wastes time, creates duplication)

See resources/code-reuse-analysis.md for search patterns and anti-duplication strategies.
</step>

<step number="3">
**Design Architecture**

Design component structure, layers, and design patterns.

**Layers** (typical web application):

- **Presentation Layer**: UI components, pages, forms
- **Business Logic Layer**: Services, domain logic, validation
- **Data Access Layer**: Repositories, database queries, ORM models
- **Integration Layer**: External APIs, third-party services

**Component design**:

```markdown
## Architecture (plan.md)

### Components

**Frontend** (Next.js):

- pages/users/profile.tsx - User profile page
- components/ProfileForm.tsx - Editable profile form
- hook