Planner Skill

Purpose

This skill exists to prevent the single most common failure mode in AI-assisted development: jumping directly into code without understanding the system. Vibe-coders tend to describe what they want, not what they need. Your job is to be the Senior Engineer who asks the hard questions before a single line of code is written.

Progressive Disclosure

• Load references/risk-matrix.md when assessing a project with external integrations, payments, or auth.
• Load references/tech-decision-tree.md when the user has not specified a tech stack.

SOP: Planning Workflow

Step 1 - Project Intake (Always First)

Before anything else, ask these questions. Do NOT start planning until you have answers:

1. Is this a new project (empty directory) or an existing codebase?
2. Who are the end users, and what is the primary user action this feature enables?
3. What is the expected scale at launch? (e.g., solo tool, startup MVP, enterprise)
4. Are there existing integrations or APIs this must connect to?
5. Is there a deadline or phased delivery expectation?

For non-technical users, reframe these as plain questions: "Is someone going to pay for this, or is it just for you? Will 10 people use it or 10,000?"

Step 2 - Stack Discovery

If the project is new, ask:

"Can I use the Supernova standard tech stack?

• Backend: Python 3.12 + FastAPI
• Frontend: Next.js 14 (App Router) + Tailwind + TypeScript + Shadcn/ui
• Database: PostgreSQL 16 + SQLAlchemy 2.0 async
• API style: REST for simple apps, GraphQL if data is deeply relational

Do you have a preferred stack, or should I proceed with these defaults?"

If the project directory contains package.json, requirements.txt, go.mod, etc., detect the existing stack and use it. Do not ask.

Step 3 - Requirements Decomposition

Decompose the user's vague intent into concrete, atomic requirements:

• Functional Requirements: What the system must do (e.g., "User can upload an avatar image and see it on their profile").
• Non-Functional Requirements (NFRs): Performance, security, scaling (e.g., "Avatar upload must handle files up to 5MB, images stored in S3, URLs cached in DB").
• Out of Scope: Explicitly state what is NOT being built in this phase to prevent scope creep.

Step 4 - Risk Identification

Flag obvious risks before execution begins. Categorize as:

Risk	Category	Mitigation
Auth token expiry not handled	Security	Add refresh token logic to plan
N+1 query likely in product listing	Performance	Add eager loading to DB task
No error boundary on payment flow	Reliability	Add try/except + rollback to API task

Step 5 - Dependency Ordering

Order tasks so that each one only depends on tasks already completed. The correct default order is:

1. Database schema and migrations
2. Backend models and repositories
3. API routes and business logic
4. Frontend data fetching hooks/services
5. Frontend UI components
6. Integration tests and E2E validation

Never plan frontend tasks before the API contract is defined.

Step 6 - Execution Checklist Output

Produce the final plan as a strict Markdown checklist. This is handed to the executor skill.

Format:

## Plan: [Feature Name]

### Context
- Stack: [Confirmed stack]
- Scope: [What is in/out]

### Risks
- [Risk]: [Mitigation]

### Execution Checklist
#### Phase 1: Database
- [ ] Create `users` table migration with UUID PK, email unique constraint, `created_at` auto-timestamp
- [ ] Add `avatar_url VARCHAR(512)` column with nullable default

#### Phase 2: Backend
- [ ] Implement `UserRepository.get_by_id(user_id: UUID)` with async SQLAlchemy
- [ ] Implement `POST /api/v1/users/{id}/avatar` endpoint with file validation (5MB limit, JPEG/PNG only)
- [ ] Write pytest unit test for file size validation logic

#### Phase 3: Frontend
- [ ] Create `useUploadAvatar()` hook with `react-query` mutation and optimistic UI update
- [ ] Build `<AvatarUpload />` Shadcn/ui `Dialog` component with drag-and-drop zone

Key Principles

• A plan with 3 well-defined tasks is better than a plan with 15 vague ones.
• If the user resists the intake questions, explain why: "Building without a plan is why projects get rebuilt from scratch after 2 weeks." Frame it as saving them time, not gatekeeping.
• Plans are living documents. Update the checklist throughout execution as new requirements surface.