Estimation Skill

Core Principle: Estimate before committing.

When to Invoke

Before starting a large or complex task
When user asks about complexity or scope
Before providing time commitments
When decomposing tasks for orchestration
When uncertain about task scope

Complexity Factors

Assess each factor to determine overall complexity:

Factor	Weight	Questions to Ask
Files to modify	High	How many files? How spread across codebase?
New patterns required	High	Does this require patterns not in codebase?
External dependencies	High	New APIs, services, or integrations?
Test coverage needed	Medium	Unit, integration, e2e tests required?
Documentation updates	Low	README, API docs, comments needed?
Breaking changes	High	Will this break existing functionality?
Unknown territory	High	Are you familiar with this code area?

Complexity Scoring

LOW: 1-2 files, existing patterns, no new dependencies
MEDIUM: 3-5 files, minor new patterns, limited dependencies
HIGH: 6+ files, new patterns, new dependencies, cross-cutting
UNKNOWN: Cannot assess without more exploration

Estimation Protocol

Step 1: Scope Analysis

1. What is the task asking for?
2. What files will likely need changes?
3. What patterns exist for similar features?
4. What dependencies are involved?
5. What testing is required?

Step 2: Factor Assessment

For each complexity factor:

Score as: none (0), low (1), medium (2), high (3)
Note specific concerns

Step 3: Risk Identification

Risks to identify:
- Areas of uncertainty
- Potential blockers
- Dependencies on external factors
- Technical debt implications

Step 4: Output Estimation

Use the template below.

Output Template

estimation:
  timestamp: [ISO 8601]
  task: |
    [Task description]

  scope:
    files_affected:
      known:
        - [file1.ts - reason]
        - [file2.ts - reason]
      likely:
        - [file3.ts - reason]
      unknown: [count or "cannot determine"]

    changes_required:
      - type: [new_file | modification | deletion]
        description: [what change]
      - type: [type]
        description: [what change]

  complexity:
    overall: [low | medium | high | unknown]
    factors:
      files_to_modify: [0-3]
      new_patterns: [0-3]
      external_dependencies: [0-3]
      test_coverage: [0-3]
      documentation: [0-3]
      breaking_changes: [0-3]
      unknown_territory: [0-3]
    total_score: [sum]

  risks:
    - risk: "[Risk description]"
      likelihood: [low | medium | high]
      impact: [low | medium | high]
      mitigation: "[How to address]"

  unknowns:
    - "[What you couldn't determine]"
    - "[What needs clarification]"

  recommendations:
    approach: |
      [Recommended approach]
    alternatives:
      - "[Alternative approach 1]"
    next_steps:
      - "[First step]"
      - "[Second step]"

  confidence: 0.0
  evidence:
    - "[What you examined]"

Complexity Thresholds

Low Complexity (Score 0-5)

Can likely be completed in single session
Straightforward implementation
Well-understood patterns

Medium Complexity (Score 6-10)

May require multiple sessions
Some exploration needed
Some new patterns required

High Complexity (Score 11+)

Definitely requires planning
Significant exploration needed
Consider breaking into phases

Unknown Complexity

Cannot assess without more information
Recommend context-gathering first
Ask user clarifying questions

Rules

[!CRITICAL] NEVER estimate without understanding scope. ALWAYS include unknowns.

Do

List specific files you expect to change
Identify risks and unknowns
Provide confidence level
Recommend next steps

Don't

Give point estimates (use ranges/categories)
Promise delivery timelines
Understate complexity to seem helpful
Skip the unknown factors

Integration with Other Skills

After Estimation	Invoke
Need more context	→ `context-gathering` skill
Ready to plan implementation	→ `writing-plans` skill
Ready to execute	→ `orchestration` skill

Chaining Rules

IF unknowns are significant THEN invoke context-gathering first
IF complexity is high THEN recommend phased approach
AFTER estimation accepted THEN proceed to writing-plans

Example

Task: "Add user authentication to the API"

estimation:
  timestamp: "2024-01-15T10:00:00Z"
  task: |
    Add user authentication to the existing Express API

  scope:
    files_affected:
      known:
        - src/routes/auth.ts - new route file
        - src/middleware/auth.ts - new middleware
        - src/models/user.ts - user model changes
      likely:
        - src/routes/index.ts - route registration
        - tests/auth.test.ts - new tests
      unknown: 2-3 additional files for utilities

    changes_required:
      - type: new_file
        description: Authentication routes (login, register, logout)
      - type: new_file
        description: Auth middleware for protected routes
      - type: modification
        description: Add auth to existing protected routes

  complexity:
    overall: medium
    factors:
      files_to_modify: 2
      new_patterns: 2
      external_dependencies: 2
      test_coverage: 2
      documentation: 1
      breaking_changes: 1
      unknown_territory: 1
    total_score: 11

  risks:
    - risk: "Password hashing library choice"
      likelihood: low
      impact: medium
      mitigation: "Use bcrypt, well-established"
    - risk: "JWT secret management"
      likelihood: medium
      impact: high
      mitigation: "Environment variable, document required setup"

  unknowns:
    - "Which routes should be protected?"
    - "OAuth integration needed?"
    - "Session vs JWT preference?"

  recommendations:
    approach: |
      Implement JWT-based auth with bcrypt password hashing.
      Start with login/register, add middleware, then protect routes.
    alternatives:
      - "Session-based auth with express-session"
      - "OAuth with passport.js"
    next_steps:
      - "Clarify auth requirements with user"
      - "Create detailed plan with writing-plans skill"

  confidence: 0.7
  evidence:
    - "Reviewed existing routes structure"
    - "Checked package.json for auth libraries"
    - "Examined similar features in codebase"