planning-guidelines

Planning Guidelines for Portfolio Buddy 2

Core Principles

When planning and implementing features for Portfolio Buddy 2, always follow these fundamental principles:

1. Preserve Existing Code - Default to extending rather than replacing
2. Optimize for Mobile & Desktop - Every feature must work well on both
3. Ask Clarifying Questions - Gather complete context before execution
4. Integrate Seamlessly - New code should feel native to the existing codebase

Code Preservation Strategy

Default Behavior: Always Preserve

Rule: Preserve existing code unless explicitly instructed to refactor or rewrite.

When implementing new features or fixes:

• ✅ Extend existing components
• ✅ Add new functions alongside existing ones
• ✅ Preserve existing patterns and conventions
• ✅ Maintain backward compatibility
• ❌ Don't refactor working code "just because"
• ❌ Don't introduce new patterns without justification

Exception: Massively Better Options

You MAY propose improvements to existing code ONLY when ALL conditions are met:

1. Very Low Risk - Change is isolated, well-understood, easily reversible
2. Massive Upside - Significant benefit (correctness, performance, maintainability)
3. No Unnecessary Complexity - Solution is simpler or equal complexity
4. Clear Justification - Can explain why exception applies

When exception applies, you MUST:

• Explain the problem with current implementation
• Show the proposed improvement
• Demonstrate why it meets all three criteria
• Get user approval before implementing

Real Example: Annual Growth Rate Fix

Situation: During implementation of Trading Days update, discovered Annual Growth Rate calculation was mathematically incorrect.

Current (incorrect) code:

const tradingPeriodDays = uniqueTradingDates.size || 1;  // 150 days
const annualGrowthRate = (totalPnl / startingCapital / tradingPeriodDays) * 365 * 100;
// Result: Inflated by mixing trading days (denominator) with calendar day annualization (365)

Why exception applied:

1. Very Low Risk ✅
2. Isolated calculation (one line)
3. Easy to understand (calendar days vs trading days)
4. Easily reversible if wrong

1. Massive Upside ✅
2. Fixes incorrect financial metric (accuracy critical)
3. Returns were inflated by ~2.4x
4. Aligns with financial industry standards

1. No Unnecessary Complexity ✅
2. Added 9 lines (calendar day calculation)
3. Clearer, more correct logic
4. No new dependencies

Result: User approved fix immediately because exception criteria were clearly met.

Mobile & Desktop Optimization

Every feature must be optimized for both mobile and desktop experiences.

Quick Reference Checklist

✅ Use Responsive Tailwind Classes

• Base styles for mobile (no prefix)
• sm: for small screens (640px+)
• md: for medium screens (768px+)
• lg: for large screens (1024px+)

✅ Touch Targets

• Minimum 44x44 pixels for all interactive elements
• Use touch-manipulation CSS class for better touch response

✅ Test Both Viewports

• Verify layout works on mobile and desktop before completion
• Check that text is readable on small screens
• Ensure buttons/inputs are appropriately sized

Existing Patterns to Follow

Portfolio Buddy 2 already has excellent responsive patterns. Reference these:

Example 1: Responsive Text Sizing

className="text-xs sm:text-sm"        // Smaller on mobile
className="text-base sm:text-lg"      // Larger on desktop

Example 2: Responsive Spacing

className="gap-1 sm:gap-2"           // Tighter gaps on mobile
className="px-2 sm:px-4 py-2 sm:py-3" // Smaller padding on mobile

Example 3: Responsive Layout

className="flex flex-col sm:flex-row"  // Stack on mobile, row on desktop

Example 4: Responsive Visibility

<span className="hidden sm:inline">Total Margin</span>  // Hide text on mobile, show on desktop

See: [src/components/PortfolioSection.tsx](src/components/PortfolioSection.tsx) for comprehensive examples of responsive patterns throughout the application.

Clarifying Questions Framework

When to Ask Questions

Ask clarifying questions BEFORE executing when:

• Requirements are ambiguous
• Multiple valid approaches exist
• Decision affects architecture or user experience
• User's request could be interpreted multiple ways
• You need context about business logic or domain knowledge

Question Format Template

Use this structure for ALL clarifying questions:

## Clarifying Question: [Topic]

[Brief context about why you need to ask]

**Option A: [Approach Name]** ✅ (Recommended)
- [Detail about approach]
- [Key characteristics]
- **Pros:** [Benefits]
- **Cons:** [Trade-offs]
- **Why experts prefer this:** [Technical reasoning from domain expert perspective]

**Option B: [Alternative Approach]**
- [Detail about approach]
- [Key characteristics]
- **Pros:** [Benefits]
- **Cons:** [Trade-offs]
- **Trade-offs:** [Why this isn't the top choice]

**Option C: [Another Alternative]** (if applicable)
- [Detail about approach]
- [Key characteristics]
- **Pros:** [Benefits]
- **Cons:** [Trade-offs]
- **Trade-offs:** [Why this isn't the top choice]

Key Requirements

1. Mark Best Option - Use ✅ to indicate expert-recommended choice
2. Explain Reasoning - "Why experts prefer this" section required
3. Unbiased Options - Present all options fairly, let marking indicate preference
4. Complete Context - User should understand trade-offs without additional research

Real Example: Trading Days Calculation

From today's conversation about how to calculate Trading Days:

## Clarifying Question 2: Trading Days Calculation with Date Filters

When the user sets a custom date range (Start Date/End Date), should Trading Days represent:

**Option A: The number of calendar days in the selected date range** ✅ (Recommended)
- Example: Jan 1 to Jan 31 = 31 days
- **Pros:** Simple, matches user's mental model of "days in range"
- **Cons:** Doesn't account for non-trading days
- **Why experts prefer this:** For portfolio analysis, calendar days provide accurate time-based performance metrics and match financial industry standards for annualized returns.

**Option B: The number of actual trading days (days with trades) within the date range**
- Example: Jan 1 to Jan 31 = only count days where trades occurred (e.g., 18 days)
- **Pros:** Reflects actual market activity
- **Cons:** Can be misleading - a strategy might not trade every day by design
- **Trade-offs:** Better for measuring trading frequency, not time-based performance

Outcome: User chose Option B, demonstrating how clear options enable informed decisions.

Decision Criteria

When to Preserve vs Improve

Use this decision tree:

Is the code broken or incorrect?
├─ YES → Fix it (with explanation)
└─ NO → Is there a massively better option?
    ├─ YES → Does it meet ALL exception criteria?
    │   ├─ YES → Propose improvement (get approval)
    │   └─ NO → Preserve existing code
    └─ NO → Preserve existing code

Risk Assessment Checklist

Before proposing any change to existing code, verify:

• [ ] Change is isolated to specific files/functions
• [ ] No ripple effects on other features
• [ ] TypeScript compilation succeeds
• [ ] No breaking changes to interfaces
• [ ] Existing tests still pass (if tests exist)
• [ ] Can be reverted with single git revert

Complexity Evaluation

Avoid unnecessary complexity:

• ❌ Adding new libraries when existing ones suffice
• ❌ Introducing new patterns when existing patterns work
• ❌ Over-engineering simple features
• ❌ Premature optimization
• ✅ Using existing utilities and components
• ✅ Following established patterns
• ✅ Simple, readable solutions

Integration with Other Skills

This skill works alongside other Portfolio Buddy 2 skills:

• **Use with `planning-f