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