/ase-task-estimate

name: ase-task-estimate
argument-hint: "[--help|-h] [--force|-f] [--dry-run|-d] [--all|-a] [--calibrate|-c [--save|-s]] [<id> ...]"
description: >
    Estimate the effort of the current, given, or all unestimated task
    plans as T-shirt sizes (XS, S, M, L, XL) of expected human time, and
    store it in the "Effort:" frontmatter key, or calibrate the estimation
    against the actual human time of the finished tasks. Use when the user
    wants to "estimate", "size", or "gauge the effort" of a "task" or
    "plan", or to "calibrate" the effort estimation.
user-invocable: true
disable-model-invocation: false
effort: high

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

<purpose name="ase-task-estimate"> Estimate the Effort of a Task Plan </purpose>

<expand name="getopt" arg1="ase-task-estimate" arg2="--force|-f --dry-run|-d --all|-a --calibrate|-c --save|-s"> $ARGUMENTS </expand>

<objective> *Estimate* the effort of task plans as T-shirt sizes of expected human time. </objective>

@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md

Procedure ---------

<define name="effort-scores">

Derive the *scores* of the plan <plan/> (the body only, never the frontmatter or backmatter), skipping every bullet-point in the *inert* checkbox states `[-]` and `[>]` entirely, while all other checkbox states (including `[x]`, as the effort covers the *entire* lifecycle of the task) count alike. A bullet-point *without* a type (like in a legacy plan) counts with the types following from its section: `DOM` or `IFC` for a context or specification section (but *nothing* for a pure rationale like a *why*), `ARC` or `IMP` for a changes or design section, and `REG` or `CON` for a verification section. Do not output anything.

1. *Attention score*: set <attention/> to the sum of the weights of all counted bullet-points, with the weights `DOM` 5.0, `IFC` 4.0, `ARC` 3.0, `IMP` 1.0, `REG` 0.5, and `CON` 1.0, each *multiplied* by the *item count* of the bullet-point: the number of *distinct* requirements, behaviors, or changes it states (at least `1`), like one per independent statement or per enumerated element, so a dense bullet-point stating ten key bindings counts ten times, while a bullet-point stating a single fact counts once. Set <minutes-attention/> to <attention/> times <factor/>.

2. *Volume score*: *predict* the code impact of the counted `ARC` and `IMP` bullet-points *strictly read-only* from the plan and the code base (never change, stage, or commit anything), *disregarding* any already existing change set of the task (its uncommitted changes, its branch, or its change set attachment): *never* measure the volume from such a change set, so estimations before and after the implementation stay comparable. Set <files/> to the number of files they touch (or create) -- the files named by the bullet-points *plus* the files following from them, like call sites, documentation, manual pages, and generated catalogs -- and <lines/> to the estimated number of changed lines, sizing new files after comparable existing ones and changes after the code they touch, and <new-lines/> to the part of <lines/> in newly created files. Set <minutes-volume/> to <files/> times <file-minutes/> plus <lines/> plus twice <new-lines/> times <line-minutes/>, so a newly written line weighs *three* times a changed one. As a plan describes the straightforward path only, while the edge cases, the error handling, and the polishing of the realization regularly multiply its size, <line-minutes/> already covers this growth, hence do *not* inflate the predicted lines themselves.

3. *Base size*: set <minutes/> to <minutes-attention/> plus <minutes-volume/>, and set <size/> to the *smallest* size of `XS`, `S`, `M`, and `L` whose upper band bound in <scale/> is greater than or equal to <minutes/>, or to `XL` if <minutes/> exceeds all bounds.

</define>

1. **Determine Operation:**

1. Set <ids/> to the whitespace-separated tokens of <getopt-arguments/>, each with a trailing `:` removed. Inherit the always existing <ase-task-id/>, <ase-session-id/>, <ase-project-task-lifecycle/>, and <ase-project-boxing/> from the current context. Do not output anything.

2. Validate the arguments and options:

• If a token <token/> of <ids/> does *not* match the regexp

`^[a-zA-Z0-9#][a-zA-Z0-9#_-]*$`, only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ☻ skill: **ase-task-estimate**, ▶ ERROR: invalid task id: **<token/>** </template>

• If <getopt-option-all/> is `true` and <ids/> is *not* empty,

only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ☻ skill: **ase-task-estimate**, ▶ ERROR: option `--all` takes no task ids </template>

• If <getopt-option-calibrate/> is `true` and <ids/> is *not*

empty or any of <getopt-option-all/>, <getopt-option-force/>, and <getopt-option-dry-run/> is `true`, only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ☻ skill: **ase-task-estimate**, ▶ ERROR: option `--calibrate` takes no task ids and excludes `--all`, `--force`, and `--dry-run` </template>

• If <getopt-option-save/> is `true` and

<getopt-option-calibrate/> is *not* `true`, only output the following <template/> and then immediately *STOP* processing the entire current skill:

<temp