scope

# 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