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

code

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

code

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

code

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

yaml

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"

yaml

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"