estimate

What this skill does

# Estimate Skill

When estimating work, follow this structured process. Good estimates are ranges, not single numbers. They account for complexity, risk, unknowns, and the reality that things always take longer than expected.

## 1. Understand What's Being Estimated

Before estimating, clarify the scope:

### Gather Requirements
- **What exactly needs to be built/changed?** — Get specific, not vague
- **What's the expected outcome?** — How will we know it's done?
- **What's explicitly out of scope?** — Prevent scope creep
- **Who is this for?** — End users, internal team, API consumers?
- **Are there design mocks?** — UI work without mocks adds uncertainty
- **Are there dependencies on other teams/services?** — External dependencies add risk

### Analyze the Codebase
```bash
# Find the files that would need to change
grep -rn "[relevant-keyword]" --include="*.ts" --include="*.js" --include="*.py" src/ 2>/dev/null | head -20

# Check complexity of affected area
wc -l [target-files]

# Check how many files import/depend on the affected code
grep -rn "import.*from.*[module]" --include="*.ts" --include="*.js" src/ 2>/dev/null | wc -l

# Check test coverage of affected area
find . -name "*[module]*test*" -o -name "*[module]*spec*" 2>/dev/null

# Check recent change frequency (hot spots = more risk)
git log --oneline -20 -- [target-path]

# Check how many people have worked on this area
git log --format='%aN' -- [target-path] | sort | uniq -c | sort -rn

# Check for existing TODOs/FIXMEs in the area
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.js" --include="*.py" [target-path] 2>/dev/null
```

## 2. Complexity Analysis

### Break Down the Work

Decompose every task into concrete subtasks:
```
Example: "Add OAuth2 login with Google"

Subtasks:
1. Research Google OAuth2 API and decide on library          [spike]
2. Create OAuth config and environment variables              [small]
3. Implement OAuth callback route and token exchange          [medium]
4. Create/update user record from OAuth profile               [medium]
5. Handle account linking (OAuth + existing email account)    [large]
6. Add OAuth login button to frontend                         [small]
7. Handle OAuth error states and edge cases                   [medium]
8. Write unit tests for OAuth service                         [medium]
9. Write integration tests for OAuth flow                     [medium]
10. Update documentation and environment setup guide          [small]
11. Test in staging with real Google credentials              [small]
12. Security review of token handling                         [small]
```

### Complexity Factors

Rate each factor on a scale of 1-5:

| Factor | 1 (Low) | 3 (Medium) | 5 (High) |
|--------|---------|------------|----------|
| **Code changes** | Single file, < 50 lines | 3-5 files, ~200 lines | 10+ files, 500+ lines |
| **Logic complexity** | Simple CRUD, straightforward | Conditional logic, state management | Complex algorithms, concurrency |
| **Dependencies** | No external dependencies | Uses existing libraries/APIs | New integrations, cross-team coordination |
| **Data changes** | No schema changes | New columns/indexes | New tables, data migration, backfill |
| **Testing effort** | Easy to test, few cases | Multiple scenarios, some mocking | Complex setup, E2E, hard to reproduce states |
| **Risk** | Well-understood area, safe change | Some unknowns, moderate impact | Touching critical path, payment/auth/data |
| **Frontend work** | No UI changes | Minor UI updates | New pages/flows, responsive, accessibility |
| **Domain knowledge** | Team has done similar work | Some research needed | New territory for the team |
| **Review/approval** | Standard PR review | Security review needed | Architecture review, stakeholder sign-off |
| **Deployment** | Normal deploy, no special steps | Feature flag, migration | Coordinated deploy, downtime window |

**Complexity Score** = Average of all factors
- **1.0 - 2.0** → Simple
- **2.1 - 3.0** → Medium
- **3.1 - 4.0** → Complex
- **4.1 - 5.0** → Very Complex

## 3. Estimation Methods

### Method A: T-Shirt Sizing

Quick, relative sizing — best for backlog grooming and sprint planning:

| Size | Description | Typical Duration | Story Points |
|------|-------------|-----------------|-------------|
| **XS** | Config change, copy update, one-liner fix | < 2 hours | 1 |
| **S** | Simple bug fix, small feature, well-defined scope | 2-4 hours | 2 |
| **M** | Feature with a few moving parts, some unknowns | 1-2 days | 3-5 |
| **L** | Multi-component feature, new integration, DB changes | 3-5 days | 8 |
| **XL** | Large feature spanning multiple systems, significant unknowns | 1-2 weeks | 13 |
| **XXL** | Epic-level work, needs decomposition before estimating | 2+ weeks | 21+ |

**Rule**: If it's XL or larger, break it into smaller tickets before estimating.

### Method B: Time Range Estimate

Provide optimistic, likely, and pessimistic estimates:
```
Estimate: Add OAuth2 Login with Google

Best case (everything goes smoothly):     3 days
Most likely (normal development pace):    5 days
Worst case (unexpected complications):    8 days

Recommended estimate:                     5 days
Buffer for unknowns (20%):               +1 day
Total with buffer:                        6 days
```

**Formula**: `Expected = (Best + 4×Likely + Worst) / 6`

This is the PERT estimation technique — it weights the most likely scenario while accounting for extremes.

### Method C: Story Points (Fibonacci)

Relative sizing using Fibonacci sequence: 1, 2, 3, 5, 8, 13, 21
```
Reference stories (calibrate with team):

1 point  → Fix a typo in the UI
2 points → Add a new field to an existing form
3 points → Create a new API endpoint with validation
5 points → Implement a new feature with frontend + backend + tests
8 points → New integration with external service + error handling
13 points → Large feature with DB schema changes + migration + multiple APIs
21 points → Epic-level, needs decomposition
```

**Rule**: If you can't agree on 5 vs 8, go with 8. Estimates should err on the side of caution.

### Method D: Task-Based Estimate

Most accurate for known work — sum up individual task estimates:
```
Task Breakdown: Add OAuth2 Login with Google

| # | Task | Estimate | Confidence |
|---|------|----------|-----------|
| 1 | Research & library selection | 2h | High |
| 2 | OAuth config & env vars | 1h | High |
| 3 | OAuth callback route | 3h | Medium |
| 4 | User record creation/linking | 4h | Medium |
| 5 | Account linking edge cases | 4h | Low |
| 6 | Frontend login button | 2h | High |
| 7 | Error handling | 3h | Medium |
| 8 | Unit tests | 3h | High |
| 9 | Integration tests | 4h | Medium |
| 10 | Documentation | 1h | High |
| 11 | Staging testing | 2h | Medium |
| 12 | Security review | 1h | High |
|---|------|----------|-----------|
| | **Subtotal** | **30h** | |
| | **Buffer (25% for medium/low confidence)** | **+8h** | |
| | **Total** | **38h (~5 days)** | |
```

## 4. Risk Assessment

### Identify Risks That Inflate Estimates

| Risk | Impact on Estimate | Mitigation |
|------|-------------------|------------|
| **First time doing this** | +50-100% | Do a time-boxed spike first |
| **Unclear requirements** | +30-50% | Clarify before estimating |
| **External API dependency** | +25-50% | Build with mock first, integrate later |
| **Cross-team coordination** | +25-50% | Align schedules early, identify blockers |
| **Database migration on large table** | +25% | Test migration time on production-size data |
| **Touching critical path** (auth, payments) | +25% | Extra testing, staged rollout |
| **No existing tests** | +30% | Write characterization tests first |
| **Legacy code / tech debt** | +25-50% | Budget time for understanding + cleanup |
| **Designer not available** | +25% | Use existing patterns, get async feedback |
| **New technology/library** | +30-50% | Prototype first, add learning time |
| **Regulatory/compliance req