planning-guidelines

What this skill does

# 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:**
```typescript
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** ✅
   - Isolated calculation (one line)
   - Easy to understand (calendar days vs trading days)
   - Easily reversible if wrong

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

3. **No Unnecessary Complexity** ✅
   - Added 9 lines (calendar day calculation)
   - Clearer, more correct logic
   - 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**
```tsx
className="text-xs sm:text-sm"        // Smaller on mobile
className="text-base sm:text-lg"      // Larger on desktop
```

**Example 2: Responsive Spacing**
```tsx
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**
```tsx
className="flex flex-col sm:flex-row"  // Stack on mobile, row on desktop
```

**Example 4: Responsive Visibility**
```tsx
<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-