scope-check

What this skill does

# Scope Check Skill

When checking scope, follow this structured process. The goal is to catch the things that make a "2-week project" turn into a "3-month nightmare" — before the team commits.

**IMPORTANT**: Always save the output as a markdown file in the `project-decisions/` directory at the project root. Create the directory if it doesn't exist.

## 0. Output Setup
```bash
# Create project-decisions directory if it doesn't exist
mkdir -p project-decisions

# File will be saved as:
# project-decisions/YYYY-MM-DD-scope-[kebab-case-topic].md
```

## 1. Parse the Spec / Proposal

### Extract Key Information

From the spec, ticket, PRD, or conversation, identify:

- **What's being built?** — the core feature or change
- **Who is it for?** — target users/personas
- **What's the stated timeline?** — any deadlines or sprint targets
- **What's the stated estimate?** — story points, days, t-shirt size
- **Who wrote this?** — product, engineering, design, stakeholder?
- **What stage is this?** — idea, spec, approved, in-progress?

### Scan the Codebase for Context
```bash
# Check how the current system works in the affected area
grep -rn "[feature-keyword]" --include="*.ts" --include="*.js" --include="*.py" src/ app/ 2>/dev/null | grep -v "node_modules\|\.git\|test\|spec" | head -30

# Check existing models/schemas in the area
grep -rn "interface\|type\|class\|model\|schema" --include="*.ts" --include="*.js" --include="*.py" src/ 2>/dev/null | grep -i "[keyword]"

# Check existing API endpoints in the area
grep -rn "router\.\|app\.\(get\|post\|put\|delete\)\|@app\.route\|@GetMapping" --include="*.ts" --include="*.js" --include="*.py" --include="*.java" src/ 2>/dev/null | grep -i "[keyword]"

# Check existing tests in the area
find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" | xargs grep -l "[keyword]" 2>/dev/null

# Check for similar past features (how long did they take?)
git log --oneline --all --grep="[keyword]" | head -10

# Check for related TODOs/FIXMEs
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.js" --include="*.py" src/ 2>/dev/null | grep -i "[keyword]"

# Check for tech debt in the area
wc -l $(grep -rln "[keyword]" --include="*.ts" --include="*.js" --include="*.py" src/ 2>/dev/null | head -10) 2>/dev/null
```

## 2. Scope Creep Red Flags

Scan the spec for language and patterns that signal hidden complexity:

### 🔴 Critical Red Flags — Almost Certainly Bigger Than It Sounds

#### Vague Requirements
```
Flag these phrases:
- "Simple" / "Just" / "Quickly" / "Easy"
  → The word "just" in a spec is the #1 predictor of scope creep
  → "Just add a button that..." hides all the backend logic

- "Similar to [complex product]"
  → "Like Slack but for X" is 5 years of engineering
  → Always ask: which specific feature of that product?

- "And everything that goes with it"
  → Unbounded scope — what does "everything" mean?

- "Should work like it does now, but also..."
  → Backward compatibility + new behavior = double the work

- "Users should be able to..."  (without specifying which users)
  → All users? Admins? Free tier? Paid? Each is different scope

- "Support for [open-ended list]"
  → "Support for multiple payment providers" = how many? Which ones? Each is a separate integration
```

#### Missing Edge Cases
```
Flag when the spec doesn't mention:
- What happens on error?
- What happens with empty/null data?
- What happens with very large data sets?
- What happens when the user is offline?
- What happens on timeout?
- What happens concurrently?
- What happens when the user goes back/refreshes?
- What about existing data? (migration needed?)
- What about internationalization?
- What about accessibility?
- What about mobile/responsive?
```

#### Hidden "Icebergs"
```
The spec says:              But it actually requires:
─────────────────────────   ────────────────────────────────────
"Add search"                Full-text search engine, indexing,
                            ranking, filters, pagination, 
                            highlighting, typo tolerance

"Add notifications"         Notification service, delivery 
                            channels (email, SMS, push),
                            preferences, templates, scheduling,
                            unsubscribe, rate limiting

"Add user roles"            Permission system, role management UI,
                            migration of existing users, audit 
                            trail, testing every endpoint

"Add file upload"           Storage service, virus scanning,
                            file type validation, size limits,
                            thumbnails, CDN, cleanup/deletion

"Add payments"              Payment provider integration, PCI
                            compliance, webhooks, retry logic,
                            refunds, invoicing, tax calculation

"Add real-time updates"     WebSocket infrastructure, connection
                            management, reconnection, state sync,
                            horizontal scaling with pub/sub

"Add an admin panel"        CRUD for every entity, audit logging,
                            role-based access, bulk operations,
                            export, dashboard, search/filter

"Add multi-tenancy"         Data isolation, tenant-aware queries
                            everywhere, tenant management, billing
                            per tenant, cross-tenant prevention

"Add SSO/SAML"              SAML/OIDC integration, identity 
                            provider config UI, JIT provisioning,
                            session management, logout propagation

"Make it work offline"      Local database, sync engine, conflict
                            resolution, queue for pending actions,
                            retry logic, cache invalidation
```

### 🟡 Warning Flags — Likely Bigger Than Estimated

#### Underspecified Behavior
```
Flag when the spec says:
- "The usual flow" → Which flow? Document it
- "Handle errors appropriately" → What specifically? Show user? Retry? Log?
- "Responsive design" → Mobile? Tablet? Which breakpoints? Different layouts?
- "Good performance" → What's the target? <200ms? <1s? Under what load?
- "Secure" → Against what? XSS? CSRF? Injection? Auth bypass?
- "Nice UI" → Where are the mocks? No mocks = design work not included
- "Integration with X" → Which API? Which version? Is there documentation?
- "Export functionality" → What format? CSV? PDF? Excel? All of them?
- "Audit trail" → What events? How long to retain? Who can view?
- "Configurable" → By whom? Admin UI? Config file? Environment variable?
```

#### Cross-Cutting Concerns Not Mentioned
```
Flag if the spec doesn't address:
- Authentication → Who can access this?
- Authorization → What permissions are needed?
- Logging → What should be logged for debugging?
- Monitoring → What alerts should fire if this fails?
- Rate limiting → Can this be abused?
- Caching → Does this need caching for performance?
- Data validation → What input validation is needed?
- Error handling → What's the error UX?
- Migration → What happens to existing data/users?
- Documentation → API docs? User docs? Internal docs?
- Testing strategy → Unit? Integration? E2E? Manual?
- Deployment plan → Feature flag? Gradual rollout?
- Rollback plan → What if this needs to be reverted?
```

#### Dependencies Not Called Out
```
Flag when the feature requires:
- Design work that hasn't started
- API from another team that doesn't exist yet
- Third-party service evaluation or contract
- Infrastructure provisioning (new database, queue, etc.)
- Data migration or backfill
- Legal/compliance review
- External partner coordination
- New environment variables or secrets
- CI/CD pipeline changes
```

### 🟢 Minor Flags — Worth Noting
```
- Copy/text not finalized (changes = rework)
- No success metrics defined (how do we know it's working?)
- No acceptance criteria (how do we know it's done?)
- No out-of-scope section