/plan - Implementation Planner

Launches the implementation-planner agent to create a detailed implementation plan for a React/TypeScript feature before writing code.

Usage

# Plan a new feature
/plan Add offline expense capture UI

# Plan a refactoring
/plan Refactor dashboard filters into composable hooks

# Plan with context
/plan Implement PWA sync queue per the requirements in issue #42

What You Get

The planner creates a concise, actionable plan that includes:

Plan Structure

• •Overview: What we're building and why
• •Affected Files: Files that will be created/modified
• •Feature Architecture Validation: Layer placement and dependency direction
• •React Principles Compliance: How the design follows React/TypeScript principles
• •Implementation Steps: Numbered, sequential steps
• •Testing Strategy: What needs to be tested
• •Risk Assessment: Categorized risks (see below)
• •Open Questions: Decisions that need clarification

Planner's Expertise

The planner knows:

• •Every file in the SpendiaBot React/PWA codebase
• •Feature-based folder conventions (components/, hooks/, lib/, context/, types/)
• •React Router, Suspense, TanStack Query, Dexie, and service worker patterns in the repo
• •State management choices (context, Zustand, Redux Toolkit, React Query cache)
• •PWA caching/sync flows and IndexedDB constraints
• •Testing conventions (Vitest + Testing Library, Playwright smoke flows)
• •Current phase from PLAN.md and linked initiatives
• •Tech debt highlighted in GitHub issues/retro notes

Output Location

Plans are saved based on context:

When working on an issue:

.md/issues/{issue-number}/plan.md

When not on an issue (standalone):

.md/standalone/plan-{feature-name}.md

Examples:

• •Issue #42: .md/issues/42/plan.md
• •Standalone feature: .md/standalone/plan-multi-currency.md

Search Tools for Planning

Use targeted code search to understand impact and find patterns:

For planning, combine these tools to:

• •Map how props/data flow across the feature folders
• •Identify all hook and lib consumers before proposing changes
• •Confirm generated types or API clients already exist before reinventing

How It Works

1. •Exploration: Use Grep for JSX usage, Glob for layout of feature folders
2. •Impact Analysis: Pair ast-grep with Grep to find every hook/lib consumer and cross-feature coupling
3. •Architecture Analysis: Validate layer placement and dependency direction per Feature Architecture rules
4. •Risk Assessment: Check against React/PWA risk categories below
5. •Planning: Create sequential implementation/test steps referencing concrete files
6. •Validation: Final pass against Feature Architecture + React Principles checklist
7. •Output: Write the plan to the correct markdown path with metadata footer

Feature Architecture Validation (MANDATORY)

Every plan MUST validate these points:

Layer Placement

Dependency Direction

components → hooks → lib/services → types
        (never reverse; context providers sit between hooks and components and obey the same direction)

Questions to validate:

• •Do components delegate all logic to hooks/context?
• •Do hooks only depend on lib/services and types (never components)?
• •Do lib/services stay React-agnostic and avoid importing hooks/components?
• •Are shared types referenced from types/ instead of duplicating local definitions?
• •Do context providers expose stable values (memoized) so consumers avoid redundant renders?

React Principles Compliance Checklist

Every plan MUST consider:

Risk Categories (MANDATORY Assessment)

Every plan MUST evaluate these risk categories:

1. Rendering Risks

• •Are we triggering unnecessary rerenders (missing React.memo, unstable deps)?
• •Are expensive computations happening inside render without memoization?
• •Is state lifted to the right component (not global when local suffices)?

2. Hook Rules Risks

• •Any conditional/looped hook usage?
• •Are useEffect dependencies accurate, or will stale closures surface?
• •Are custom hooks hiding rule violations (hook order drift)?

3. State Management Risks

• •Are we prop drilling vs. adding context selectively?
• •Is derived state being stored instead of computed?
• •Could async state updates race (multiple setState relying on stale snapshots)?

4. Data Layer Risks

• •Will IndexedDB/Dexie schema changes require migrations/version bumps?
• •Are queries bounded/paginated?
• •Is error/quota handling (quota exceeded, storage events) defined?

5. Side Effect Risks

• •Do effects/registers cleanup listeners, intervals, observers, and AbortControllers?
• •Are fetches cancelable when components unmount or inputs change?
• •Are service worker messages handled idempotently?

6. Type Safety Risks

• •Any any casts/null assertions hiding runtime risk?
• •Are unions narrow enough to detect impossible states?
• •Are runtime guards needed around external data?

7. PWA/Offline Risks

• •What is the service worker update strategy and cache invalidation plan?
• •How do we reconcile offline data with server truth?
• •Are browser storage limits handled (Safari private browsing, quota)?

Risk Assessment Format in Plan

## Risk Assessment

| Category | Risk Level | Notes |
|----------|------------|-------|
| Rendering | Medium | Virtualized list will rerender without memoizing filters |
| Hook Rules | Low | Custom hooks already wrap effects and pass lint rules |
| State Management | High | Current approach prop-drills 5 levels - introduce context |
| Data Layer | Medium | Dexie schema upgrade required - add migration path |
| Side Effects | Low | useEffect cleans up subscriptions |
| Type Safety | Medium | External API returns `unknown` - add zod parsing |
| PWA/Offline | High | Need cache bust + sync queue conflict policy |

### Mitigations
- Rendering: Add `useMemo` + `React.memo` around `ExpenseGrid`
- State: Create `useExpenseFiltersContext` provider consumed by grid + toolbar
- PWA: Define SW version gating + background sync conflict resolution

Example Workflow

# 1. Create the plan (for issue #42)
/plan Implement offline-first sync queue per the requirements in issue #42

# Agent will:
# - Inspect src/features/expenses_sync/{components,hooks,lib}
# - Search for existing Dexie stores + service worker handlers
# - Check PLAN.md for release constraints + app shell commitments
# - Create detailed plan in .md/issues/42/plan.md

# 2. Review the plan, then execute
npm run lint
npm run build
npm test
npx vitest run src/features/expenses_sync/__tests__/queue.spec.ts

# Standalone plan (no issue)
/plan Add install prompt + manifest polish for SpendiaBot PWA

# Agent will create: .md/standalone/plan-install-prompt.md

When to Use /plan

✅ Good for:

• •Net-new React features (dashboard widgets, offline flows, service worker changes)
• •Large refactors (rewrite to hooks, modularizing feature folders)
• •Architecture shifts (introducing new state stack, virtualization, streaming SSR)
• •When cross-feature impact or shared components are touched
• •When multiple front-end approaches exist and tradeoffs must be explained

❌ Skip for:

• •Copy tweaks or className updates
• •Tiny bug fixes (<10 LOC) with clear diff
• •Styling adjustments already specced elsewhere
• •Simple data binding additions

Markdown Metadata Footer (MANDATORY)

Every plan markdown file MUST end with a metadata footer:

---

**Model**: <your exact model ID, e.g. claude-opus-4-6>
**Persona**: <your persona name, e.g. Prometheus>

Notes

• •The planner creates specifications, not code
• •Plans are concise—typically 1-2 pages focused on sequential steps + validation
• •Plans reference existing React files/hooks/context providers as concrete anchors
• •Follow-up questions can refine or scope down the plan before coding
• •After approval, use /implementation-executor to execute the React plan end-to-end