Story Point Estimation Guide¶

CMS Planner uses Fibonacci sequence-based story point estimation to account for increasing uncertainty with larger tasks. This guide explains the framework and how to apply it effectively.

Fibonacci Sequence¶

Story points follow the Fibonacci sequence: 1, 2, 3, 5, 8, 13, 21, 34+

Why Fibonacci?¶

• Uncertainty increases non-linearly - Larger tasks have more unknowns
• Prevents false precision - Gap between numbers acknowledges uncertainty
• Forces decomposition - Very large numbers indicate tasks need breaking down
• Industry standard - Widely used in Agile/Scrum methodologies

Story Point Scale¶

What Story Points Measure¶

Story points measure complexity and effort, not just time:

Factors Considered¶

1. Complexity - How difficult is the work?
2. Uncertainty - How well understood is the requirement?
3. Effort - How much work is involved?
4. Dependencies - What else must be complete first?
5. Risk - What could go wrong?

NOT Time Estimates¶

While we provide time ranges for reference, story points are relative measures of effort.

• 5 points for Developer A might take 2 days
• 5 points for Developer B might take 3 days
• Both are still 5 points of complexity

Estimation Best Practices¶

Include Everything¶

Story points should include time for:

• ✅ Implementation - Writing the code
• ✅ Testing - Unit, integration, manual testing
• ✅ Code review - Review cycle and revisions
• ✅ Documentation - Code comments, README updates
• ✅ Deployment - Configuration, deployment steps
• ✅ Bug fixes - Addressing issues found in testing

Consider Complexity Factors¶

• Technical complexity - Algorithm difficulty, architecture decisions
• Integration complexity - Number of systems/components to integrate
• Unknown requirements - Ambiguity or research needed
• Team experience - Familiarity with technology
• Dependencies - Blocking or parallel work

Add Uncertainty Buffer¶

• Higher points = more buffer - 21 points has more uncertainty than 3 points
• Unknown tech = higher points - New framework? Add buffer
• Vague requirements = higher points - Unclear acceptance criteria? Add buffer
• External dependencies = higher points - Waiting on third parties? Add buffer

Recipe-Based Projects¶

For Drupal recipes and similar architectures, estimate separately:

1. Recipe creation (8-13 points)
2. Define configuration entities
3. Export configuration
4. Organize structure

5. Test clean installation

6. Configuration export (2-3 points per entity)

7. Content type configuration
8. View configuration

9. Field configuration

10. Testing (3-5 points per recipe)

11. Clean installation test
12. Dependency testing

13. Field storage verification

14. Documentation (2-3 points per recipe)

15. README file
16. Installation instructions

17. Dependency documentation

18. Demo content (5-8 points per recipe)

19. Create sample content
20. Export with Default Content
21. Verify import works

WordPress Block Theme Projects¶

For WordPress 6.8+ block themes with Full Site Editing, estimation depends heavily on the block vs pattern vs ACF vs custom block decision. This choice can impact development time by 3-10x.

Story Points to Hours Conversion¶

While story points are relative measures, stakeholders often need hour estimates for budgeting. Use these conversion guidelines for WordPress projects:

Important: These are estimates for planning, not guarantees. Actual time varies by developer experience, complexity, and unknowns.

Block Theme Foundation (5-8 points, 20-32 hours)¶

theme.json v3 Configuration: - Basic (colors, typography, spacing): 3 points (6-8 hours) - 6-8 colors - 2 font families, 5-7 font sizes - 8-10 spacing presets - Basic layout settings

• Complete (+ element styles, custom settings): 5 points (12-16 hours)
• Everything in Basic
• Element styles (links, headings, buttons)
• Border radius, shadows, gradients

• Block-specific style overrides

• Advanced (+ style variations, complex presets): 8 points (24-32 hours)

• Everything in Complete
• Multiple style variations (light/dark themes)
• Complex block-specific settings
• Custom template configurations

Basic Templates: - index, single, page, 404 templates: 2-3 points (8-12 hours) - Header/footer template parts: 1-2 points (4-8 hours)

Block Pattern Creation (1-5 points per pattern)¶

Patterns are reusable combinations of core blocks - the most efficient approach for most layouts.

Estimation Factors: - Number of blocks (each block = ~15-30 minutes) - Nesting depth (nested groups add complexity) - Custom styling (beyond theme.json) - Responsive behavior (mobile/tablet/desktop variations)

ACF Block Development (2-5 points)¶

ACF blocks use PHP templates + custom fields - faster than custom Gutenberg blocks for field-heavy components.

Requirements: - ACF PRO license ($49-249/year) - PHP templating knowledge - Field configuration time

Estimation Factors: - Number of fields (each field = ~15-30 minutes) - Repeater fields (add 1-2 hours per repeater) - Conditional logic (add 1-2 hours per condition set) - Relationship/post object fields (add 2-4 hours)

Custom Gutenberg Block Development (3-21 points)¶

Custom blocks are React-based - reserve for truly interactive features. Most expensive option.

Requirements: - React knowledge - WordPress block editor API - Build tooling (@wordpress/scripts, webpack, npm) - Testing (Jest, React Testing Library)

Estimation Factors: - Block attributes (each attribute = ~30-60 minutes) - InspectorControls (sidebar settings = +2-4 hours) - InnerBlocks configuration (each level = +4-8 hours) - Backend PHP rendering (add 2-4 hours) - REST API endpoints (each endpoint = +4-8 hours) - State management complexity (add 4-8 hours)

Performance Optimization (5-13 points)¶

Core Web Vitals are mandatory for WordPress projects (Google Search ranking factor since 2021).

Core Web Vitals Targets: - LCP (Largest Contentful Paint): < 2.5 seconds - INP (Interaction to Next Paint): < 200ms - CLS (Cumulative Layout Shift): < 0.1

Estimation Factors: - Current performance baseline - Asset size (JS/CSS/images) - Number of plugins - Hosting quality

Plugin Setup and Configuration¶

Plugin Budget: Recommend < 15 plugins total for performance (< 20 maximum with strong justifications).

Hour Calculation for CSV Export¶

When the csv-exporter skill generates the Teamwork backlog CSV, the "Estimated time" column is populated using these conversions:

Format Guidelines: - 1-2 points: Use exact hours (e.g., "2h", "4h") - 3-5 points: Use hour ranges or days (e.g., "6-8h", "1 day", "12-16h", "2 days") - 8+ points: Use day ranges or weeks (e.g., "3-4 days", "1-2 weeks")

Examples:

Tasklist,Task,Tags,Estimated time
"Phase 1","[EPIC] Theme Foundation [8 points]","SP-8,Phase-1","24-32h"
"Phase 1","- [TASK] theme.json configuration [3 points]","SP-3,Phase-1","1 day"
"Phase 1","- [TASK] Basic templates [2 points]","SP-2,Phase-1","4h"
"Phase 2","[EPIC] Block Patterns [13 points]","SP-13,Phase-2","1-2 weeks"
"Phase 2","- [PATTERN] Hero section [2 points]","SP-2,Phase-2","4h"
"Phase 2","- [PATTERN] Feature grid [2 points]","SP-2,Phase-2","4h"
"Phase 3","[CUSTOM] Pricing calculator [13 points]","SP-13,Phase-3","1-2 weeks"

Decision Framework Impact on Estimates¶

The Pattern-First Framework: 1. Try Core Blocks First → 1-3 points (2-8 hours) 2. Compose Patterns Second → 2-5 points (4-20 hours) 3. Use ACF Blocks Third → 2-5 points (4-20 hours) + ACF PRO cost 4. Build Custom Blocks Last → 3-21 points (12-120 hours)

Cost Multipliers: - Pattern → ACF Block: 2-3x longer - Pattern → Custom Block: 3-10x longer - ACF Block → Custom Block: 2-5x longer

Example: Team Member Directory

Key Insight: For most UI components (80-90%), patterns or ACF blocks are sufficient. Custom blocks should be < 10-20% of total development.

WordPress Estimation Checklist¶

Before providing estimates, verify:

• Decision framework applied - Core → Pattern → ACF → Custom (in order)
• Justification documented - Why this approach vs alternatives?
• Performance budget included - Core Web Vitals optimization (5-8 points)
• Plugin budget considered - < 15 plugins target, justifications documented
• ACF PRO cost noted - If using ACF blocks, note $49-249/year license
• Testing included - Browser testing (2 points), accessibility (3 points), performance (2 points)
• Documentation included - Pattern library, editor training, developer README

Velocity Calculation¶

Team velocity is the average story points completed per sprint.

Formula¶

Velocity = (Team Size × Hours/Sprint × Productive %) / Hours per Point

Example Calculation¶

Team: - 3 developers - 2-week sprints (80 hours/developer) - 70% productive time (30% for meetings, admin, etc.) - 6 hours per story point (team average)

Calculation:

3 developers × 80 hours × 0.70 / 6 hours per point = 28 points per sprint

Calibrating Velocity¶

After a few sprints, use historical data:

1. Track completed points per sprint
2. Calculate average over 3-5 sprints
3. Adjust estimates if consistently over/under
4. Re-calibrate when team changes

Breaking Down Large Items¶

13 Points: Should Break Down¶

13-point items should typically be broken into smaller stories:

Example: User Management System [13 points]

Break into: - User Registration Flow [5 points] - User Login Flow [3 points] - Password Reset [2 points] - Profile Management [3 points]

Total: 13 points (same estimate, but broken down)

21 Points: Must Break Down¶

21-point items are too large for a single sprint and must be decomposed:

Example: Complete Theme Development [21 points]

Break into: - Base Theme Setup [5 points] - Component Library [8 points] - Page Templates [5 points] - Responsive Styles [3 points]

Total: 21 points (spread across multiple sprints)

34+ Points: Decompose First¶

Items over 34 points should be broken into multiple epics:

Example: E-commerce Platform [89 points]

Break into epics: - Product Management [21 points] - Shopping Cart [13 points] - Checkout Flow [21 points] - Payment Processing [13 points] - Order Management [21 points]

Total: 89 points (5 epics)

Estimation Workshop¶

Planning Poker¶

1. Present user story - Product owner explains requirement
2. Ask questions - Team clarifies understanding
3. Individual estimates - Each person picks a card (1, 2, 3, 5, 8, 13, 21)
4. Reveal simultaneously - Everyone shows their card
5. Discuss differences - Highest and lowest explain reasoning
6. Re-estimate - Repeat until consensus

Relative Estimation¶

Compare to known tasks:

• "This is about the same as the login form we built" → 5 points
• "This is more complex than search but simpler than checkout" → between 8 and 13
• "This is twice as complex as the user profile" → double the points

T-Shirt Sizing (Initial Estimates)¶

For rough initial estimates, use T-shirt sizes:

• XS → 1-2 points
• S → 3-5 points
• M → 8 points
• L → 13 points
• XL → 21 points
• XXL → Must decompose

Convert to Fibonacci numbers for sprint planning.

Common Estimation Mistakes¶

❌ Too Precise¶

Wrong: "This is 4.5 story points" Right: "This is between 3 and 5, let's call it 5"

Story points are relative, not precise time measurements.

❌ Time-Based Thinking¶

Wrong: "8 hours = 1 day = 8 points" Right: "This is more complex than a 5-pointer but less than a 13"

Think complexity, not time.

❌ Individual Capacity¶

Wrong: "I can do 40 points this sprint" Right: "Our team velocity is 28 points per sprint"

Story points are team-based, not individual.

❌ Ignoring Uncertainty¶

Wrong: "We've done this before, it's still 5 points even with new tech" Right: "New tech adds uncertainty, this is 8 points"

Higher uncertainty = higher points.

❌ Not Including Everything¶

Wrong: "5 points for coding" (forgetting testing, review, documentation) Right: "5 points for full implementation including tests and review"

Include all work in the estimate.

Re-estimation¶

When to Re-estimate¶

• Requirements change significantly
• Technical approach changes
• New information discovered
• Team composition changes
• Velocity consistently off

How to Re-estimate¶

1. Review original estimate and reasoning
2. Identify what changed - new requirements? tech change?
3. Estimate new work separately if possible
4. Adjust total - add points for new complexity
5. Document change - note why re-estimated

Example¶

Original: API Integration [5 points] - Simple REST API - JSON response - Standard authentication

Re-estimated: API Integration [13 points] - Discovered: SOAP API (not REST) - XML parsing required - OAuth 2.0 with refresh tokens - Rate limiting to handle

Reasoning: Complexity increased significantly with legacy SOAP API and OAuth requirements.

Story Points in FRDs¶

CMS Planner includes story points throughout the FRD:

In Requirements Section¶

## FR-001: saplings_person Recipe [MUST HAVE]

**Story Points:** 34 points

- Recipe creation and config export: 13 points
- Field definitions (including shared storage): 8 points
- Views and Pathauto configuration: 5 points
- Testing and documentation: 5 points
- Demo content creation: 3 points

In Implementation Plan¶

## Phase 2: Core Recipes [168 points]

### Epic 1: saplings_person Recipe [34 points]
- Story 1: Content type and fields [13 points]
- Story 2: Taxonomies and views [8 points]
- Story 3: Pathauto and metatag [5 points]
- Story 4: Demo content [3 points]
- Story 5: Testing and documentation [5 points]

In CSV Backlog¶

Tasklist,Task,Tags
"Phase 2","[EPIC] saplings_person [34 points]","SP-34,Phase-2"
"Phase 2","- [STORY] Content type [13 points]","SP-13,Phase-2"
"Phase 2","-- [TASK] Field definitions [5 points]","SP-5,Phase-2"

Resources¶

• Agile Estimating and Planning by Mike Cohn
• Scrum Guide: https://scrumguides.org/
• Mountain Goat Software: https://www.mountaingoatsoftware.com/agile/planning-poker
• Atlassian Agile Coach: https://www.atlassian.com/agile/project-management/estimation

Getting Help¶

• Documentation: https://kanopi.github.io/cms-planner/
• GitHub Issues: https://github.com/kanopi/cms-planner/issues
• Email: code@kanopi.com

Next: Teamwork Import | Recipe Projects