agent-estimation

使用代理自己的操作单位（工具调用轮次）而不是人工时间来准确估计 AI 代理的工作量。当被要求估计、范围、计划或评估编码任务将花费多长时间时使用。防止代理锚定人类开发人员时间表并严重高估的常见故障模式。输出包含轮数、风险因素和最终挂钟转换的结构化细分。

# Agent Work Estimation Skill

## Problem

AI coding agents systematically overestimate task duration because they anchor to human developer timelines absorbed from training data. A task an agent can complete in 30 minutes gets estimated as "2-3 days" because that's what a human developer forum post would say.

## Solution

Force the agent to estimate from its own operational units — **tool-call rounds** — and only convert to human wallclock time at the very end.

## Core Units

| Unit | Definition | Scale |
|------|-----------|-------|
| **Round** | One tool-call cycle: think → write code → execute → verify → fix | ~2-4 min wallclock |
| **Module** | A functional unit built from multiple rounds until usable | 2-15 rounds |
| **Project** | All modules + integration + debugging | Sum of modules × integration factor |

A **Round** is the atomic unit. It maps directly to one iteration of:
1. Agent reasons about what to do
2. Agent writes/edits code
3. Agent runs the code or a test
4. Agent reads the output
5. Agent decides if it needs to fix something (if yes → next round)

## Estimation Procedure

When asked to estimate a task, follow these steps in order:

### Step 1: Decompose into Modules

Break the task into functional modules. Each module should be independently buildable and testable. Ask yourself: "What are the distinct pieces I would build one at a time?"

### Step 2: Estimate Rounds per Module

For each module, estimate the number of rounds using these anchors:

| Pattern | Typical Rounds | Examples |
|---------|---------------|----------|
| **Boilerplate / known pattern** | 1-2 | CRUD endpoint, config file, standard API client |
| **Moderate complexity** | 3-5 | Custom UI layout, state management, data pipeline |
| **Exploratory / under-documented** | 5-10 | Unfamiliar framework, platform-specific APIs, complex integrations |
| **High uncertainty** | 8-15 | Undocumented behavior, novel algorithms, multi-system debugging |

Key calibration rules:
- If you can generate the code in one shot and it will likely run → **1 round**
- If you'll need to generate, run, see an error, and fix → **2-3 rounds**
- If the library/framework has sparse docs and you'll be guessing → **5+ rounds**
- If it involves platform permissions, OS-level APIs, or environment-specific behavior the user must manually verify → add **2-3 rounds**

### Step 3: Assign Risk Coefficients

Each module gets a risk coefficient that inflates its round count:

| Risk Level | Coefficient | When to Apply |
|------------|------------|---------------|
| **Low** | 1.0 | Mature ecosystem, clear docs, agent has strong pattern match |
| **Medium** | 1.3 | Minor unknowns, may need 1-2 extra debug rounds |
| **High** | 1.5 | Sparse docs, platform quirks, integration unknowns |
| **Very High** | 2.0 | Possible dead ends, may need to change approach entirely |

### Step 4: Calculate Totals

```
Module effective rounds = base rounds × risk coefficient
Project rounds = Σ(module effective rounds) + integration rounds
Integration rounds = 10-20% of base total (for wiring modules together)
```

### Step 5: Convert to Wallclock Time

Only at the very end, convert to human time:

```
Wallclock time = project rounds × minutes_per_round
```

Default `minutes_per_round` = **3 minutes** (includes agent generation time + user review time).

Adjust this parameter based on context:
- Fast iteration, user barely reviews → 2 min/round
- Complex domain, user carefully reviews each step → 4 min/round
- User needs to manually test (mobile, hardware, permissions) → 5 min/round

## Output Format

Always output the estimation in this exact structure:

```markdown
### Task: [task name]

#### Module Breakdown

| # | Module | Base Rounds | Risk | Effective Rounds | Notes |
|---|--------|------------|------|-----------------|-------|
| 1 | ...    | N          | 1.x  | M               | why   |
| 2 | ...    | N          | 1.x  | M               | why   |

#### Summary

- **Base rounds**: X
- **Integration**: +Y rounds
- **Risk-adjusted total**: Z rounds
- **Estimated wallclock**: A – B minutes (at N min/round)

#### Biggest Risks
1. [specific risk and what could blow up the estimate]
2. [...]
```

## Anti-Patterns to Avoid

These are the failure modes this skill exists to prevent:

1. **Human-time anchoring**: "A developer would take about 2 weeks..." → NO. Start from rounds.
2. **Padding by vibes**: Adding time "just to be safe" without specific risk rationale → NO. Use risk coefficients.
3. **Confusing complexity with volume**: 500 lines of boilerplate ≠ hard. One line of CGEvent API ≠ easy. Estimate by uncertainty, not line count.
4. **Forgetting integration cost**: Modules work alone but break together. Always add integration rounds.
5. **Ignoring user-side bottlenecks**: If the user must manually grant permissions, restart an app, or test on a device, that's extra round time. Adjust `minutes_per_round`, don't add phantom rounds.

## Calibration Reference

Here are example projects with known round counts to help calibrate:

See `references/calibration-examples.md` for detailed examples across project types.

## Eval Prompts

See `evals/evals.json` for test cases to validate estimation accuracy.

---

## 中文说明

# 代理工作量估算技能

## 问题

AI 编码代理系统性地高估任务时长，因为它们锚定于从训练数据中吸收的人类开发者时间表。一项代理 30 分钟就能完成的任务会被估算为“2-3 天”，因为人类开发者论坛帖子就是这么说的。

## 解决方案

迫使代理从它自身的操作单位 —— **工具调用轮次（rounds）** —— 进行估算，并且只在最后才转换为人类挂钟时间。

## 核心单位

| 单位 | 定义 | 规模 |
|------|-----------|-------|
| **Round（轮次）** | 一个工具调用周期：思考 → 编写代码 → 执行 → 验证 → 修复 | 约 2-4 分钟挂钟时间 |
| **Module（模块）** | 由多轮构建直至可用的功能单元 | 2-15 轮 |
| **Project（项目）** | 所有模块 + 集成 + 调试 | 各模块之和 × 集成系数 |

**Round** 是原子单位。它直接对应以下一次迭代：
1. 代理推理要做什么
2. 代理编写/编辑代码
3. 代理运行代码或测试
4. 代理读取输出
5. 代理判断是否需要修复某处（如果需要 → 进入下一轮）

## 估算流程

当被要求估算某项任务时，按顺序遵循以下步骤：

### 第 1 步：分解为模块

将任务拆分为功能模块。每个模块都应能够独立构建和测试。问自己：“我会逐个构建哪些不同的部分？”

### 第 2 步：估算每个模块的轮数

对每个模块，使用以下锚点估算轮数：

| 模式 | 典型轮数 | 示例 |
|---------|---------------|----------|
| **样板代码 / 已知模式** | 1-2 | CRUD 端点、配置文件、标准 API 客户端 |
| **中等复杂度** | 3-5 | 自定义 UI 布局、状态管理、数据管道 |
| **探索性 / 文档不足** | 5-10 | 不熟悉的框架、平台特定 API、复杂集成 |
| **高度不确定** | 8-15 | 无文档的行为、新颖算法、多系统调试 |

关键校准规则：
- 如果你能一次性生成代码且很可能就能运行 → **1 轮**
- 如果你需要生成、运行、看到错误并修复 → **2-3 轮**
- 如果库/框架文档稀缺、你需要靠猜测 → **5+ 轮**
- 如果涉及平台权限、操作系统级 API，或用户必须手动验证的环境特定行为 → 增加 **2-3 轮**

### 第 3 步：分配风险系数

每个模块都会得到一个用于放大其轮数的风险系数：

| 风险级别 | 系数 | 何时应用 |
|------------|------------|---------------|
| **低** | 1.0 | 生态成熟、文档清晰、代理有强模式匹配 |
| **中** | 1.3 | 小的未知项，可能需要额外 1-2 个调试轮次 |
| **高** | 1.5 | 文档稀缺、平台怪癖、集成未知项 |
| **非常高** | 2.0 | 可能走入死胡同，可能需要彻底改变方法 |

### 第 4 步：计算总数

```
Module effective rounds = base rounds × risk coefficient
Project rounds = Σ(module effective rounds) + integration rounds
Integration rounds = 10-20% of base total (for wiring modules together)
```

### 第 5 步：转换为挂钟时间

仅在最后，才转换为人类时间：

```
Wallclock time = project rounds × minutes_per_round
```

默认 `minutes_per_round` = **3 分钟**（包含代理生成时间 + 用户审阅时间）。

根据上下文调整此参数：
- 快速迭代、用户几乎不审阅 → 2 分钟/轮
- 复杂领域、用户仔细审阅每一步 → 4 分钟/轮
- 用户需要手动测试（移动端、硬件、权限）→ 5 分钟/轮

## 输出格式

始终以这个确切结构输出估算：

```markdown
### Task: [task name]

#### Module Breakdown

| # | Module | Base Rounds | Risk | Effective Rounds | Notes |
|---|--------|------------|------|-----------------|-------|
| 1 | ...    | N          | 1.x  | M               | why   |
| 2 | ...    | N          | 1.x  | M               | why   |

#### Summary

- **Base rounds**: X
- **Integration**: +Y rounds
- **Risk-adjusted total**: Z rounds
- **Estimated wallclock**: A – B minutes (at N min/round)

#### Biggest Risks
1. [specific risk and what could blow up the estimate]
2. [...]
```

## 应避免的反模式

这些正是本技能存在以防止的故障模式：

1. **人类时间锚定**：“一名开发者大约需要 2 周……” → 不行。从轮次开始。
2. **凭感觉加余量**：在没有具体风险依据的情况下“为保险起见”增加时间 → 不行。使用风险系数。
3. **混淆复杂度与体量**：500 行样板代码 ≠ 困难。一行 CGEvent API ≠ 简单。按不确定性估算，而非按行数。
4. **遗忘集成成本**：模块单独工作但放在一起就崩溃。始终增加集成轮次。
5. **忽视用户侧瓶颈**：如果用户必须手动授予权限、重启应用或在设备上测试，那都是额外的轮次时间。调整 `minutes_per_round`，而不要添加虚构的轮次。

## 校准参考

以下是一些具有已知轮数的示例项目，帮助进行校准：

不同项目类型的详细示例参见 `references/calibration-examples.md`。