Task-Board Planning Skill

This skill provides specialized workflows for creating and managing implementation plans in the finans project. It transforms user requests into comprehensive, well-researched plan files that guide future implementation.

CRITICAL CONSTRAINT: This skill is for planning and documentation ONLY. Never implement fixes, write code changes, or modify the codebase. The sole responsibility is creating thorough plan documentation in .task-board/backlog/.

When to Use This Skill

Use this skill for:

• Feature planning requiring technical design
• Refactoring plans needing impact assessment
• Exploration and research documentation
• Breaking down epics into implementation phases
• User requests that need structured planning

DO NOT use this skill for:

• Quick bug fixes (just implement directly)
• Simple changes with obvious implementation
• Active code implementation (skill is planning-only)
• Trivial updates that don't need planning
• AI scaffolding (CLAUDE.md, rules, skills, commands) - update directly, no task

Core Planning Principles

• Research before planning: Thoroughly explore the codebase before creating plan files
• Ask clarifying questions: Never assume—gather complete information from users
• Break down complexity: Decompose large features into manageable phases
• Identify dependencies: Map out external packages, internal dependencies, and blocking work
• Document technical approach: Include architecture decisions, file paths, and code references
• Assess risks: Identify what could go wrong and mitigation strategies
• Plan-only: Focus solely on designing the approach, not implementing

Planning Workflow

Phase 1: Initial Understanding (Gather Context)

1. Listen carefully: Read the user's request completely
2. Ask clarifying questions to understand scope:
   • What problem are you trying to solve?
   • What does success look like?
   • Are there any constraints or preferences?
   • What's the priority level?
   • What's the estimated timeline?
3. Identify plan type: Feature, refactor, exploration, or epic
4. Assess complexity: Simple (1-2 days), Medium (3-5 days), or Complex (1+ weeks)

Phase 2: Codebase Research (Deep Exploration)

CRITICAL: Conduct thorough research before creating the plan file.

1. Search for relevant code:

   • Use search tools to find related features, components, or patterns
   • Look for similar implementations in the codebase
   • Check for existing utilities or shared components to reuse

2. Read relevant files:

   • Examine the feature area (frontend/backend/components)
   • Review related components and dependencies
   • Check test files for existing coverage patterns
   • Look at API routes and database schema

3. Understand architecture:

   • Frontend: Feature folders, Zustand stores, TanStack Query hooks, BeerCSS components
   • Backend: Express routes, validation layers, CosmosDB containers
   • Shared: Component library, utility functions, types

4. Map dependencies:

   • What npm packages might be needed?
   • What internal features does this depend on?
   • Are there any blocking tasks?

5. Identify risks:

   • What could go wrong?
   • Are there performance concerns?
   • Security considerations (input validation, authentication)?
   • Data migration needs?

Phase 3: Approach Design (Technical Solution)

1. Define architecture decisions:

   • Where should code live? (feature folder, shared component, utility)
   • What patterns to follow? (existing patterns in the codebase)
   • State management approach? (Zustand, TanStack Query, Context)

2. Break down into phases:

   • Phase 1: Core functionality
   • Phase 2: Testing
   • Phase 3: Polish and edge cases

3. Plan implementation steps:

   • List specific files to create or modify
   • Describe key changes needed in each file
   • Identify test scenarios

4. Consider finans-specific context:

   • Norwegian language and number formatting (123 456,78 kr)
   • Portfolio tracking domain (accounts, asset classes, net worth)
   • Financial calculators (compound interest, Monte Carlo)
   • Monorepo coordination (frontend/backend/components)
   • EasyAuth authentication patterns
   • CosmosDB partitioning and queries

Phase 4: Documentation (Create Plan File)

Create a comprehensive plan file in .task-board/backlog/ with:

1. Descriptive filename following conventions:

   • FEATURE-[short-description].md - New functionality
   • REFACTOR-[short-description].md - Code improvements
   • EXPLORE-[short-description].md - Research/investigation
   • EPIC-[short-description].md - Major multi-phase features

2. Complete template with all sections filled (see template below)

3. Specific technical details:

   • File paths: frontend/src/features/portfolio/PortfolioPage.tsx
   • Code snippets showing relevant patterns
   • Architecture context (Zustand store, API endpoint, database container)
   • Dependencies and integration points

Phase 5: Validation (Confirm Completeness)

Before finishing, verify:

• User's request is fully understood
• All clarifying questions answered
• Technical approach is clear and feasible
• Specific file locations and paths included
• Dependencies and risks identified
• Test requirements outlined
• Priority and effort estimate set
• Plan file created in backlog/ folder
• User informed that plan is ready for implementation

File Naming Convention

Use numbered, descriptive, kebab-case names with type prefix:

Format: [NNN]-[TYPE]-[short-description].md

Task Numbering - CRITICAL

🚨 ALWAYS scan ALL folders to find the next task number:

1. Glob pattern: .task-board/**/*.md
2. Scan: backlog/, in-progress/, AND done/
3. Extract numbers from filenames (e.g., 071-FEATURE-xxx.md → 071)
4. Find highest number across ALL folders
5. Next task = highest + 1

Why include done/: Completed tasks retain their numbers. Reusing numbers breaks history tracking and causes confusion.

Example:

done/ has: 001-070 (completed)
in-progress/ has: 071
backlog/ has: 072-075

Next task number = 076

Type Prefixes

• Features: [NNN]-FEATURE-[short-description].md

  • Example: 076-FEATURE-llm-data-import.md
  • Example: 077-FEATURE-monte-carlo-calculator.md

• Refactors: [NNN]-REFACTOR-[short-description].md

  • Example: 078-REFACTOR-extract-calculator-logic.md

• Explorations: [NNN]-EXPLORE-[short-description].md

  • Example: 079-EXPLORE-langfuse-integration.md

• Epics: [NNN]-EPIC-[short-description].md

  • Example: 080-EPIC-portfolio-tracker.md

Finans Project Context

Domain Knowledge

Portfolio & Wealth Tracking:

• Account-based tracking (not individual holdings)
• Asset classes: aksjer, fond, krypto, bankkonto, custom
• Monthly snapshots with account balances
• Total net worth calculations
• F.I.R.E. planning and projections

Financial Calculators:

• Compound interest calculator
• Monte Carlo simulations
• Future retirement scenarios
• Loan amortization

Norwegian Localization:

• UI language: Norwegian (Bokmål)
• Number format: 123 456,78 kr (space thousands, comma decimal)
• Date format: dd.MM.yyyy (01.01.2024)
• Currency: NOK (kroner)

Technology Stack

Frontend (/frontend):

• React 18+ with TypeScript
• Vite build tool
• BeerCSS + Material UI for styling
• D3.js for visualizations
• Zustand (client state), TanStack Query (server state), Context (auth)
• Axios for HTTP
• React Hook Form + Zod for forms

Backend (/backend):

• Node.js + Express + TypeScript
• Azure App Service
• EasyAuth (Google + Facebook OAuth)
• CosmosDB (NoSQL database)
• Winston logging

Components (/components):

• Shared React component library
• Storybook for documentation
• Bundled into frontend (not published to npm)

Testing (/e2e):

• Playwright for E2E tests
• Page Object Model pattern

Architecture Patterns

Frontend Organization (Vertical Slicing):

/frontend/src/
  /features/
    /auth/           - LoginPage, AuthContext, useAuth
    /portfolio/      - PortfolioPage, PortfolioTable, usePortfolio
    /calculators/    - CompoundCalculator, MonteCarloSimulation
    /dashboard/      - DashboardPage, NetWorthChart
  /shared/
    /components/     - Shared UI components
    /hooks/          - Shared custom hooks
    /utils/          - Utility functions

Backend Organization:

/backend/src/
  /routes/          - Express route definitions
  /controllers/     - Request handlers
  /validation/      - Input and business validation
  /services/        - Business logic and database access

State Management:

• Zustand: UI preferences, local state
• TanStack Query: All API data, server state
• Context: Auth state (EasyAuth user)
• useState: Component-specific UI state

Database (CosmosDB):

• Container: users (partition: /id) - User profiles
• Container: portfolios (partition: /userId) - Monthly snapshots with accounts

API Design:

• Base path: /api/v1
• REST conventions (GET, POST, PATCH, DELETE)
• Two-layer validation (input + business)
• Standard response format with { data, success } or { error, success }

Enhanced Plan Template

Use this comprehensive template for all plan files. Fill in ALL sections based on research:

# [Type]: [Short Description]

**Status**: Backlog
**Created**: [YYYY-MM-DD]
**Priority**: [High/Medium/Low]
**Labels**: [frontend, backend, database, calculator, etc.]
**Estimated Effort**: [Simple/Medium/Complex - X days/weeks]

## Context & Motivation

[Why this work is needed - business value, user need, or technical debt]

## Current State

[What exists today - relevant background, current implementation]

## Desired Outcome

[What we want to achieve after this is complete - specific goals]

## Acceptance Criteria

- [ ] [Specific, measurable criterion 1]
- [ ] [Specific, measurable criterion 2]
- [ ] [Specific, measurable criterion 3]
- [ ] [Tests covering the implementation]
- [ ] [Documentation updated if needed]

## Affected Components

### Frontend (if applicable)
- **Features**: [Feature folders, e.g., `/frontend/src/features/portfolio/`]
- **Components**: [Shared components from `/components/src/`]
- **State Management**: [Zustand stores, TanStack Query hooks, Context]
- **Routes**: [New or modified routes]

### Backend (if applicable)
- **API Endpoints**: [New or modified routes, e.g., `POST /api/v1/snapshots`]
- **Controllers**: [Controller files]
- **Validation**: [Input validation, business validation logic]
- **Database**: [CosmosDB containers/documents affected]

### Testing (E2E only - no unit tests per CLAUDE.md)
- **E2E Tests**: [Playwright test scenarios]

## Technical Approach

### Architecture Decisions

[Key architectural choices and rationale]
- Example: "Use Zustand for calculator state because it's simple and doesn't need server sync"
- Example: "Create new `/calculators` feature folder following vertical slicing pattern"

### Implementation Steps

1. **[Phase 1: Core Implementation]**
   - Files to create: [specific paths]
   - Files to modify: [specific paths]
   - Key changes: [what needs to be done]

2. **[Phase 2: Testing]**
   - Test files to create: [specific paths]
   - Test scenarios: [what to test]

3. **[Phase 3: Integration]**
   - Integration points: [what needs to connect]
   - Final verification: [how to confirm it works]

### Dependencies

- **External**: [npm packages needed, APIs, services]
- **Internal**: [Other features/components this depends on]
- **Blocking**: [Other tasks that must be completed first]

### Risks & Considerations

- **Risk 1**: [What could go wrong] - **Mitigation**: [How to address]
- **Risk 2**: [What could go wrong] - **Mitigation**: [How to address]
- **Performance**: [Any performance concerns and how to handle them]
- **Security**: [Input validation, authentication, data protection]

## Code References

### Relevant Existing Code

```[language]
// File: [path/to/file.ext]
[Relevant code snippet showing similar patterns or context]

Similar Patterns

[Point to existing code that follows similar patterns]

• Example: "See /frontend/src/features/auth/ for feature folder structure"
• Example: "Follow validation pattern in /backend/src/validation/userValidator.ts"

Design Notes

[Optional sections based on plan type]

UI/UX Considerations (if frontend work)

• BeerCSS components to use
• Norwegian language text
• Responsive design needs
• Accessibility requirements

Data Model (if database work)

• Document structure
• Partition key strategy
• Query patterns

API Contract (if backend work)

• Request/response formats
• Status codes
• Error handling

Implementation Plan

[This section added when moving to in-progress - detailed step-by-step breakdown]

Progress Log

[This section added during implementation - real-time updates]

• YYYY-MM-DD HH:MM - [What was done]
• YYYY-MM-DD HH:MM - [What was done]

Verification

[This section added during implementation - how to verify completion]

• All acceptance criteria met
• E2E tests passing (no unit tests per CLAUDE.md)
• Code reviewed
• Documentation updated
• Deployed and tested

Resolution

[This section added when complete - summary of implementation, any deviations from plan]

Related Plans

• [Link to related plan 1]
• [Link to blocking plan]
• [Link to follow-up work]

---

Next Steps: Ready for implementation. Move to .task-board/in-progress/ when starting work.

## Best Practices

### Research Quality
1. **Thorough exploration**: Search multiple ways (keywords, file patterns, component names)
2. **Read, don't skim**: Actually read files to understand patterns
3. **Follow the trail**: Find imports, usages, related files
4. **Check similar features**: Learn from existing implementations
5. **Multiple perspectives**: Look at frontend, backend, database, tests

### Question Quality
1. **Ask specific questions**: "Which calculators need this feature?" vs "Tell me more"
2. **Confirm scope**: "Should this work for all asset classes or just stocks?"
3. **One at a time**: Don't overwhelm with 10 questions
4. **Progressive refinement**: Start broad, get specific

### Documentation Quality
1. **Be specific**: Use exact file paths, not "the calculator code"
2. **Include evidence**: Show code snippets, not just descriptions
3. **Quantify scope**: "Affects 3 calculators" vs "affects calculators"
4. **State confidence**: "High confidence" vs "Hypothesis - needs verification"
5. **Link everything**: Cross-reference files, plans, documentation

### Completeness Checklist

Before creating a plan file, verify:
- [ ] **User's intent is clear** - Asked clarifying questions if needed
- [ ] **Technical approach designed** - Architecture decisions documented
- [ ] **Specific file paths** - Listed exact files to create/modify
- [ ] **Code references included** - Showed relevant patterns
- [ ] **Dependencies identified** - External packages, internal features, blocking work
- [ ] **Risks assessed** - What could go wrong and mitigations
- [ ] **Test requirements** - Unit, integration, E2E scenarios
- [ ] **Effort estimated** - Simple/Medium/Complex with timeline
- [ ] **Priority set** - High/Medium/Low with justification
- [ ] **All template sections filled** - No [TODO] or empty sections

## Communication Guidelines

### When Creating a Plan

**DO**:
- Thank user for the request
- Ask clarifying questions upfront
- Explain what you're researching
- Share findings as you discover them
- Be honest about uncertainty
- Provide confidence levels

**DON'T**:
- Jump to planning without research
- Assume scope without asking
- Promise implementation (you only plan)
- Use jargon without context
- Create plan prematurely

## Limitations and Boundaries

### What This Skill Does
✅ Creates structured implementation plans
✅ Researches codebase and identifies patterns
✅ Designs technical approaches
✅ Breaks down complex work into phases
✅ Identifies dependencies and risks
✅ Documents architecture decisions
✅ Asks clarifying questions

### What This Skill Does NOT Do
❌ Implement code or write features
❌ Modify existing files (except creating plan files)
❌ Run tests or execute commands
❌ Create pull requests
❌ Update PLANNING-BOARD.md (done during implementation)
❌ Move plans between folders (stays in backlog)

## Handoff to Implementation

After creating a plan file, inform the user:

✓ Plan documented: .task-board/backlog/[PLAN-NAME].md

Next steps:

1. Review the plan to ensure accuracy and completeness
2. Add to PLANNING-BOARD.md if this is a top priority (max 3-5 items)
3. When ready to implement, move file to .task-board/in-progress/
4. Follow TDD approach: write tests, implement features, verify passing
5. Move to .task-board/done/ when complete

Would you like me to clarify anything in the plan?

## Integration with Workflow

This skill creates plans in `backlog/` folder. The implementation workflow then:
1. Adds plan to PLANNING-BOARD.md if it's a priority (max 3-5 items)
2. Moves file to `in-progress/` when starting work
3. Adds detailed implementation breakdown
4. Updates progress log during work
5. Moves to `done/` when complete
6. Updates PLANNING-BOARD.md to remove completed item

## See Also

- [`.task-board/WORKFLOW.md`](../../.task-board/WORKFLOW.md) - Complete workflow documentation
- [`.task-board/PLANNING-BOARD.md`](../../.task-board/PLANNING-BOARD.md) - Current top priorities
- [`.task-board/README.md`](../../.task-board/README.md) - System overview
- [`.claude/CLAUDE.md`](../../.claude/CLAUDE.md) - Project-wide instructions