Project Planner

When to Use

Activate this skill when:

Breaking down a feature request or user story into an implementation plan
Sprint planning or backlog refinement for a Python/React project
Designing a new module, service, or feature area
Estimating the overall complexity of a proposed change
Identifying file-level impact before starting implementation
Mapping the impact of a change across backend and frontend layers

Do NOT use this skill for:

Architecture decisions or technology trade-offs (use system-architecture)
Writing implementation code (use python-backend-expert or react-frontend-expert)
API contract design (use api-design-patterns)
Decomposing into atomic implementation tasks (use task-decomposition)

Instructions

Planning Workflow

Follow this 4-step workflow for every planning request:

Step 1: Analyze the Requirement

Read the feature request, user story, or product requirement in full
Identify the core objective — what value does this deliver?
List explicit inputs (what triggers the feature) and outputs (what the user sees)
Note ambiguities or missing details — list them as open questions
Determine if this is a new feature, enhancement, bug fix, or refactoring

Step 2: Map Affected Modules

Scan the project and identify every file or module area affected by the change:

Backend (FastAPI):

routes/ — New or modified endpoint handlers
services/ — Business logic changes
repositories/ — Data access layer changes
models/ — SQLAlchemy model changes (triggers migration)
schemas/ — Pydantic request/response schema changes
core/ — Configuration, security, or middleware changes
migrations/ — Alembic migration files

Frontend (React/TypeScript):

pages/ — New or modified page components
components/ — Shared UI component changes
hooks/ — Custom hook changes or additions
services/ — API client changes (TanStack Query keys, mutations)
types/ — Shared TypeScript type definitions
utils/ — Utility function changes

Shared / Cross-cutting:

types/ or shared/ — Types shared between backend and frontend
.env / config — Environment variable changes
tests/ — Test files for each changed module

Present the module map as a table:

| Layer    | Module           | Change Type       | Impact    |
|----------|-----------------|-------------------|-----------|
| Backend  | models/user.py  | Add field         | Migration |
| Backend  | schemas/user.py | Add response field| API change|
| Frontend | hooks/useUser.ts| Update query      | UI change |

Step 3: Define Verification Criteria

Define how the completed feature will be verified:

Integration verification:

End-to-end test scenario describing the complete user flow
Manual smoke test steps if automated E2E is not available

Regression check:

Existing tests still pass: pytest -x && npm test
No type errors: mypy src/ && npx tsc --noEmit
No lint issues: ruff check src/ && npm run lint

Step 4: Identify Risks and Unknowns

Flag potential issues using the categories below. For each risk:

Risk: Description of what could go wrong
Likelihood: Low / Medium / High
Impact: Low / Medium / High
Mitigation: How to reduce or eliminate the risk

See references/risk-assessment-checklist.md for the complete risk category list.

Output Format

Write the plan to a file at the project root: plan.md (or plan-<feature-name>.md if multiple plans exist). Use references/plan-template.md as the template.

The file must contain:

# Implementation Plan: [Feature Name]

## Objective
[1-2 sentence summary of what this delivers]

## Context
- Triggered by: [user story / feature request / bug report]
- Related work: [links to related plans, ADRs, or PRs]

## Open Questions
[List ambiguities that need resolution before implementation]

## Affected Modules
[Module map table from Step 2]

## Verification
[Integration verification from Step 3]

## Risks & Unknowns
[Risk table from Step 4]

## Acceptance Criteria
[Bullet list of observable outcomes that confirm the feature works]

## Estimation Summary
[Overall complexity estimate — see table below]

Always write the plan to a file. This enables /task-decomposition to read it as input. After writing, tell the user: "Plan written to plan.md. Run /task-decomposition to break it into atomic tasks."

Estimation Summary

Estimate overall feature complexity using this table:

Metric	Value
Total backend modules affected	[N]
Total frontend modules affected	[N]
Migration required	Yes / No
API changes	Yes / No (new endpoints / modified contracts)
Overall complexity	trivial / small / medium / large

Complexity guidelines:

Trivial: 1-2 modules, no migration, <50 lines
Small: 2-4 modules, no migration, <200 lines
Medium: 4-8 modules, migration possible, <500 lines
Large: 8+ modules, migration likely, 500+ lines

Examples

Example: Plan "Add User Profile Picture Upload"

Objective: Allow users to upload and display a profile picture.

Affected Modules:

Layer	Module	Change Type	Impact
Backend	models/user.py	Add avatar_url	Migration
Backend	schemas/user.py	Add field	API contract
Backend	services/upload.py	New service	New file
Backend	routes/users.py	Add endpoint	API change
Frontend	components/AvatarUpload	New component	UI change
Frontend	hooks/useUploadAvatar.ts	New hook	Data fetch
Frontend	pages/ProfilePage.tsx	Integrate	UI change

Verification:

Upload an image via the profile page, verify it displays
Upload an oversized file, verify rejection with error message
Regression: pytest -x && npm test

Risks:

File size limits need validation (server + client) — Medium likelihood — Add early validation
S3 permissions may need configuration — Low likelihood — Test with local storage first

Acceptance Criteria:

User can upload a profile picture from the profile page
Uploaded image displays as the user's avatar across the app
Files over 5MB are rejected with a clear error message
Non-image files are rejected
All existing tests pass

Estimation Summary:

Metric	Value
Backend modules affected	4
Frontend modules affected	3
Migration required	Yes
API changes	Yes (new upload endpoint)
Overall complexity	medium

Output: Written to plan.md. Run /task-decomposition to break it into atomic tasks.

Edge Cases

Cross-cutting changes (auth middleware, error handling, logging): These affect many modules. Flag for architecture review before planning. Consider whether the change should be its own plan.
Database migrations with data transformation: Flag as a risk. Note that migration testing (upgrade + rollback) is needed. Task-decomposition will create a dedicated migration task.
Frontend state cascades: When modifying shared state (React Context, TanStack Query cache), map the component tree to identify all consumers in the module map.
API breaking changes: If modifying an existing endpoint's contract, check for frontend consumers first. Consider API versioning if external consumers exist. Note in the plan that frontend updates must be coordinated.
Feature flags: For large features spanning multiple sprints, note in the plan that a feature flag is needed. Task-decomposition will handle the implementation ordering.
Third-party dependency updates: If the feature requires a new package, list it in the plan's affected modules. Note potential peer dependency conflicts as a risk.

project-planner