| name | task-board |
| description | Planning specialist that creates structured implementation plans for the finans project. Use this skill to transform user requests into comprehensive, well-researched plan files stored in .task-board/backlog/. This skill plans without implementing. |
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 functionalityREFACTOR-[short-description].md - Code improvementsEXPLORE-[short-description].md - Research/investigationEPIC-[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:
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]
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:
- 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?
## 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
