Planning Framework

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

Step 3 - Simplify:

• Add single risk-free rate input (not per-strategy)
• Calculate in existing calculateMetrics() function
• Add column to existing MetricsTable

ICE Score: 50.4 (High Priority)

Approach:

• Add calculateSortino() to dataUtils.ts
• Include Sortino in metrics calculation
• Add risk-free rate input to PortfolioSection
• Add Sortino column to MetricsTable
• Test with sample data

Time Estimate: 3-4 hours

Result: Completed successfully, but found calculation bug (commit 9f25040 fixed it).

Implementation Note: Sortino was implemented inline in PortfolioSection.tsx (lines 133-158) rather than in dataUtils.ts. This decision was made because:

• Sortino requires portfolio-level daily returns (not trade-level metrics)
• Needs user input state (risk-free rate)
• Different calculation context than win rate, profit factor, etc.
• Team should discuss whether to extract to dataUtils for consistency

Example: Refactoring PortfolioSection (Future Work)

Step 1 - Requirements:

• Component is 591 lines (3x limit)
• Hard to maintain and understand
• Want to follow coding standards

Step 2 - Delete:

• Review for duplicate logic
• Remove commented-out code
• Consolidate similar state handlers

Step 3 - Simplify:

• Extract ContractControls.tsx (contract multiplier UI)
• Extract EquityChartSection.tsx (Chart.js config)
• Extract PortfolioStats.tsx (statistics display)
• Keep only orchestration in main component

ICE Score: 19.2 (Medium Priority)

Approach:

• Create EquityChartSection component (150 lines)
• Create PortfolioStats component (80 lines)
• Create ContractControls component (100 lines)
• Refactor main PortfolioSection to <100 lines
• Test all functionality still works

Time Estimate: 4-6 hours (tedious but straightforward)

Risks:

• Breaking existing functionality
• Props drilling if not careful
• Testing all edge cases

Decision: Medium priority. Do after more urgent user-facing features.

Example: Vitest Testing Setup (Future Work)

Step 1 - Requirements:

• No tests currently
• Critical calculations need testing (Sharpe, Sortino, correlation)
• Prevent regressions in metric calculations

Step 2 - Delete:

• Don't need 100% coverage
• Skip UI/component testing for now
• Focus only on calculation functions

Step 3 - Simplify:

• Test only dataUtils.ts functions
• Use Vitest (built-in with Vite)
• Mock data from real CSV files

ICE Score: 24 (Medium Priority)

Approach:

• Install Vitest: npm install -D vitest
• Add test script to package.json
• Create dataUtils.test.ts
• Write tests for critical calculations
• Run tests in CI eventually

Time Estimate: 6-8 hours (learning curve + writing tests)

Tests to Write:

• calculateSharpe() with known data
• calculateSortino() with known data
• calculateCorrelation() edge cases
• parseCSV() error handling

Red Flags to Watch For

During Planning

• ❌ "This will only take 30 minutes" (usually takes 2-3 hours)
• ❌ "I'll just use any types for now" (technical debt accumulates)
• ❌ "We might need this later" (YAGNI - You Aren't Gonna Need It)
• ❌ "Everyone does it this way" (verify it fits your use case)

During Implementation

• ❌ Component approaching 200 lines (refactor NOW, not later)
• ❌ Duplicating logic from another file (extract to shared utility)
• ❌ Adding dependency without checking size/alternatives
• ❌ No error handling ("will add later" = never happens)

Portfolio Buddy 2 Lessons

• ✅ Did well: Questioned need for Redux, used plain React hooks instead
• ✅ Did well: Chose Chart.js over Recharts after testing both
• ❌ Should improve: Let PortfolioSection grow to 591 lines
• ❌ Should improve: Accumulated 14 any type violations

Framework in Action

When you're about to start coding, ask:

• What am I building? (clear requirement)
• Why am I building it? (real problem to solve)
• What can I delete? (remove unnecessary parts)
• What's the simplest version? (MVP approach)
• How confident am I? (ICE scoring)
• What's the time estimate? (be realistic, multiply by 2)

Then write your plan as:

• 3-5 bullet point approach
• Time estimate
• Files that will change
• Potential issues

Finally:

• Get feedback if >4 hours of work
• Start with smallest testable increment
• Commit frequently