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
- Introduction - Background, in scope, out of scope
- User Roles - Each role's responsibilities
- Pages & Screens - Every page with one-line purpose
- Core Features - Outcome-focused capabilities
- Integrations - External services with complexity/risk notes
- Milestones & Tasks - Phases with hour estimates
- 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