Estimation Expertise

When to Use This Skill

Load this skill when you need to:

• Estimate effort for a Linear issue, feature, or mini-PRD
• Decompose work into functional areas and role-based effort
• Convert hour estimates to Linear story points
• Write a structured estimate into a Linear issue comment
• Review or refine existing estimates

Common triggers:

• During Refinement phase when refining effort estimates
• When creating or updating Linear features with story points
• When a PM or SE asks "how long will this take?"

Quick Reference

Constants

Points-to-Hours Mapping

Functional Areas

Roles

Parent and Sub-issue Estimation

The Model

When a parent issue has specification sub-issues ([Behaviour], [UX]):

Parent estimate = total effort (specs + implementation)

Sub-issue estimates = breakdown of the parent total (not additions)

Example

Issue: Login Flow (8 pts total)
  ├── [Behaviour] Login scenarios (2 pts) — part of the 8
  ├── [UX] Login Storybook (2 pts) — part of the 8
  └── Implementation (4 pts) — implicit remainder, not a sub-issue

Velocity Calculation

When calculating velocity:

• Count the parent issue points (8 pts)
• Do NOT add sub-issue points on top (that would double-count to 12 pts)

Sub-issues exist for assignment and scheduling, not for inflating totals.

Estimation Timing

Discovery Estimate (on parent):

• Created during Discovery phase
• Rough total for the whole capability (specs + implementation)
• Confidence: Low/Medium
• No sub-issues exist yet

Refined Estimate (during Refinement):

• Sub-issues created with individual estimates
• Parent estimate updated if scope changed during refinement
• Verify: parent estimate ≥ sum of sub-issue estimates
• Confidence: Medium/High

Zero-Point Issues and Batching

The Problem

The 1-point minimum (3 hours) includes overhead for code + test + docs. For trivial changes (typo fix, config tweak), this overhead is disproportionate and inflates velocity.

The Solution

For genuinely trivial changes:

• Assign 0 points if it needs tracking
• Or batch into a "Housekeeping" parent issue

For batches of trivial changes:

• Create a "Housekeeping" or "Polish" parent issue
• Add trivial items as sub-issues (titles only, no individual estimates)
• Estimate the parent collectively (e.g., 2-3 points for 10-15 items)

Example

Issue: Housekeeping — Week of Feb 10 (3 pts)
  ├── Sub-issue: Fix typo in login button
  ├── Sub-issue: Update copyright year in footer
  ├── Sub-issue: Remove unused import in auth.ts
  ├── Sub-issue: Add missing alt text to logo
  └── ... (10-15 trivial items)

Decision Guide

Avoid

• Estimating each trivial change at 1 point (inflates velocity)
• Creating issues for changes that don't need tracking
• Letting trivial changes accumulate without batching them

Two-Tier Estimation

Estimation happens in two phases with increasing precision:

Discovery Estimate (Feature-Level)

• When: During Discovery phase, when creating Linear features
• Granularity: Feature-level only (sub-issues don't exist yet)
• Confidence: Typically Low or Medium
• Purpose: Rough order-of-magnitude for planning and prioritisation
• Tag: [Discovery Estimate] in Linear comment

Refined Estimate (Atomic with Roll-Up)

• When: During Refinement phase, after Behaviour scenarios and mini-PRD are written
• Granularity: Per sub-issue, with hours and points rolling up to the parent feature
• Confidence: Typically Medium or High
• Purpose: Detailed breakdown for sprint planning and delivery
• Tag: [Refined Estimate] in Linear comment

Roll-up rule: Both hours AND points roll up from sub-issues to the parent feature. Do not rely solely on Linear's points roll-up — explicitly track total hours in the parent feature's estimate comment and mini-PRD.

Small feature exception: Features estimated at 3 points or fewer can stay as a single issue without sub-issue decomposition.

Sub-issue size policy: Other than [Behaviour] and [UX] sub-issues (which are exempt), sub-issues should only be created when the parent exceeds 2 days (12 hours) of human effort, and each sub-issue must itself represent at least 2 days (12 hours) of work. The work must also be genuinely independent (different person, different phase, or independently deliverable). Prefer checklists in the parent description over small sub-issues.

Rules

1. Always decompose before estimating. Never assign a single number without breaking work into functional areas first.
2. Estimate in hours, convert to points. Hours are the base unit. Convert to the nearest fibonacci point value using the mapping table.
3. Round up to the next fibonacci value. If total hours fall between two values, always round up (e.g., 20 hours rounds to 8 points, not 5).
4. Issues over 34 points must be decomposed. If an estimate exceeds 34 points, split the work into smaller issues.
5. Include all functional areas. Don't forget testing, documentation, and infrastructure — they are often 30-50% of total effort.
6. Estimate for a single competent human. Assume one person working at normal pace, not a team in parallel.
7. State confidence level. Every estimate must include a confidence indicator based on requirement clarity.
8. Use the structured output format. All estimates posted to Linear must use the standard format below.
9. Roll up both hours and points. When estimating sub-issues, always sum total hours in the parent feature — do not rely solely on Linear's points roll-up.
10. Tag estimates by phase. Use [Discovery Estimate] or [Refined Estimate] to differentiate in Linear comments.

Workflow: Estimate a Task

When: You need to estimate a Linear issue or feature.

Procedure:

1. Read the requirements. Read the issue description, comments, mini-PRD, and any BDD scenarios. If requirements are vague, flag this in the confidence level.

2. Identify functional areas. List which areas are involved (FE, BE, INFRA, TEST, UX, DOCS). Not every task touches all areas.

3. Estimate hours per area. For each functional area, estimate the hours a single competent person would need:

   • What specific work is required?
   • What's the complexity? (new code vs. modification, known vs. unknown patterns)
   • Are there dependencies or integration points?

4. Assign roles. Map each functional area to the role that would do the work. Some areas may involve multiple roles.

5. Sum total hours. Add up all area estimates.

6. Convert to points. Find the nearest fibonacci value at or above the total hours using the mapping table.

7. Assess confidence. Rate confidence based on requirement clarity:

   • High — Clear requirements, BDD scenarios exist, known patterns
   • Medium — Refinement understood but some ambiguity, partially specified
   • Low — Vague requirements, unknown technical approach, significant unknowns

8. Write the estimate. Use the structured output format and post to the Linear issue.

Workflow: Update Linear with Estimate

When: You have completed an estimate and need to record it.

Procedure:

1. Set the story points on the issue:

   bashCopy

   curl -s -X POST https://api.linear.app/graphql \
     -H "Content-Type: application/json" \
     -H "Authorization: $LINEAR_API_KEY" \
     -d '{
       "query": "mutation { issueUpdate(id: \"ISSUE-ID\", input: { estimate: POINTS }) { success } }"
     }'
   

   Or via linearis if the CLI supports it in future versions.

2. Post the detailed breakdown as a comment:

   bashCopy

   linearis issues comment ISSUE-ID "ESTIMATE_MARKDOWN"
   

Structured Output Format

Use this format when posting estimates to Linear issue comments:

## [Discovery Estimate] or [Refined Estimate]

**Total: X points (Y hours / Z days)**
**Confidence: High | Medium | Low**

### Breakdown

| Area | Work | Hours | Role |
|------|------|-------|------|
| FE | [description] | X | SE |
| BE | [description] | X | SE |
| TEST | [description] | X | SE/QA |
| DOCS | [description] | X | PM/SE |
| **Total** | | **X** | |

### Assumptions
- [Key assumption 1]
- [Key assumption 2]

### Risks
- [Risk that could increase estimate]

Example: Discovery Estimate (Feature-Level)

## [Discovery Estimate]

**Total: 8 points (24 hours / 4 days)**
**Confidence: Medium**

### Breakdown

| Area | Work | Hours | Role |
|------|------|-------|------|
| BE | Auth API endpoints, JWT middleware, user model | 8 | SE |
| FE | Login page, auth context, protected routes | 6 | SE |
| INFRA | Cognito setup, env vars, CORS | 2 | SE |
| TEST | Unit + E2E tests | 5 | SE/QA |
| DOCS | Auth flow docs, API docs | 2 | SE |
| UX | Login form Storybook story | 1 | UX |
| **Total** | | **24** | |

### Assumptions
- Using AWS Cognito (not custom auth)
- Email/password auth only (no social login)

### Risks
- Cognito config complexity could add 4-8 hours

Example: Refined Estimate (Atomic with Roll-Up)

## [Refined Estimate]

**Feature Total: 10 points (30 hours / 5 days)**
**Confidence: High**

### Sub-Issue Breakdown

| Sub-Issue | Area | Hours | Points |
|-----------|------|-------|--------|
| AF-50a: Backend API + data model | BE | 9 | 3 |
| AF-50b: Frontend UI components | FE, UX | 9 | 3 |
| AF-50c: E2E tests + integration | TEST | 6 | 2 |
| AF-50d: Documentation + infra | DOCS, INFRA | 6 | 2 |
| **Total** | | **30** | **10** |

### Change from Discovery
- Discovery estimate: 8 points (24 hours)
- Refined estimate: 10 points (30 hours)
- Reason: BDD scenarios revealed additional error handling and edge cases

### Assumptions
- Using AWS Cognito (not custom auth)
- Email/password auth only (no social login)
- SSO not required

### Risks
- Cognito configuration complexity could add 4-8 hours

Estimation Heuristics

Use these rules of thumb when detailed decomposition isn't practical:

By Change Type

Testing Multiplier

Testing typically adds 30-50% to implementation time:

Documentation Overhead

Common Pitfalls

1. Forgetting testing effort. Testing is 30-50% of total work. Always include TEST in your breakdown.
2. Ignoring infrastructure. New features often need env vars, CI changes, or AWS resources.
3. Underestimating integration. Connecting to external APIs or services takes longer than expected.
4. Not accounting for review cycles. Code review and feedback rounds add time. Include 1-2 hours for non-trivial PRs.
5. Estimating for the best case. Estimate for normal pace, not "if everything goes perfectly."
6. Skipping documentation. Docs are part of "done." Include them in every estimate.
7. Over-precision in large estimates. A 34-point issue doesn't need hour-level precision — focus on getting the right order of magnitude and flag that it should be decomposed.
8. Estimating Epic parents that have estimated children. When an issue is labelled "Epic" and has sub-issues that carry estimates, the parent should have estimate = 0. Carrying estimates on both parent and children causes double-counting in project totals. Always check: does this issue have estimated children? If so, zero the parent estimate.
9. Missing delivery by-products. Issues created during delivery as follow-on work ("what's left to do" breakdowns) bypass the estimation workflow. These need an estimation sweep — either via a recurring task (like AGV-85) or as part of cycle planning.
10. Not checking for overlapping scope. Before estimating, check if the issue's scope overlaps with existing issues. If two issues cover the same work, one should be marked as a duplicate or made a sub-issue of the other. Estimating both inflates the project total.

Integration Points

Discovery phase (af-discover-scope):

• Feature-level estimates when creating Linear features in Phase 4
• Tag as [Discovery Estimate] in Linear comment
• Set story points on the feature issue directly
• Confidence is typically Low or Medium

Refinement phase (af-refine-specifications):

• Refined estimates after Behaviour scenarios and mini-PRD are complete
• Tag as [Refined Estimate] in Linear comment
• For features > 3 points: create specification sub-issues ([Behaviour], [UX]) with individual estimates
• Sub-issue estimates are a breakdown of the parent total (not additions)
• Hours AND points roll up to the parent feature
• Document final estimate in mini-PRD Section 7 (Effort Estimation)
• Story points must be set before moving to "Approved"

Mini-PRD (templates/mini-prd-template.md):

• Section 7 captures the refined estimate with full breakdown
• Becomes the permanent record of how the estimate was calculated

Work management (af-manage-work-state):

• Story points drive sprint planning and velocity tracking
• Use issueUpdate mutation to set estimate field on Linear issues

Linear API (af-query-linear-api):

• Set estimates via GraphQL: issueUpdate(id: "...", input: { estimate: N })
• Query estimates: issue(id: "...") { estimate }

Database (agents.db tasks table):

• After producing an estimate, persist it to the tasks table
• Discovery estimates: update discovery_points, discovery_hours, discovery_confidence, discovery_breakdown
• Refined estimates: update refined_points, refined_hours, refined_confidence, refined_breakdown
• Use this command after each estimate:

sqlite3 /var/lib/claude-agents/agents.db "
  INSERT INTO tasks (issue_id, issue_title, project, team_key, created_at, updated_at)
  VALUES ('<ISSUE_ID>', '<TITLE>', '<PROJECT>', '<TEAM_KEY>', datetime('now'), datetime('now'))
  ON CONFLICT(issue_id) DO UPDATE SET updated_at = datetime('now');

  UPDATE tasks SET
    discovery_points = <POINTS>,
    discovery_hours = <HOURS>,
    discovery_confidence = '<CONFIDENCE>',
    discovery_breakdown = '<JSON_BREAKDOWN>',
    discovery_estimated_at = datetime('now'),
    updated_at = datetime('now')
  WHERE issue_id = '<ISSUE_ID>';
"

For refined estimates, replace discovery_* columns with refined_*.

Remember:

1. Decompose first, estimate second — never guess a single number
2. Hours are the base unit, points are for Linear
3. 1 point = 3 hours = half a productive day
4. Always include testing, docs, and infrastructure
5. Round up to the next fibonacci value, never down
6. Roll up BOTH hours and points from sub-issues to parent feature
7. Tag estimates: [Discovery Estimate] or [Refined Estimate]
8. Persist estimates to the tasks table in agents.db after setting on Linear