estimate-stories

name	estimate-stories
description	Calculate story point estimates for user stories using structured formula (Complexity × Effort + Risk). Analyzes acceptance criteria, assesses complexity (1-5), effort (1-5), and risk (0-3), then documents estimation rationale. Use during backlog grooming or sprint planning when stories need sizing.
acceptance	[{"story_loaded":"Story file successfully loaded with acceptance criteria"},{"complexity_assessed":"Complexity score (1-5) calculated with detailed rationale based on technical difficulty"},{"effort_assessed":"Effort score (1-5) calculated with rationale based on work volume"},{"risk_assessed":"Risk adjustment (0-3) calculated with rationale based on unknowns"},{"story_points_calculated":"Story points calculated using formula: (Complexity × Effort) + Risk"},{"estimation_documented":"Estimation block added to story file with formula, breakdown, and assumptions"}]
inputs	{"story_id":{"type":"string","required":true,"description":"Story identifier (e.g., 'story-auth-001')","validation":"Must match pattern: story-{component}-{number}-{slug}"},"story_file":{"type":"string","required":true,"description":"Path to story markdown file"},"batch_mode":{"type":"boolean","required":false,"description":"Whether estimating multiple stories (for consistency checks)","default":false},"config_file":{"type":"string","required":false,"description":"Path to config with velocity baseline (defaults to .claude/config.yaml)"}}
outputs	{"story_points":{"type":"number","description":"Calculated story points using formula"},"complexity_score":{"type":"number","description":"Complexity assessment (1-5 scale)"},"effort_score":{"type":"number","description":"Effort assessment (1-5 scale)"},"risk_score":{"type":"number","description":"Risk adjustment (0-3 scale)"},"confidence_level":{"type":"string","description":"Estimation confidence (high/medium/low based on clarity and familiarity)"},"estimation_added":{"type":"boolean","description":"Whether estimation block was added to story file"},"split_recommended":{"type":"boolean","description":"Whether story should be split (true if >13 points)"}}
telemetry	{"emit":"skill.estimate-stories.completed","track":["story_id","story_points","complexity_score","effort_score","risk_score","confidence_level","split_recommended","batch_mode","duration_ms"]}

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