feature-planner

name

feature-planner

description

Automate analysis and planning for new feature implementations on a codebase. Use when asked to plan a new feature, design a feature implementation, or analyze how to add functionality to an existing project. This skill reads debate.md to track discussions, then analyzes the codebase via its codewiki folder to create comprehensive, context-aware feature implementation plans with step-by-step guides that respect existing architecture patterns.

Feature Planner

Overview

Automates the complete workflow for planning new feature implementations on existing codebases. The skill follows a systematic approach:

1. Read debate.md - Track feature discussions, requirements evolution, and technical decisions
2. Analyze codewiki - Understand codebase architecture, patterns, and constraints
3. Design implementation - Create context-aware plans that respect existing patterns
4. Generate step-by-step guide - Provide detailed implementation roadmap

This ensures feature plans are grounded in both the discussion history and actual codebase reality.

Workflow

Phase 1: Read Debate History

Before planning any feature, understand the discussion context and requirements:

Read debate.md:

Read the debate.md file in the project root

This file tracks:

• Feature discussions and requirements evolution
• Technical decisions and rationale
• User needs and problem statements
• Architecture considerations
• Previous Q&A that led to current requirements

Extract from debate.md:

• Current feature request or problem being solved
• Key requirements and constraints
• Technical context and decisions made
• References to similar systems or patterns
• Gap analysis if already discussed

Document findings in .feature-plans/<feature-name>/debate-context.md:

# Debate Context: <feature-name>

## Origin Discussion
[Summary from debate.md]

## Requirements Evolution
- [Requirement 1 from discussion]
- [Requirement 2 from discussion]

## Key Decisions Made
- [Decision 1]
- [Decision 2]

## References
- [Referenced systems/patterns]
- [Gap analysis findings]

Phase 2: Ensure Project Documentation Exists

Verify the codebase has proper documentation (codewiki):

Check for codewiki:

ls -la codewiki/

If codewiki/ does NOT exist:

• Inform the user that proper codebase understanding requires documentation
• Ask if they want to generate a codewiki first (recommended)
• If yes, invoke the codewiki-generator skill before proceeding
• If no, proceed with limited context from README and manual exploration

If codewiki/ exists:

• Proceed to Phase 3

Phase 3: Understand Additional Requirements

If debate.md doesn't cover everything, gather additional requirements:

Ask the user (if needed):

1. Are there additional constraints not mentioned in debate.md?
2. What is the expected user experience or interface?
3. Are there specific technical preferences?
4. Any deadlines or priority considerations?

Update requirements in .feature-plans/<feature-name>/requirements.md:

# Feature: <name>

## From Debate.md
[Summary from debate context]

## Additional Requirements
- [Additional requirement 1]
- [Additional requirement 2]

## Constraints
- [Constraint 1]
- [Constraint 2]

## User Experience
[Expected UX]

Phase 4: Analyze Codebase Context

Phase 4: Analyze Codebase Context

CRITICAL: Use the codewiki folder to understand the codebase.

Read and understand relevant parts of the codebase using the codewiki documentation.

Steps:

1. Read Overview

   • codewiki/overview.md - understand system purpose, tech stack, architecture highlights
   • codewiki/README.md or codewiki/index.md if present

2. Read Architecture

   • codewiki/architecture/overview.md - understand system design patterns
   • codewiki/core-components/overview.md - identify key components
   • Look for architecture diagrams (Mermaid)

3. Identify Integration Points

   • Where will the feature integrate? (API, UI, database, etc.)
   • What existing modules/services will be affected?
   • Read relevant component documentation from codewiki

4. Review Existing Patterns

   • How are similar features implemented?
   • What are the coding conventions?
   • Read codewiki/development/overview.md for standards
   • Check API reference: codewiki/api-reference/overview.md

5. Check Data Requirements

   • Does the feature need new data models?
   • Read codewiki/data/domain-model.md
   • Read codewiki/data/storage-layout.md

6. Security and Performance Considerations

   • Read codewiki/security/ if authentication/authorization is involved
   • Read codewiki/performance/ if performance-critical

7. Review Similar Features

   • Search codewiki for similar implementations
   • Check codewiki/plugins/ or codewiki/integrations/ if relevant

8. Check Meta Information

   • Read codewiki/.meta/doc_plan.json to understand codebase structure
   • Review codewiki/.meta/evidence.json for code evidence
   • Check codewiki/quality-report.md for known issues

Document findings in .feature-plans/<feature-name>/context-analysis.md:

# Context Analysis: <feature-name>

## From Codewiki Overview
- System: [name from overview.md]
- Tech Stack: [from overview.md]
- Key Highlights: [architectural highlights from overview.md]
- Known Risks: [from overview.md]

## Architecture Context
- Design Pattern: [from architecture/overview.md]
- Component Structure: [from core-components/overview.md]
- Data Flow: [diagrams or descriptions]

## Integration Points
- Component: [name] - [integration method from codewiki]
- API endpoints: [affected endpoints from api-reference]
- Database: [affected tables/collections from data/storage-layout.md]
- Services: [affected services from architecture docs]

## Existing Patterns (from codewiki)
- Pattern 1: [description + file reference from development/overview.md]
- Pattern 2: [description + file reference from similar components]
- Coding Standards: [from development/overview.md]

## Data Model Impact (from codewiki)
- Current Model: [from data/domain-model.md]
- New entities: [list]
- Modified entities: [list]
- Relationships: [description]
- Storage: [from data/storage-layout.md]

## Dependencies
- Internal: [list of modules from codewiki]
- External: [list of packages/services from overview.md tech stack]

## Architectural Considerations
- [Consideration 1 from architecture docs]
- [Consideration 2 from performance/bottlenecks.md if relevant]

## Technical Constraints (from codewiki)
- [Constraint 1 from overview.md or quality-report.md]
- [Constraint 2 from security/threat-model.md if relevant]

## Similar Features in Codebase
- [Feature 1] - Implementation at [location from codewiki]
- [Feature 2] - Pattern described in [codewiki page]

Phase 5: Design the Implementation

Phase 5: Design the Implementation

Create a detailed implementation design based on:

• Debate.md context and requirements
• Codewiki architecture and patterns
• Additional user requirements

Run the planner script (optional):

python3 <skill-root>/scripts/feature_planner.py \
  --repo-root <repo-root> \
  --feature-name <feature-name> \
  --requirements .feature-plans/<feature-name>/requirements.md \
  --context .feature-plans/<feature-name>/context-analysis.md \
  --output .feature-plans/<feature-name>/

OR manually create the design document:

Document the design in .feature-plans/<feature-name>/design.md:

# Implementation Design: <feature-name>

## Architecture Decision

### Chosen Approach
[Description of the chosen implementation approach]

### Alternatives Considered
1. [Alternative 1] - Rejected because: [reason]
2. [Alternative 2] - Rejected because: [reason]

### Rationale
[Why this approach is best given the context]

## Component Design

### Frontend Changes (if applicable)
- New components: [list]
- Modified components: [list]
- File structure:

src/components/ / ComponentA.tsx ComponentB.tsx

### Backend Changes (if applicable)
- New services/modules: [list]
- Modified services: [list]
- File structure:

src/services/ / service.py

### API Changes
- New endpoints:
- `POST /api/<resource>` - [description]
- `GET /api/<resource>/:id` - [description]
- Modified endpoints: [list]

### Data Model Changes
- New tables/collections:

: - field1: type (description) - field2: type (description)

- Schema migrations: [description]

### External Dependencies
- New packages to install:
- `package-name@version` - [purpose]

## Technical Specifications

### State Management (frontend)
[How state will be managed]

### Authentication/Authorization
[Security model for the feature]

### Validation
- Frontend validation: [rules]
- Backend validation: [rules]

### Error Handling
[Error handling strategy]

### Testing Strategy
- Unit tests: [scope]
- Integration tests: [scope]
- E2E tests: [scope]

## Diagrams

### Component Interaction
```mermaid
sequenceDiagram
  participant User
  participant Frontend
  participant API
  participant Service
  participant Database

  User->>Frontend: [action]
  Frontend->>API: [request]
  API->>Service: [call]
  Service->>Database: [query]
  Database-->>Service: [result]
  Service-->>API: [response]
  API-->>Frontend: [data]
  Frontend-->>User: [display]

Data Flow

graph LR
    Input[User Input] --> Validation
    Validation --> Processing
    Processing --> Storage[Database]
    Storage --> Response
    Response --> Display[UI Update]

Risk Assessment

Potential Issues

1. [Risk 1] - Mitigation: [strategy]
2. [Risk 2] - Mitigation: [strategy]

Breaking Changes

• [Change 1] - Impact: [description]

Performance Impact

[Expected performance characteristics]

Success Criteria

• [Criterion 1]
• [Criterion 2]
• [Criterion 3]

### Phase 6: Create Implementation Plan

Generate a step-by-step implementation guide.

Document in `.feature-plans/<feature-name>/implementation-plan.md`:

```markdown
# Implementation Plan: <feature-name>

## Pre-Implementation Checklist

- [ ] Review and approve design document
- [ ] Create feature branch: `feature/<feature-name>`
- [ ] Install any new dependencies
- [ ] Set up development environment (if needed)

## Implementation Steps

### Step 1: Database/Model Changes

**Why first:** Schema changes should be in place before code that uses them

**Tasks:**
1. [ ] Create migration file: `migrations/<timestamp>_add_<feature>.sql`
   - File: `<path>`
   - Add tables/columns: [list]

2. [ ] Define data models
   - File: `<path>/models.py` or `<path>/types.ts`
   - Models: [list]

3. [ ] Run migration
   ```bash
   <migration-command>

4. Verify schema changes

   <verify-command>
   

Files to create/modify:

• <file-path-1> - [description]
• <file-path-2> - [description]

Estimated complexity: [Low/Medium/High]

---

Step 2: Backend Service/API Layer

Why next: Core logic before UI

Tasks:

1. Create service module

   • File: <path>/service.py
   • Methods: [list]

2. Implement business logic

   • Validation rules
   • Data processing
   • Error handling

3. Create API endpoints

   • File: <path>/routes.py or <path>/api.ts
   • Endpoints: [list]

4. Write unit tests

   • File: <path>/test_service.py
   • Coverage: [methods]

Code patterns to follow:

# Example following project conventions
class <FeatureName>Service:
    def __init__(self, db):
        self.db = db

    async def create(self, data):
        # Implementation
        pass

Files to create/modify:

• <file-path-1> - [description]
• <file-path-2> - [description]

Estimated complexity: [Low/Medium/High]

---

Step 3: Frontend Components (if applicable)

Tasks:

1. Create UI components

   • File: <path>/Component.tsx
   • Props: [list]

2. Implement state management

   • Hook/store: <path>
   • State shape: [description]

3. Add form validation

   • Library: [validation library]
   • Rules: [list]

4. Style components

   • Follow design system: [reference]

5. Write component tests

   • File: <path>/Component.test.tsx

Code patterns to follow:

// Example following project conventions
export function <ComponentName>() {
  const [state, setState] = useState()

  return (
    // JSX
  )
}

Files to create/modify:

• <file-path-1> - [description]
• <file-path-2> - [description]

Estimated complexity: [Low/Medium/High]

---

Step 4: Integration

Tasks:

1. Wire up frontend to API

   • API client: <path>
   • Endpoints used: [list]

2. Add navigation/routing

   • Route: <route-path>
   • File: <router-file>

3. Update menu/navigation UI

   • File: <nav-component>

4. Write integration tests

   • File: <test-file>
   • Scenarios: [list]

Files to create/modify:

• <file-path-1> - [description]
• <file-path-2> - [description]

Estimated complexity: [Low/Medium/High]

---

Step 5: Testing & Documentation

Tasks:

1. Run all tests

   <test-command>
   

2. Manual testing

   • Happy path: [scenario]
   • Error cases: [scenarios]
   • Edge cases: [scenarios]

3. Update documentation

   • Update README.md if needed
   • Update API docs: <api-doc-file>
   • Add inline code comments for complex logic

4. Update codewiki (if exists)

   • Add feature to relevant pages
   • Update architecture diagrams if structure changed

Files to create/modify:

• <file-path-1> - [description]
• <file-path-2> - [description]

Estimated complexity: [Low/Medium/High]

---

Step 6: Code Review & Deployment Prep

Tasks:

1. Self-review checklist

   • Code follows project conventions
   • No console.log/debug statements
   • Error handling in place
   • Tests passing
   • No sensitive data exposed

2. Create pull request

   • Title: "feat: "
   • Description: Link to design doc and requirements
   • Reviewers: [suggest reviewers]

3. Address review feedback

4. Merge to main branch

Estimated complexity: [Low/Medium/High]

---

Post-Implementation

Verification

• Test in staging environment
• Performance testing (if needed)
• Security review (if handling sensitive data)

Monitoring

• Set up logging for new endpoints
• Add metrics/monitoring (if applicable)
• Document runbook for operational issues

Rollout

• Deploy to production
• Monitor for errors
• Announce to team/users

Rollback Plan

If issues arise:

1. [Rollback step 1]
2. [Rollback step 2]

Notes

• [Any additional notes, gotchas, or considerations]

### Phase 7: Present Plan to User

**Summary output:**

Feature Plan Created:

📁 Location: .feature-plans//

📄 Documents:

• requirements.md - Feature requirements and constraints
• context-analysis.md - Codebase context and integration points
• design.md - Architectural design and technical specifications
• implementation-plan.md - Step-by-step implementation guide

📊 Complexity: [Overall estimate based on steps]

🔧 Technologies Involved:

• [Tech 1]
• [Tech 2]

📝 Next Steps:

1. Review the design document
2. Approve or suggest modifications
3. Begin implementation following the plan

Type "start implementation" when ready to begin, or ask questions about any part of the plan.

## Quality Bar

**Plans must include:**
- Context-aware design (respects existing architecture)
- Concrete file paths and code examples
- Risk assessment and mitigation strategies
- Step-by-step implementation guide with clear ordering
- Testing strategy
- Success criteria

**Plans should NOT:**
- Suggest generic solutions without codebase context
- Ignore existing patterns and conventions
- Skip data model or API design
- Omit testing or documentation steps
- Make assumptions without verification

## Resources

### scripts/
- `feature_planner.py` - Automated plan generator (optional enhancement)

### references/
- `plan-templates.md` - Deep templates for common feature types
- `decision-framework.md` - Framework for architecture decisions
- `integration-patterns.md` - Common integration patterns

### assets/
- (none currently)