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:

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:

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:

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.

Implementation Plan Template

Use this template when producing an implementation plan for a feature, enhancement, or change.

---

Objective

<!-- 1-2 sentence summary of what this delivers and why it matters -->

[Feature name]: [Clear description of the value delivered]

Context

<!-- Background information that helps understand the change -->

• Triggered by: [User story / feature request / bug report / tech debt]
• Related work: [Links to related plans, ADRs, or PRs]

Open Questions

<!-- List ambiguities that need resolution before implementation -->

1. [Question 1] 2. [Question 2]

Affected Modules

<!-- Complete module map showing every area of the codebase impacted -->

Change Types: New file, Modify, Delete, Rename Impact: Migration, API change, UI change, Config change, None

Verification

Integration Verification

<!-- End-to-end test or manual smoke test for the complete feature -->

Automated E2E:

[E2E test command, e.g., npx playwright test tests/e2e/feature-name.spec.ts]

Manual Smoke Test: 1. [Step 1: Navigate to...] 2. [Step 2: Perform action...] 3. [Step 3: Verify result...] 4. [Expected outcome]

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

Risks & Unknowns

<!-- Potential issues with likelihood and mitigation -->

Acceptance Criteria

<!-- Observable outcomes that confirm the feature is complete -->

• [ ] [Criterion 1: User can...]
• [ ] [Criterion 2: System responds with...]
• [ ] [Criterion 3: Data persists in...]
• [ ] [Criterion 4: Error case handles...]
• [ ] All tests pass (unit + integration)
• [ ] No regressions in existing functionality
• [ ] Code reviewed and approved

Estimation Summary

Next Step

Run /task-decomposition to read this plan file and break it into atomic implementation tasks with persistent tracking files (task_plan.md, progress.md, findings.md).

Notes

<!-- Any additional context, decisions, or constraints -->

• [Note 1]
• [Note 2]

Risk Assessment Checklist

Use this checklist during Step 5 (Identify Risks and Unknowns) of the planning workflow. Review each category and flag any risks that apply to the current feature.

---

Risk Severity Matrix

Action by severity:

• Critical: Must have mitigation plan before starting. Escalate to tech lead.
• High: Must have mitigation plan. Consider reducing scope.
• Medium: Document mitigation. Monitor during implementation.
• Low: Acknowledge and proceed. Revisit if conditions change.
• Negligible: No action needed.

---

Category 1: Database & Data Migration

• [ ] Schema change requires migration — Does this change add, modify, or remove database columns or tables?
• Risk: Migration failure in production, data loss
• Mitigation: Write and test both upgrade and downgrade migrations. Run dry-run against staging.

• [ ] Data transformation required — Does existing data need to be converted or backfilled?
• Risk: Long migration time, data corruption, downtime
• Mitigation: Write migration as a background job. Test with production-sized dataset.

• [ ] Index changes on large tables — Adding or removing indexes on tables with >100K rows?
• Risk: Lock contention, slow migration, downtime
• Mitigation: Use CREATE INDEX CONCURRENTLY. Plan for off-peak deployment.

• [ ] Foreign key or constraint changes — Adding NOT NULL, UNIQUE, or FK constraints to existing data?
• Risk: Constraint violation on existing data
• Mitigation: Audit existing data first. Add constraint with validation step.

Category 2: API Contract Changes

• [ ] Breaking change to existing endpoint — Does this modify request/response shape for an existing API?
• Risk: Frontend breakage, external consumer breakage
• Mitigation: Version the API or use additive changes only. Coordinate frontend update.

• [ ] New required field in request body — Adding a required field to an existing POST/PUT/PATCH?
• Risk: Existing clients will get 422 errors
• Mitigation: Make the field optional with a default, or version the endpoint.

• [ ] Changed status codes or error format — Modifying HTTP status codes or error response shape?
• Risk: Frontend error handling breaks
• Mitigation: Update frontend error handlers in the same sprint.

• [ ] New authentication or authorization requirement — Adding auth to a previously public endpoint?
• Risk: Existing unauthenticated consumers will get 401/403
• Mitigation: Announce deprecation, add auth gradually with feature flag.

Category 3: Authentication & Authorization

• [ ] Auth flow changes — Modifying login, token generation, session management, or role checks?
• Risk: Users locked out, privilege escalation, security vulnerability
• Mitigation: Thorough testing with multiple user roles. Security review before merge.

• [ ] Permission model changes — Adding or modifying role-based access control?
• Risk: Users gain unintended access or lose existing access
• Mitigation: Audit current permission assignments. Test with each role.

• [ ] Token or session changes — Modifying JWT claims, token lifetime, or session storage?
• Risk: Active sessions invalidated, users forced to re-login
• Mitigation: Support both old and new token formats during transition.

Category 4: Performance

• [ ] N+1 query risk — Does the change introduce a loop that queries the database per iteration?
• Risk: Response time scales linearly with data size
• Mitigation: Use selectinload() or joinedload() for relationships. Profile with realistic data.

• [ ] Large payload risk — Does the endpoint return unbounded data (no pagination)?
• Risk: Memory exhaustion, slow responses
• Mitigation: Add cursor-based pagination. Set reasonable page size defaults.

• [ ] Expensive computation — Does the change introduce CPU-intensive work in the request path?
• Risk: Slow responses, timeout under load
• Mitigation: Move to background task (Celery/BackgroundTasks). Add caching.

• [ ] Frontend bundle size increase — Adding a new large dependency to the frontend?
• Risk: Slower initial page load, poor Core Web Vitals
• Mitigation: Check bundle size impact. Consider lazy loading or lighter alternative.

Category 5: Third-Party Dependencies

• [ ] New dependency added — Installing a new Python or npm package?
• Risk: Supply chain vulnerability, license incompatibility, maintenance risk
• Mitigation: Check download stats, last publish date, license, known vulnerabilities.

• [ ] Dependency version upgrade — Upgrading a major version of an existing dependency?
• Risk: Breaking API changes, incompatibilities with other packages
• Mitigation: Read changelog. Check peer dependency compatibility. Run full test suite.

• [ ] External service integration — Calling a new third-party API (payment, email, storage)?
• Risk: Service unavailability, rate limiting, credential management
• Mitigation: Implement retry logic, circuit breaker, timeout. Store credentials in secrets manager.

Category 6: Frontend State & UI

• [ ] Shared state modification — Changing React Context, TanStack Query cache, or global store?
• Risk: Unintended re-renders, stale data, broken components elsewhere
• Mitigation: Map all consumers of the shared state. Test each consumer.

• [ ] Component tree restructuring — Moving, renaming, or reorganizing component hierarchy?
• Risk: Broken imports, lost CSS scoping, context provider issues
• Mitigation: Update all import paths. Test routing and layout at each level.

• [ ] Form validation changes — Modifying form validation rules or error display?
• Risk: Users unable to submit valid data, or invalid data accepted
• Mitigation: Test with edge case inputs. Match backend validation rules.

• [ ] Accessibility impact — Does the UI change affect keyboard navigation, screen readers, or color contrast?
• Risk: WCAG violation, inaccessible to users with disabilities
• Mitigation: Run axe-core scan. Test with keyboard only. Check color contrast ratios.

Category 7: Deployment & Infrastructure

• [ ] Environment variable changes — Adding or modifying environment variables?
• Risk: Deployment fails if env vars not set in staging/production
• Mitigation: Update deployment configuration. Document all new env vars.

• [ ] Docker changes — Modifying Dockerfile, docker-compose, or build process?
• Risk: Build failure, image size regression, security vulnerability
• Mitigation: Test build locally. Check image size before/after. Scan with Trivy.

• [ ] CI/CD pipeline changes — Modifying GitHub Actions workflows or deployment scripts?
• Risk: Pipeline failure, skipped tests, broken deployment
• Mitigation: Test workflow changes in a branch. Verify all jobs complete.

Category 8: Security

• [ ] User input handling — Does the change process user-provided data (form input, file upload, URL params)?
• Risk: Injection attacks (SQL, XSS, command injection)
• Mitigation: Use parameterized queries, Pydantic validation, output escaping.

• [ ] Secrets or credentials — Does the change involve API keys, tokens, or passwords?
• Risk: Secrets leaked in code, logs, or error messages
• Mitigation: Use environment variables. Never log secrets. Review for accidental exposure.

• [ ] File system access — Does the change read or write files based on user input?
• Risk: Path traversal, arbitrary file read/write
• Mitigation: Validate and sanitize file paths. Use allowlists for permitted directories.

---

Quick Risk Summary Template

Use this table in your implementation plan: