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 examplesreferences/effort-scale.md - Detailed 1-5 effort scale with examplesreferences/risk-factors.md - Risk analysis framework (0-3)references/calculation-guide.md - Formula examples and edge casesreferences/report-templates.md - Comprehensive report formatsreferences/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
