Estimation Techniques

// Estimation models and calculators
interface EstimationResult {
  technique: string;
  estimate: number;
  unit: 'points' | 'hours' | 'days';
  confidence: number; // percentage
  range: { low: number; high: number };
}

// Three-Point (PERT) Estimation
function pertEstimate(
  optimistic: number,
  mostLikely: number,
  pessimistic: number
): { expected: number; standardDeviation: number; range95: { low: number; high: number } } {
  // PERT formula: (O + 4M + P) / 6
  const expected = (optimistic + 4 * mostLikely + pessimistic) / 6;
  // Standard deviation: (P - O) / 6
  const standardDeviation = (pessimistic - optimistic) / 6;
  // 95% confidence interval: expected ± 2 * SD
  return {
    expected: Math.round(expected * 10) / 10,
    standardDeviation: Math.round(standardDeviation * 10) / 10,
    range95: {
      low: Math.round((expected - 2 * standardDeviation) * 10) / 10,
      high: Math.round((expected + 2 * standardDeviation) * 10) / 10
    }
  };
}

// Example: Estimate for building a search feature
const searchFeatureEstimate = pertEstimate(
  3,   // Optimistic: 3 days (simple Elasticsearch setup)
  7,   // Most Likely: 7 days (standard implementation)
  15   // Pessimistic: 15 days (unexpected data issues)
);
// Result: expected = 7.3 days, SD = 2.0, 95% range = 3.3 - 11.3 days

// Velocity-based Sprint Forecasting
interface SprintForecast {
  sprintNumber: number;
  velocity: number; // story points completed
}

function forecastCompletion(
  historicalVelocity: SprintForecast[],
  remainingPoints: number
): { sprintsNeeded: number; expectedDate: Date; range: { best: number; worst: number } } {
  const velocities = historicalVelocity.map(s => s.velocity);
  const avgVelocity = velocities.reduce((a, b) => a + b, 0) / velocities.length;
  const minVelocity = Math.min(...velocities);
  const maxVelocity = Math.max(...velocities);

  const sprintsNeeded = Math.ceil(remainingPoints / avgVelocity);
  const bestCase = Math.ceil(remainingPoints / maxVelocity);
  const worstCase = Math.ceil(remainingPoints / minVelocity);

  const today = new Date();
  const expectedDate = new Date(today.getTime() + sprintsNeeded * 14 * 24 * 60 * 60 * 1000);

  return { sprintsNeeded, expectedDate, range: { best: bestCase, worst: worstCase } };
}

// Example
const velocity: SprintForecast[] = [
  { sprintNumber: 1, velocity: 28 },
  { sprintNumber: 2, velocity: 34 },
  { sprintNumber: 3, velocity: 31 },
  { sprintNumber: 4, velocity: 36 },
  { sprintNumber: 5, velocity: 33 },
];
const forecast = forecastCompletion(velocity, 120);
// avg velocity = 32.4, sprints needed = 4, range: 4-5 sprints

// Planning Poker Simulation
interface PlanningPokerRound {
  storyId: string;
  votes: { member: string; points: number }[];
  consensus: number | null;
  discussion: string;
}

function analyzePlanningPokerVotes(
  votes: { member: string; points: number }[]
): { median: number; spread: number; needsDiscussion: boolean } {
  const points = votes.map(v => v.points).sort((a, b) => a - b);
  const median = points[Math.floor(points.length / 2)];
  const spread = Math.max(...points) - Math.min(...points);

  // If spread is more than 2 Fibonacci numbers apart, discussion needed
  const fibSequence = [1, 2, 3, 5, 8, 13, 21];
  const minIdx = fibSequence.indexOf(Math.min(...points));
  const maxIdx = fibSequence.indexOf(Math.max(...points));
  const needsDiscussion = maxIdx - minIdx > 2;

  return { median, spread, needsDiscussion };
}

// T-Shirt to Points Mapping
const tshirtToPoints: Record = {
  'XS': { points: 1, days: '< 1 day' },
  'S':  { points: 2, days: '1-2 days' },
  'M':  { points: 5, days: '3-5 days' },
  'L':  { points: 8, days: '1-2 weeks' },
  'XL': { points: 13, days: '2-3 weeks' },
  'XXL': { points: 21, days: 'Split this story!' },
};