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

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