Estimate Stories Skill

Purpose

Estimate story points for user stories using a structured, evidence-based formula: Story Points = (Complexity × Effort) + Risk

This provides consistent estimations that help with sprint planning, velocity tracking, and story comparison.

Core Principle: Estimation is not guessing—it's structured analysis of complexity, effort, and risk based on acceptance criteria and technical context.

Prerequisites

• Story file exists in .claude/stories/ directory

• Story has clear acceptance criteria

• Understanding of project tech stack

• Access to historical velocity data (optional)

Workflow

1. Load Story Context

Read story file to understand:

• User story narrative (As a... I want... So that...)

• Acceptance criteria (what needs to be implemented)

• Dependencies and technical notes

• Current priority level

Load project context:

• Team velocity baseline (from .claude/config.yaml )

• Tech stack and known patterns

• Historical estimation data (if available)

Example story:

User Story: As a new user, I want to create an account with email/password

Acceptance Criteria:

• AC-1: User can enter email and password on signup form
• AC-2: Email validated with Zod
• AC-3: Password hashed with bcrypt
• AC-4: Duplicate emails rejected with 409
• AC-5: Success returns JWT token
• AC-6: User record saved to PostgreSQL

2. Analyze Complexity (1-5 Scale)

Complexity measures technical difficulty and cognitive load (NOT time/effort).

Quick Guide:

• 1 (Trivial): Single file, copy-paste from existing, no edge cases

• 2 (Simple): 2-3 files, existing patterns, minimal edge cases

• 3 (Moderate): 4-6 files, may need new library, multiple edge cases

• 4 (Complex): 7-12 files, multiple patterns, many error paths

• 5 (Very Complex): 12+ files, new architecture, extensive edge cases

Consider:

• Number of integration points (APIs, databases, services)

• Error handling paths required

• State management complexity

• Data transformation complexity

For example story:

Complexity: 3 (Moderate)

• 6 files affected (form, validation, controller, service, model, tests)
• Multiple integration points (DB, JWT, bcrypt)
• Several error paths (validation, duplicates, DB errors)
• Moderate state management

See: references/complexity-scale.md for detailed scale with examples

3. Analyze Effort (1-5 Scale)

Effort measures the volume of work regardless of difficulty.

Quick Guide:

• 1 (Minimal): <1 hour, <50 LOC, 2-3 tests

• 2 (Small): 1-2 hours, 50-150 LOC, 4-6 tests

• 3 (Medium): 3-4 hours, 150-300 LOC, 7-10 tests

• 4 (Large): 5-6 hours, 300-500 LOC, 11-15 tests

• 5 (Very Large): >6 hours, >500 LOC, 15+ tests

Consider:

• Number of acceptance criteria (more AC = more work)

• Lines of code to write

• Number of tests required

• Documentation needs

For example story:

Effort: 3 (Medium)

• 6 acceptance criteria
• ~250 LOC (controller, service, validation, model)
• ~10 tests (unit + integration)
• 3-4 hours estimated work

See: references/effort-scale.md for detailed scale with examples

4. Analyze Risk (0-3 Adjustment)

Risk is an adjustment factor for unknowns and potential issues.

Quick Guide:

• 0: No significant risks

• +1: Minor risks (unfamiliar library, some unknowns)

• +2: Moderate risks (new pattern, integration uncertainty)

• +3: High risks (new architecture, external dependencies, R&D needed)

Consider:

• Team familiarity with required tech

• External dependencies (third-party APIs)

• Requirements clarity (vague requirements = higher risk)

• Performance/security concerns

For example story:

Risk: +1

• Team familiar with all tech (Zod, bcrypt, JWT, PostgreSQL)
• Requirements clear and testable
• Minor risk: ensuring proper bcrypt cost and JWT security

See: references/risk-factors.md for detailed risk analysis

5. Calculate Story Points

Formula: Story Points = (Complexity × Effort) + Risk

For example story:

Complexity: 3 Effort: 3 Risk: +1

Story Points = (3 × 3) + 1 = 10 points

Story Point Scale Interpretation:

• 1-2 points: Trivial, can complete in < 1 hour

• 3-5 points: Small, can complete in 1-3 hours

• 6-10 points: Medium, can complete in half day

• 11-15 points: Large, can complete in 1 day

• 16-20 points: Very large, consider splitting

• 21+ points: Too large, MUST split into smaller stories

If story > 13 points: Consider splitting into smaller stories.

See: references/calculation-guide.md for examples and edge cases

6. Provide Estimation Rationale

Document WHY this estimate:

Estimation Rationale

Story Points: 10

Complexity (3/5): Moderate

• 6 files to modify/create
• Multiple integration points (validation, hashing, DB, JWT)
• Multiple error paths to handle

Effort (3/5): Medium

• 6 acceptance criteria
• ~250 lines of code
• ~10 tests required
• Estimated 3-4 hours

Risk (+1/3): Minor

• Team familiar with tech stack
• Requirements clear and testable
• Minor security considerations for bcrypt/JWT

Confidence: High (80%)

• Clear requirements
• Standard patterns
• No unknowns

7. Update Story File

Add estimation block to story file:

Estimation

Story Points: 10 Estimated By: Alex (Planner) Date: 2025-01-15 Confidence: High (80%)

Breakdown:

• Complexity: 3/5 (Moderate - 6 files, multiple integrations)
• Effort: 3/5 (Medium - 6 AC, ~250 LOC, ~10 tests, 3-4 hours)
• Risk: +1/3 (Minor - familiar tech, clear requirements)

Formula: (3 × 3) + 1 = 10 points

Assumptions:

• Team familiar with Zod, bcrypt, JWT, PostgreSQL
• Clear acceptance criteria remain stable
• No major architectural changes needed

8. Generate Estimation Report (Optional)

For formal estimation reviews or audits, generate comprehensive report:

Story Estimation Report

Executive Summary

• Story: User Signup with Email/Password
• Story Points: 10
• Confidence: High (80%)
• Recommendation: Ready for sprint planning

Detailed Analysis

[Complexity, Effort, Risk breakdown]

Comparable Stories

• story-auth-002-login: 8 points (similar complexity, slightly less effort)
• story-auth-003-password-reset: 13 points (more complex flow)

Assumptions & Risks

[List key assumptions]

Sprint Planning Notes

• Can be completed in 1 sprint (assuming 2-week sprint)
• No blocking dependencies
• Suitable for mid-level developer

See: references/report-templates.md for full report format

Batch Estimation

For multiple stories:

• Load all stories

• Estimate each using same process

• Compare estimates for consistency

• Adjust if similar stories have very different estimates

• Generate summary report

Tips for consistency:

• Use same reference points

• Compare with recently estimated similar stories

• Document rationale for each estimate

• Flag outliers for review

Calibration and Adjustment

After sprint completes:

• Compare estimated vs actual story points

• Identify patterns in over/under-estimation

• Adjust future estimates based on learnings

• Update complexity/effort/risk scales if needed

Example:

Story estimated: 10 points Actual velocity: 13 points (30% under-estimated)

Reason: Underestimated integration complexity

Learning: Increase complexity score for multi-API integrations

Common Scenarios

Story Seems Too Large (>13 points)

Approach:

• Identify if complexity, effort, or both are high

• Look for natural split points in acceptance criteria

• Split into multiple smaller stories

• Re-estimate each smaller story

Example:

Original: User Profile (21 points) Split into:

• User Profile - Basic Info (8 points)
• User Profile - Avatar Upload (8 points)
• User Profile - Preferences (5 points)

Uncertainty in Estimation

If confidence < 60%:

• Identify sources of uncertainty

• Add risk adjustment

• Consider spike story for research

• Document assumptions clearly

Team Disagreement on Estimate

Approach:

• Each person explains their reasoning

• Identify where views differ (complexity/effort/risk)

• Discuss until consensus or average estimates

• Document the final rationale

See: references/estimation-scenarios.md for complex cases

Best Practices

• Be consistent - Use same criteria for all stories

• Compare similar stories - Check recent similar estimates

• Document rationale - Explain WHY, not just WHAT

• Calibrate regularly - Adjust based on actual velocity

• Split large stories - > 13 points should be split

• Include the team - Discuss estimates with implementers

• Track confidence - Low confidence = higher risk adjustment

Reference Files

• references/complexity-scale.md

• Detailed 1-5 complexity scale with examples

• references/effort-scale.md

• Detailed 1-5 effort scale with examples

• references/risk-factors.md

• Risk analysis framework (0-3)

• references/calculation-guide.md

• Formula examples and edge cases

• references/report-templates.md

• Comprehensive report formats

• references/estimation-scenarios.md

• Complex scenarios and solutions

When to Escalate

• Story is very large (>20 points) and can't be split

• High uncertainty even after analysis (confidence < 40%)

• Team has no experience with required technology

• Requires significant architectural changes

• Story depends on many external factors

Part of BMAD Enhanced Planning Suite