Estimates and Capacity

Estimates and Capacity

handoff-mcp separates the raw human-effort estimate you record on a task from the AI-effort hours used in scheduling and metrics. You always enter the raw estimate; the server scales it when aggregating.

Required estimates

When settings.require_estimate_hours is true (the default), handoff_update_task rejects creating or updating a leaf task (one with no children) in todo / in_progress / review / done unless it has schedule.estimate_hours > 0.

Exemptions:

• Parent tasks (tasks that have children) — their effort is the sum of their leaves.
• blocked and skipped tasks.
• A task that already carries an estimate satisfies the requirement on subsequent updates.

Set settings.require_estimate_hours = false (via handoff_update_config) to opt out entirely.

Enter the raw human-effort estimate — the time the work would take a person. Never pre-multiply it yourself.

The AI-effort multiplier

settings.ai_estimate_multiplier (default 0.2) models how much faster the work goes when an AI agent does it. It is applied at aggregation time, never written back onto the task, so raw estimates are preserved.

It surfaces in two places:

• handoff_get_metrics reports ai_estimate_multiplier, total_adjusted_estimate_hours (the project's raw estimate total × the multiplier), and a per-milestone adjusted_estimate_hours.
• handoff_get_capacity multiplies each task's raw estimate by the multiplier when distributing effort across days. remaining_hours, which represents actual progress, is used as-is.

Negative multipliers are rejected by handoff_update_config. To change it:

{ "settings.ai_estimate_multiplier": 0.3 }

Worked example

A task estimated at 10 human-hours, with the default multiplier 0.2:

• The task keeps estimate_hours = 10.
• handoff_get_metrics counts it as 2 adjusted hours toward the totals.
• handoff_get_capacity schedules 2 hours of work across the calendar.

Logging time and scheduling

• Use handoff_log_time to record hours worked — it atomically adds to actual_hours and deducts from remaining_hours. Prefer it over editing actual_hours directly.
• Use handoff_get_capacity before scheduling to see available hours per day and per assignee, respecting the project calendar and per-assignee overrides.
• Use handoff_auto_schedule to compute task dates from dependencies, estimates, and capacity. Run it with dry_run: true first to preview the changes.