planning-framework

What this skill does

# Planning Framework

## When to Use
Before starting ANY significant coding task:
- New features (> 50 lines of code)
- Refactoring existing components
- Architectural changes
- Debugging complex issues

## Musk's 5-Step Algorithm

### Step 1: Make Requirements Less Dumb
**Question everything:**
- Who requested this feature? Why?
- What problem does it actually solve?
- Is there a simpler way to achieve the same outcome?
- What happens if we don't build this?

**Portfolio Buddy 2 Example**:
> **Request**: "Add sortable columns to metrics table"
>
> **Questions**:
> - Why? Users want to find best/worst performing strategies quickly
> - Simpler solution? Just default sort by Sharpe Ratio (most important metric)
> - Alternative? Add "Top 3" and "Bottom 3" highlight sections
>
> **Decision**: Implemented full multi-column sorting via `useSorting` hook because:
> - Different users care about different metrics (Sharpe vs Sortino vs Max DD)
> - Sorting is O(n log n) - negligible for <100 strategies
> - Reusable hook can be used in future tables

### Step 2: Delete the Part or Process
**What can we eliminate?**
- Remove features that serve no clear purpose
- Cut unnecessary steps in workflows
- Simplify data structures
- Delete unused dependencies

**Rule**: If you don't add back 10% of what you deleted, you didn't delete enough.

**Portfolio Buddy 2 Example**:
> **Discovery**: Recharts library (11.5KB) installed but never imported
>
> **Questions**:
> - Is it used anywhere? NO - search reveals zero imports
> - Why was it installed? Probably initial plan, switched to Chart.js
> - Can we delete it? YES - nothing depends on it
>
> **Action**: `npm uninstall recharts` (saves 11.5KB in bundle)
>
> **Result**: Cleaner dependency tree, faster installs, smaller bundle

### Step 3: Simplify or Optimize
**Only after deleting:**
- Simplify remaining code
- Extract reusable functions
- Improve type safety
- Reduce complexity

**Portfolio Buddy 2 Example**:
> **Problem**: PortfolioSection.tsx is 591 lines (3x the 200-line limit)
>
> **Before Optimization**:
> ```typescript
> function PortfolioSection() {
>   // 50 lines of contract multiplier logic
>   // 40 lines of date filtering logic
>   // 100 lines of Chart.js configuration
>   // 80 lines of statistics calculations
>   // 300+ lines of JSX rendering
> }
> ```
>
> **After Simplification**:
> ```typescript
> // Extract hooks
> const portfolio = usePortfolio(files, dateRange)
> const contracts = useContractMultipliers(strategies)
>
> // Extract components
> <ContractControls {...contracts} />
> <EquityChartSection data={portfolio.equity} />
> <PortfolioStats metrics={portfolio.metrics} />
> ```
>
> **Result**: Main component < 100 lines, logic encapsulated, reusable

### Step 4: Accelerate Cycle Time
- Reduce build/test time
- Improve developer experience
- Add helpful error messages
- Optimize feedback loops

**Portfolio Buddy 2 Example**:
> **Before**: Create React App build time: ~30 seconds
>
> **Action**: Migrated to Vite
>
> **After**: Vite build time: ~2 seconds (15x faster)
>
> **Impact**: Developer can iterate 15x more per hour

### Step 5: Automate
Last step only - automate what's proven necessary.

**Portfolio Buddy 2 Example**:
> **Don't automate yet**: CI/CD pipeline
> - Manual Cloudflare deployments work fine for now
> - Only deploying 2-3x per month
> - Setting up GitHub Actions would take 2-4 hours
> - Wait until deployment frequency increases
>
> **Should automate**: TypeScript checking on commit
> - Would catch `any` type violations before merge
> - Git pre-commit hook: `tsc --noEmit`
> - Saves debugging time later

## ICE Scoring Framework

Evaluate solutions using:
- **Impact**: How much does this move the needle? (1-10)
- **Confidence**: How certain are we this will work? (1-10)
- **Ease**: How simple to implement? (1-10)

**ICE Score = (Impact × Confidence × Ease) / 10**

### Portfolio Buddy 2 Examples

#### Example 1: Error Boundaries (High Priority)
**Feature**: Add React error boundaries around risky components
- **Impact**: 7 (prevents full app crashes from component errors)
- **Confidence**: 9 (standard React pattern, well-documented)
- **Ease**: 8 (wrapper component + fallback UI, ~50 lines)
- **ICE Score**: (7 × 9 × 8) / 10 = **50.4** → **HIGH PRIORITY**

**Decision**: Should implement soon. Quick win, high impact.

#### Example 2: Export to Excel (Medium-High Priority)
**Feature**: Add Excel export button for metrics table
- **Impact**: 8 (users explicitly requested it)
- **Confidence**: 8 (libraries like xlsx exist, proven solution)
- **Ease**: 7 (format data, generate file, trigger download)
- **ICE Score**: (8 × 8 × 7) / 10 = **44.8** → **HIGH PRIORITY**

**Decision**: Worth implementing. Clear user value, reasonable effort.

#### Example 3: Refactor PortfolioSection (Medium Priority)
**Feature**: Split 591-line component into smaller pieces
- **Impact**: 6 (improves maintainability, no user-facing change)
- **Confidence**: 8 (clear extraction points identified)
- **Ease**: 4 (tedious, 4-6 hours, risk of breaking things)
- **ICE Score**: (6 × 8 × 4) / 10 = **19.2** → **MEDIUM PRIORITY**

**Decision**: Important for code health, but not urgent. Do after user-facing features.

#### Example 4: Real-time Price Updates via WebSocket (Low Priority)
**Feature**: Live market data updates in charts
- **Impact**: 6 (nice to have, but app analyzes historical data)
- **Confidence**: 5 (complex integration, data source needed)
- **Ease**: 3 (WebSocket setup, state management, error handling)
- **ICE Score**: (6 × 5 × 3) / 10 = **9** → **LOW PRIORITY**

**Decision**: Skip for now. Doesn't fit core use case (historical analysis).

#### Example 5: Remove Recharts Dependency (Quick Win)
**Feature**: Uninstall unused Recharts library
- **Impact**: 3 (small bundle size reduction, cleaner deps)
- **Confidence**: 10 (confirmed never imported anywhere)
- **Ease**: 10 (one command: `npm uninstall recharts`)
- **ICE Score**: (3 × 10 × 10) / 10 = **30** → **MEDIUM PRIORITY**

**Decision**: Easy quick win. Do it next time touching package.json.

#### Example 6: Sortino Ratio Calculation (Completed)
**Feature**: Add Sortino Ratio metric (already completed)
- **Impact**: 8 (important risk-adjusted metric for traders)
- **Confidence**: 9 (well-defined formula, similar to Sharpe)
- **Ease**: 7 (calculation + UI + risk-free rate input)
- **ICE Score**: (8 × 9 × 7) / 10 = **50.4** → **HIGH PRIORITY**

**Result**: Successfully implemented in commits 258ba3a & 9f25040.

### ICE Score Interpretation

| ICE Score Range | Priority | Action |
|-----------------|----------|--------|
| 40+ | High | Do soon, within 1-2 sprints |
| 25-39 | Medium-High | Plan for next 2-3 sprints |
| 15-24 | Medium | Backlog, do when capacity available |
| 10-14 | Low | Consider if very easy or strategic |
| < 10 | Very Low | Probably skip unless requirements change |

## Planning Checklist

Before coding:
- [ ] Applied Step 1: Questioned requirements thoroughly
- [ ] Applied Step 2: Identified what can be deleted/simplified
- [ ] Calculated ICE score (for features > 100 lines)
- [ ] Confirmed simpler solution doesn't exist
- [ ] Identified which components/hooks will be affected
- [ ] Checked for existing similar functionality in codebase
- [ ] Reviewed related code to understand context

After planning:
- [ ] Written approach in 3-5 bullet points
- [ ] Identified potential issues/edge cases
- [ ] Estimated time realistically (multiply initial guess by 2)
- [ ] Confirmed TypeScript types are planned (no `any`)
- [ ] Verified component won't exceed 200 lines

## Portfolio Buddy 2 Planning Examples

### Example: Adding Sortino Ratio (Completed Feature)

**Step 1 - Requirements**:
- Users need Sortino Ratio alongside Sharpe Ratio
- Sortino focuses on downside risk (more relevant for traders)
- Requires risk-free rate input

**Step 2 - Delete**:
- Don't need separate page for advanced metrics
- Don't need tutorial/help text (formula is standa