project-planner

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

1. Read the feature request, user story, or product requirement in full
2. Identify the core objective — what value does this deliver?
3. List explicit inputs (what triggers the feature) and outputs (what the user sees)
4. Note ambiguities or missing details — list them as open questions
5. 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.