plan

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

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

---

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

---

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

---

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