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)

•Listen carefully: Read the user's request completely
•
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?
•Identify plan type: Feature, refactor, exploration, or epic
•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.

•
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
•
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
•
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
•
Map dependencies:
- •What npm packages might be needed?
- •What internal features does this depend on?
- •Are there any blocking tasks?
•
Identify risks:
- •What could go wrong?
- •Are there performance concerns?
- •Security considerations (input validation, authentication)?
- •Data migration needs?

Phase 3: Approach Design (Technical Solution)

•
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)
•
Break down into phases:
- •Phase 1: Core functionality
- •Phase 2: Testing
- •Phase 3: Polish and edge cases
•
Plan implementation steps:
- •List specific files to create or modify
- •Describe key changes needed in each file
- •Identify test scenarios
•
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:

•
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
•
Complete template with all sections filled (see template below)
•
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:

code

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:

code

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

code

/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:

code

/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:

markdown

# [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.

code


## 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:

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

Would you like me to clarify anything in the plan?

code


## 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