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"