project-sizing-guide

Project Sizing Guide — Software Project Effort Estimation

Helps teams produce scientifically grounded effort estimates for software projects, based on three major methodologies: Three-Point Estimation (PERT), T-shirt Sizing, and Function Point Analysis (FPA). Outputs optimistic, most-likely, and pessimistic values along with risk intervals.

Quick Start

1. User provides a requirements description → Agent identifies functional modules and breaks them into a Work Breakdown Structure (WBS)
2. Select an estimation method → Choose the best-fit approach based on project stage and available information
3. Estimate each item → Assign O/M/P (Optimistic / Most Likely / Pessimistic) values to every work package
4. Aggregate and report → Generate an estimation report with risk analysis and confidence intervals

A calculation helper is available:

python3 scripts/estimate_calculator.py --method pert --tasks '[{"name":"User Login","O":2,"M":3,"P":8}]'

---

Method Selection Guide

| Scenario | Recommended Method | Rationale |

|----------|-------------------|-----------|

| Early feasibility study, rough budgeting | T-shirt Sizing | Little information available; quickly align on order of magnitude |

| Sprint planning, iteration estimation | Three-Point Estimation (PERT) | Good granularity with confidence intervals |

| Contract bidding, large-project RFPs | Function Point Analysis (FPA) | Most rigorous; industry-comparable |

| Team has historical data | PERT + historical calibration | Combines empirical correction with data |

---

Method 1: Three-Point Estimation (PERT)

Core Formulas

| Metric | Formula | Meaning |

|--------|---------|---------|

| Expected Value E | (O + 4M + P) / 6 | Weighted average effort |

| Standard Deviation σ | (P − O) / 6 | Estimation uncertainty |

| Variance V | σ² | Used to aggregate across tasks |

| Project Total Expected | ΣE | Sum of individual expected values |

| Project Total Std Dev | √(ΣV) | Square root of summed variances |

Where:

• O (Optimistic): Shortest duration assuming everything goes smoothly
• M (Most Likely): Duration under normal circumstances
• P (Pessimistic): Longest duration when significant difficulties arise

Confidence Intervals

| Confidence Level | Interval | Use Case |

|-----------------|----------|----------|

| 68.3% | E ± 1σ | Internal rough estimates |

| 90% | E ± 1.645σ | Project planning |

| 95% | E ± 2σ | External quotes |

| 99.7% | E ± 3σ | Contractual commitments |

Steps

1. Build the WBS: Decompose requirements into the smallest independently estimable units (recommended ≤ 5 person-days each)
2. Three-point estimation: For each work package, provide O / M / P values (use consistent units: person-hours or person-days)
3. Calculate per-task expected value and standard deviation
4. Aggregate project-level metrics: Total Expected = ΣE, Total Std Dev = √(Σσ²)
5. Output confidence intervals: Choose a confidence level based on risk appetite

O/M/P Estimation Rules of Thumb

• O should not be less than 30% of M (overly optimistic suggests essential steps were overlooked)
• P should not exceed 5× M (overly pessimistic suggests unclear requirements that need clarification first)
• If O ≈ M ≈ P, the task is either extremely well-understood or the estimator hasn't seriously considered risks
• The P/O ratio (spread ratio) reflects uncertainty: < 2 = low risk, 2–4 = medium risk, > 4 = high risk

---

Method 2: T-shirt Sizing

Size Reference Table

| Size | Typical Range (person-days) | Typical Story Points | Suitable For |

|------|----------------------------|---------------------|--------------|

| XS | 0.25 – 0.5 | 1 | Config changes, copy edits, simple bug fixes |

| S | 0.5 – 2 | 2 – 3 | Single-component development, simple API, minor UI tweaks |

| M | 2 – 5 | 5 – 8 | Complete feature module, moderately complex API |

| L | 5 – 15 | 13 – 21 | Cross-module features requiring integration |

| XL | 15 – 40 | 34 – 55 | Subsystem-level development requiring architecture design |

| XXL | 40+ | 89+ | Should be split across multiple iterations; not recommended as a single estimation unit |

Converting T-shirt Sizes to Three-Point Estimates

When more precise numbers are needed, T-shirt sizes can be converted to three-point estimates:

| Size | O (person-days) | M (person-days) | P (person-days) |

|------|-----------------|-----------------|-----------------|

| XS | 0.25 | 0.5 | 1 |

| S | 0.5 | 1 | 2.5 |

| M | 2 | 3.5 | 7 |

| L | 5 | 10 | 20 |

| XL | 15 | 25 | 50 |

| XXL | 40 | 70 | 150 |

Steps

1. Team alignment: Confirm what each size means (the table above is a reference; teams may customize)
2. Independent assessment: Each person assigns a size independently to avoid anchoring bias
3. Discuss discrepancies: When estimates differ by more than 2 sizes, a discussion is mandatory
4. Reach consensus: Adopt the team consensus value
5. Convert to numbers (optional): Use the table above to derive O/M/P values

---

Method 3: Function Point Analysis (FPA)

Five Function Component Types

| Component Type | Abbreviation | Definition | Example |

|---------------|-------------|-----------|---------|

| Internal Logical File | ILF | Logical data group maintained by the application | Users table, Orders table |

| External Interface File | EIF | Data group referenced but not maintained by the application | Third-party exchange rate data |

| External Input | EI | Data processing entering the system from outside | Form submission, API POST |

| External Output | EO | Data generated and sent outside the system | Report generation, exports |

| External Inquiry | EQ | Simple data retrieval + display | List queries, detail pages |

Complexity Weight Matrix

| Component Type | Low | Medium | High |

|---------------|-----|--------|------|

| ILF | 7 | 10 | 15 |

| EIF | 5 | 7 | 10 |

| EI | 3 | 4 | 6 |

| EO | 4 | 5 | 7 |

| EQ | 3 | 4 | 6 |

Complexity Assessment Rules

ILF / EIF Complexity (based on DET – Data Element Types and RET – Record Element Types):

| | DET 1-19 | DET 20-50 | DET 51+ |

|---|---------|-----------|---------|

| RET 1 | Low | Low | Medium |

| RET 2-5 | Low | Medium | High |

| RET 6+ | Medium | High | High |

EI Complexity (based on DET and FTR – File Types Referenced):

| | DET 1-4 | DET 5-15 | DET 16+ |

|---|---------|----------|---------|

| FTR 0-1 | Low | Low | Medium |

| FTR 2 | Low | Medium | High |

| FTR 3+ | Medium | High | High |

EO / EQ Complexity (based on DET and FTR):

| | DET 1-5 | DET 6-19 | DET 20+ |

|---|---------|----------|---------|

| FTR 0-1 | Low | Low | Medium |

| FTR 2-3 | Low | Medium | High |

| FTR 4+ | Medium | High | High |

Converting Function Points to Effort

After calculating Unadjusted Function Points (UFP):

1. Calculate the Value Adjustment Factor (VAF) (optional; deprecated since IFPUG 4.3+ but still used by some teams)

• 14 General System Characteristics (GSC), each scored 0–5
• VAF = 0.65 + 0.01 × Σ(GSC)
• Adjusted Function Points AFP = UFP × VAF

1. Function points to person-hours

• Industry benchmark: 8–15 person-hours per function point (varies by language and team maturity)

| Technology Stack | Person-hours / FP | Notes |

|-----------------|-------------------|-------|

| Low-code / Mature Frameworks | 4 – 8 | Many reusable components available |

| Python / JS / Modern Web | 8 – 12 | Mainstream development productivity |

| Java / C# Enterprise | 10 – 15 | Includes architecture and standards overhead |

| Embedded / C / C++ | 15 – 25 | High debugging and testing cost |

| Legacy System Maintenance | 20 – 30 | Comprehension and regression cost |

Steps

1. Identify function components: List all ILFs, EIFs, EIs, EOs, and EQs
2. Assess complexity: Rate each component as Low / Medium / High
3. Calculate UFP: Sum (count × weight) for all components
4. Select conversion factor: Choose person-hours per FP based on technology stack
5. Compute total effort: UFP × conversion factor
6. Add buffer: A 15–30% management and risk buffer is recommended

---

Estimation Adjustment Factor Checklist

After completing the estimation, verify that the following factors have been accounted for:

Technical Factors

• [ ] Technology stack familiarity (Is the team experienced? If unfamiliar, add 30–50%)
• [ ] Technical debt (Poor legacy code quality? Add 20–40%)
• [ ] Third-party dependencies (Unstable APIs? Missing documentation? Add 10–30%)
• [ ] Performance / security requirements (Special non-functional requirements? Add 15–25%)

Team Factors

• [ ] Team size (Communication overhead increases significantly above 5 people; add ~5% per person)
• [ ] Personnel turnover risk (Key members may leave? Add 15–25%)
• [ ] Parallel projects (Team context-switching across multiple projects? Add 20–30%)
• [ ] Onboarding new members (New hires? Expect ~50% reduced efficiency for the first 2 weeks)

Process Factors

• [ ] Requirements stability (Requirements likely to change? Add 20–50%)
• [ ] Approval processes (Multiple layers of approval needed? Add 10–20%)
• [ ] Deployment complexity (Multi-environment, multi-region deployments? Add 10–15%)
• [ ] Compliance requirements (Audit or compliance processes? Add 15–30%)

Commonly Underestimated Work

• [ ] Code review: +10–15%
• [ ] Unit test authoring: +15–25%
• [ ] Integration / E2E testing: +10–20%
• [ ] Documentation: +5–15%
• [ ] Bug fixing and regression: +10–20%
• [ ] Environment setup and DevOps: +5–10%
• [ ] Meetings and communication: +10–15%

---

Estimation Output Template

After the Agent completes the estimation, it should produce output in the following format:

## Estimation Report: [Project / Feature Name]

### Estimation Method: [PERT / T-shirt / FPA]

### Work Package Breakdown

| # | Work Package | O (person-days) | M (person-days) | P (person-days) | E (person-days) | σ |
|---|-------------|-----------------|-----------------|-----------------|-----------------|---|
| 1 | xxx         | x               | x               | x               | x.x             | x.x |
| 2 | xxx         | x               | x               | x               | x.x             | x.x |

### Summary

- Total expected effort: X person-days
- Total standard deviation: X person-days
- 68% confidence interval: X – X person-days
- 90% confidence interval: X – X person-days
- 95% confidence interval: X – X person-days

### Adjustment Factors
- [Factors considered and adjustments applied]

### Final Recommendation
- For internal planning: X person-days (90% confidence)
- For external quotes: X person-days (95% confidence)

### Risk Alerts
- [Key risk items and mitigation suggestions]

---

Calculation Tool

The scripts/estimate_calculator.py script supports numerical calculations for all three estimation methods:

# Three-Point Estimation (PERT)
python3 scripts/estimate_calculator.py --method pert \
  --tasks '[{"name":"Login Module","O":2,"M":3,"P":8},{"name":"Payment Module","O":5,"M":10,"P":20}]'

# T-shirt Size Conversion
python3 scripts/estimate_calculator.py --method tshirt \
  --tasks '[{"name":"Login Module","size":"M"},{"name":"Payment Module","size":"L"}]'

# Function Point Analysis
python3 scripts/estimate_calculator.py --method fpa \
  --components '[{"type":"ILF","complexity":"medium","count":3},{"type":"EI","complexity":"low","count":5}]' \
  --hours-per-fp 10

---

References

• IFPUG (International Function Point Users Group) CPM 4.3.1
• PMI PMBOK Guide — 6th Edition, Section 6.4: Estimate Activity Durations
• Steve McConnell, Software Estimation: Demystifying the Black Art
• Mike Cohn, Agile Estimating and Planning