| name | agent-estimation |
| description | Triggers: "estimate effort", "agent time", "how long", "effort bucket", "estimate rounds", "size this work", "agent estimation". Estimate agent work in tool-call rounds (not human hours). Use whenever an LLM is asked how long a coding task will take. |
Agent Estimation — Rounds-First Effort Sizing
When this skill is invoked, immediately say:
"Using Agent Estimation skill. Primary unit: tool-call rounds. Wallclock is derived."
Why this exists
Ask Claude, Cursor, or any other coding agent how long a refactor will take. It will answer in hours or days, with confidence, and the answer will be made up. The training data is full of human engineers writing about human workflows in human units. The model has nothing else to anchor on, so it borrows the wrong unit.
This skill replaces that frame. The agent estimates in tool-call rounds (its native unit) and converts to wallclock at the very end, as a range.
Use this whenever you are producing effort estimates for agent-executed work: in plans, reviews, GitHub issues, stabilization orders, anything.
Core principle
One round = one think → search/edit → execute/verify → fix-if-needed cycle.
A round is one turn of useful agent work. It does not depend on model speed, thinking budget, or wallclock elapsed time. It is observable: you can count rounds in a transcript and check whether the estimate was right.
Estimate = base rounds × risk coefficient → wallclock range.
Bucket table
| Bucket | Rounds | What fits |
|---|
trivial | 1-2 | Rename, typo, single-line fix, add a comment |
small | 3-5 | Multi-file mechanical change with tests |
medium | 6-10 | Read 5-10 files, careful refactor, verify |
large | 11-20 | Cross-cutting work with a plan gate |
xlarge | 21+ | Decompose first |
Rule of thumb: if you cannot picture executing the work in 20 rounds or fewer, decompose before estimating. Long unbroken tasks die at context limits.
Risk coefficients
Multiply base rounds by the highest applicable factor:
| Factor | Multiplier | When |
|---|
| Clear spec, isolated change | 1.0× | Baseline |
| Spec has gaps, touches 3+ modules | 1.3× | Cross-module |
| High ambiguity, unknown third-party | 1.6× | Spec needs clarification mid-flight |
| Spike or exploration | 2.0× | Outcome not defined upfront |
Example: 5 rounds × 1.3× = 6.5 rounds adjusted.
Wallclock conversion
Default: rounds × 2-4 min/round. Always express as a range, never a point.
| Modifier | Effect |
|---|
| External calls (API, deploy, CI) | Add wallclock equal to external wait. Do not add rounds. |
| Approval gates (human review) | Add human-cycle wallclock (hours or days). Rounds unchanged. |
| Subagent parallelism | Wallclock = max(parallel subagent rounds) + 1-2 coordination rounds |
| Higher reasoning effort setting | Use upper end of the 2-4 min range |
Example: 6.5 adjusted rounds × 2-4 min = ~13-26 min wallclock.
When agent-time does not apply
Use human-time or wall-time when:
- The task is wall-time dominated (long CI run, deploy waits, human approval). Rounds are near-zero but wallclock is long.
- The task requires human pairing (onboarding, stakeholder meetings).
- The estimate is for roadmap or capacity planning against human developer FTEs.
Always flag those with human-time: so readers do not mistake them for agent-time.
Worked example — multi-module plan
Use this template when decomposing. Skip it for inline single-item estimates.
## Estimation: Sunset legacy auth middleware
| Module | Base rounds | Risk | Adjusted |
|--------|-------------|------|----------|
| 1. Feature flag + routing shim | 3 | 1.0× | 3 |
| 2. Port 3 remaining flows | 6 | 1.3× | 7.8 |
| 3. Migrate tests | 4 | 1.0× | 4 |
| 4. Remove dead code | 2 | 1.0× | 2 |
| 5. Verify and capture lessons | 2 | 1.0× | 2 |
Base total: 17 rounds
Integration overhead: +2
Adjusted total: ~19 rounds
Wallclock range: 19 × 2-4 min = ~40-75 min agent-time
External waits: CI run (+5-10 min wallclock)
Approval gates: 1 plan approval + 1 PR review (hours-days human wallclock)
Summary: ~19 rounds (~40-75 min agent) + human review loop
Common mistakes
- Estimating in days or weeks. Wrong anchor for agent work.
- Forgetting the range. Point estimates lie. Ranges are honest.
- Mixing agent-time and human-time in the same table without labels. Confusing.
- Skipping risk coefficient on ambiguous specs. Under-estimates bite later.
- Forgetting subagent coordination overhead. Fan out 5 subagents and you still need the fan-in round.
- Using rounds for wall-time-dominated work. CI waits are not agent work.
Hard rules
- Never use
~1d, ~1w, ~1h in an agent-execution context without the human-time: prefix.
- Always include a wallclock range when converting from rounds.
- Always surface the risk coefficient when above 1.0×.
- Decompose tasks above 20 rounds before estimating.
Quick reference
| Step | What |
|---|
| 1 | Decompose into modules if >20 rounds |
| 2 | Count base rounds per module (bucket table) |
| 3 | Apply risk coefficient per module |
| 4 | Sum adjusted rounds + integration overhead |
| 5 | Convert: rounds × 2-4 min wallclock range |
| 6 | Flag external waits and approval gates separately |
| 7 | Present as: N rounds (~X-Y min agent) |
Completion
When used to produce an estimate, close with:
"Estimated: {N} rounds (~{low}-{high} min agent-time). Risk: {coefficient}. External / approval waits: {list or 'none'}."
References
License
MIT.
