Adaptive ETA#

Never leave the user waiting in silence. Promise a time, track it with a real clock, correct it honestly, and learn from the gap.

You cannot feel time passing between tool calls — the script is your clock. Trust its numbers over your sense of progress.

When to activate#

Expected durationWhat to do< 30s, or a direct answerNothing. Just do it.30s – 2 minOne line up front ("About a minute."). No timer.> 2 min, or ≥ 4 tool callsFull protocol below.

When unsure, lean toward the lighter tier. An ETA on a trivial task is noise.

Script#

scripts/timer.py sits next to this file. Call it by absolute path (resolve this skill's directory once), e.g. python3 <skill-dir>/scripts/timer.py check. State is stored in ~/.adaptive-eta/ (override with ADAPTIVE_ETA_HOME); add --task <id> only if you run parallel timers.

CommandWhenstart --eta <sec> --label "<what>"Right after estimating, before the first real stepcheckAt each step boundary (see below)revise --eta <remaining sec> --reason "<why>"After telling the user a new estimate. Keeps the original ETA for the 3× rulestop (or stop --outcome aborted)When the work ends, before the final reportcalibrateOptional; shows how accurate past estimates were

Protocol#

1. Estimate. Break the task into 3–5 steps, estimate each, sum, add ~20% buffer. Run start. If it prints a CALIBRATION line, your past estimates were off — use its suggested figure and run the revise it shows.

2. Announce. One or two lines, in the user's language: total time and the steps. Round honestly; a range is fine.

About 5 minutes: read the 12 files (~1 min), draft the changes (~3 min), run tests (~1 min).

3. Check at step boundaries — not around every tool call. Run check when you finish a planned step, and before starting anything that may block for more than a minute (long builds, big downloads). Act on the status:

STATUSActionON_TRACKContinue. Say nothing.THRESHOLD_REACHED≥80% of the window used. If nearly done, finish. Otherwise re-estimate, tell the user, revise.EXPIREDTell the user what is slower than expected and the new remaining time, then revise.OVERRUNOver 3× the original estimate. Stop and ask: continue, cut scope, or stop? Wait for an answer.NOT_RUNNING / STALENo live timer. start again if work continues.

An update names the cause, not just a number:

Slower than planned — the test suite takes ~4 min per run. About 6 more minutes.

4. Deliver. Run stop, then add its REPORT line in one short line at the end of the result:

Estimated 5m · actual 7m20s · 1 revision

Rules#

• Report real progress only. Never claim a step is done to stay on schedule.
• At most one update per step unless the status gets worse. Do not narrate the timer.
• If you cannot speak during a single long command, say so before it starts ("the build blocks for ~3 min").
• If the user changes the scope, re-estimate and revise — that is not an overrun.
• Always stop, including when the task fails or the user cancels ( --outcome aborted). That keeps calibration honest.