/plan

name: plan
description: "Use this skill when the user needs to turn an idea into a buildable spec, write a project scope, create feature requirements, or define an MVP. Covers quick feature specs (10-15 min) for immediate AI builds and full project scopes (1-2 hours) for planning and contractor estimates."

Scope

Turn ideas into specs that AI tools can execute and stakeholders can evaluate.

When to Use This Skill

• Starting any new feature or product
• Before hiring developers or estimating costs
• When AI keeps building the wrong thing (unclear spec)
• When stakeholders need to review scope and budget

Choose Your Approach

**Quick Feature Spec (10-15 minutes)**

• Use for: Single features, iterations, additions
• Give to: AI tools (Claude Code, Lovable, Replit) to build directly
• See: [QUICK-SPEC.md](QUICK-SPEC.md)

**Full Project Scope (1-2 hours)**

• Use for: New products, major releases, stakeholder review
• Give to: Contractors, team members, budget planning
• See: [PROJECT-SCOPE.md](PROJECT-SCOPE.md)

---

Quick Feature Spec Workflow

Use this checklist and complete each section:

Feature Spec Progress:
- [ ] Write what users will do (2-3 sentences)
- [ ] Show what it looks like (reference, screenshot, or description)
- [ ] Define happy path (3-5 steps)
- [ ] List edge cases (2-4 scenarios)
- [ ] Specify out of scope items
- [ ] Save to docs/specs/YYYY-MM-DD-feature-name.md

Section 1: What Users Will Do

Write 2-3 sentences describing user actions and outcomes.

**Template:**

Users can [ACTION] to [OUTCOME].
When they [DO THIS], they see [WHAT HAPPENS].
If [EDGE CASE], then [WHAT HAPPENS].

**Example:**

Users sign up with email/password, receive confirmation email, and log in to 
see their dashboard. They can reset forgotten passwords via email link.

Section 2: What It Looks Like

Pick ONE:

• **Reference app:** "Login like Linear - minimal, centered, email/password/button"
• **Screenshot/sketch:** Quick mockup or phone photo
• **Description:** "Card 400px wide, 'Welcome' header Inter 24px, two inputs, blue button"

Section 3: Happy Path

List 3-5 steps users take to complete the task.

Section 4: Edge Cases

List 2-4 scenarios where things don't go as planned and what happens.

**Format:**

- **[Scenario]:** [Response shown to user]

Section 5: Out of Scope

Define what you're NOT building to prevent scope creep.

For complete template and examples, see [QUICK-SPEC.md](QUICK-SPEC.md)

---

Full Project Scope Workflow

Use this checklist for comprehensive project planning:

Project Scope Progress:
- [ ] Write introduction (background, in/out of scope)
- [ ] Define user roles
- [ ] List all pages/screens
- [ ] Describe core features
- [ ] Identify integrations
- [ ] Create milestones with hour estimates
- [ ] Document assumptions and open questions
- [ ] Save to docs/specs/YYYY-MM-DD-project-name.md

The 7 Required Sections

1. **Introduction** - Background, in scope, out of scope 2. **User Roles** - Each role's responsibilities 3. **Pages & Screens** - Every page with one-line purpose 4. **Core Features** - Outcome-focused capabilities 5. **Integrations** - External services with complexity/risk notes 6. **Milestones & Tasks** - Phases with hour estimates 7. **Open Questions** - Assumptions and unresolved decisions

For complete template and examples, see [PROJECT-SCOPE.md](PROJECT-SCOPE.md)

---

Using Your Spec With AI Tools

**Claude Code / Cursor:**

Build this feature: [paste Quick Feature Spec]

**Lovable / Replit / Bolt:**

• Paste Quick Feature Spec as initial prompt
• Break complex features into smaller chunks
• Iterate: "Close, but error message should say X not Y"

**Hiring contractors:**

• Send Full Project Scope
• Ask: "What's unclear? What would you change?"
• Get hour estimate and compare to yours

---

Common Mistakes

| Mistake | Fix | |---------|-----| | "Build a dashboard" | Describe what's ON dashboard and what each thing does | | Describing HOW to code it | Describe WHAT it should do | | Forgetting mobile | Add "Works on mobile" to every spec | | Skipping edge cases | Define what happens when things break | | No out-of-scope | Prevents scope creep |

---

When You're Stuck

**"I don't know what I want yet"**

• Use competitor's product for 20 minutes
• Screenshot 3 things you like
• Write: "I want these 3 things, but simpler"

**"AI keeps building the wrong thing"**

• Your spec is vague
• Use templates in QUICK-SPEC.md or PROJECT-SCOPE.md
• Fill in EVERY section

---

After Scoping

**Save as:** `docs/specs/YYYY-MM-DD-feature-name.md`

**Then:**

• Quick Feature Spec → Give directly to AI tool
• Full Project Scope → Review with stakeholders/contractors first

---

Success Looks Like

✅ AI builds it right first time (or very close) ✅ Contractors give realistic estimates without surprises ✅ Edge cases don't surprise you in production ✅ Stakeholders know exactly what they're getting

---

Related Skills

• **translate** — If you're a domain expert, start here to turn your pain into a spec
• **prioritize** — Decide what to build first when you have too many ideas
• **build** — Hand your spec to AI tools and start building
• **validate** — Test demand before investing in a full spec