---
name: agent-effort-estimation
description: >
  Translate a coding agent's conventional human-hour estimate into agent labor
  and schedule wall-clock using empirical calibration from completed traces.
  Preserve the agent's task breakdown, range, assumptions, and dependencies;
  then apply declared parallelism. After shipping, compare with a look-back
  accounting pass so the conversion improves over time.
---

# Agent Effort Estimation (public / portable)

Forecast how long **upcoming** agent-assisted work will take **before** it
starts by translating the estimate the agent already knows how to produce.

Coding agents often return a conventional senior-developer estimate in human
hours. Keep that estimate and its work breakdown. This skill changes the units:

```text
agent's human-hour estimate
  ÷ trace-derived conversion
  = agent labor
  → dependency-aware critical path
  = schedule wall-clock
```

This skill is intentionally free of personal infrastructure, private paths, and
account identifiers. Point it at *your* ledger and *your* session artifacts.
The coefficients below are a real snapshot from one personal workflow, not
industry benchmarks. They are included so the draft is reproducible and
criticizable, not so they can be copied without recalibration.

> **Direction matters.** This looks **forward** (forecast). After work ships, run a
> **look-back** pass on the git range (or session receipts) and record actuals.
> Forecast quality rises only if the ledger grows.

---

## The two numbers (do not conflate them)

| Output | Meaning | Parallelism |
|--------|---------|-------------|
| **Labor** | Total agent effort (Σ item agent-hours) | Always **sum** |
| **Schedule wall** | Attended / calendar time until done | **Critical path** under `max_parallel` |
| **Human-equivalent** | Senior-solo human hours for the same volume | Always **sum** (effort, not calendar) |

A four-hour *budget* is a **schedule wall** SLA.
Summing lane times without a fan-out model overstates calendar time when work is parallel.

**Rule:** every estimate reports **Labor** and **Schedule wall** as separate lines.

---

## Inputs you may use (session-grounded, no PII required)

Prefer measured session signals over gut feel. Use whatever your harness records:

| Signal | Examples (generic) | Use for |
|--------|--------------------|---------|
| Agent estimate | Human-hour low/mid/high by item | Primary conversion input |
| Work breakdown | Plan slices, graph nodes, task titles | Items to estimate |
| Size proxy | Expected net lines, files touched, T1–T5 complexity | Cross-check the human estimate |
| Parallel structure | Dependency graph, “lanes”, max concurrent workers | Schedule wall |
| Historical rates | Your private JSONL/JSON ledger of past items | Calibration |
| After ship | `git log` / diff stats for the branch range | Look-back actuals |

**Do not paste into public posts:** absolute home paths, hostnames, emails, API keys,
customer names, private repo URLs, raw transcript dumps with secrets.

**Safe to cite publicly:** rounded hours, work types, n of prior samples, multipliers,
anonymized method (“four parallel workers”, “critical path ≈ max lane + integrate”).

---

## Work types

Classify each item:

`feature` · `bug` · `chore` · `docs` · `research` · `orchestration` · `infra`

---

## Current calibration snapshot (real, anonymized)

Calibration window: **2026-06-17 through 2026-07-14**
Ledger rows: **243**
Rates version: **v2-file-facts**
Observed human-equivalent → attended-agent multiplier: **43.3×**

The multiplier means:

```text
agent_labor_h ≈ agent_estimated_human_h / 43.3
```

This is a provisional coefficient from one person’s repositories, tools,
models, and attendance assumptions. It will drift. It may also be measuring
the surrounding workflow as much as agent capability.

The current work-type summary is reproduced below without private item names:

| Work type | n | Median human-eq h | p25–p75 human-eq h | Median net lines | Derived median agent h |
|-----------|--:|------------------:|--------------------:|-----------------:|-----------------------:|
| Bug | 64 | 13.43 | 0.00–120.62 | 351.5 | 0.310 |
| Chore | 12 | 0.81 | 0.00–32.14 | 26.0 | 0.019 |
| Docs | 4 | 0.95 | 0.00–3.83 | 33.5 | 0.022 |
| Feature | 115 | 0.00 | 0.00–4.00 | 0.0 | 0.000 |
| Infrastructure | 18 | 0.00 | 0.00–4.78 | 0.0 | 0.000 |
| Orchestration | 26 | 0.00 | 0.00–8.53 | 0.0 | 0.000 |
| Research | 2 | 95.38 | 35.14–155.61 | 2,522.5 | 2.203 |

**Do not use a zero median as a zero-time forecast.** In this snapshot, zero
rows mostly mean the harvested work item did not retain a countable diff after
exclusions or did not map cleanly to the item. Fall back to file-tier sizing
for those types. `docs` and `research` also have fewer than five samples and
remain low-confidence.

The wide ranges are not a formatting problem. They are a warning that work
type alone is too coarse and that the ledger still needs better segmentation
and true wall-clock measurements.

---

## Complexity tiers (cross-check or fallback)

Senior developer, solo, full context (conservative / credible):

| Tier | Category | Examples | Human rate (lines/hr) |
|------|----------|----------|----------------------:|
| T1 | Trivial | Config, boilerplate, generated, CI yaml | 60 |
| T2 | Low | Simple UI, CRUD, tests, docs, scripts | 35 |
| T3 | Medium | Business logic, data layer, APIs | 22 |
| T4 | High | Architecture, migrations, state machines | 14 |
| T5 | Specialist | Parsers, systems, crypto, GPU | 10 |

When uncertain, round **up** one tier.

---

## How it works

### 1. Capture the agent's conventional estimate

Before showing the agent the trace coefficient, ask it to estimate the work as
it normally would for an experienced solo developer. This reduces anchoring on
the desired agent-time result.

Record for each item:

- human-hour low / midpoint / high;
- assumptions and exclusions;
- dependencies and serial gates;
- the agent's confidence.

The midpoint is the default conversion input. Preserve the low and high values
to form the initial confidence cone.

### 2. Describe and cross-check the items

For each unit of work:

- `work_type`
- size: expected **net lines** *or* tier T1–T5 + rough file count
- optional `parallel_group` (items that can run concurrently share a group id)
- optional `depends_on` (item ids) for critical path.

Use the file-tier calculation as a cross-check, not as an automatic replacement
for the agent's estimate. If the agent's human-hour midpoint and the tier model
differ by more than 2×, widen the range and explain the disagreement.

### 3. Load rates from *your* ledger
Maintain a private append-only ledger (example shape only):

```json
{"id":"anon-001","work_type":"chore","net_lines":400,"human_hours":18.5,"agent_walltime_h":0.9,"speed_multiplier":20.6,"merged":"2026-01-15"}
```

Derive per `work_type` (need n ≥ 5 for medium confidence):

- median agent hours per item **or** per 100 net lines
- median human-hours
- p25–p75 agent hours (cone)
- median net lines (for line-scaling)

If n < 5 for a type: say so, widen the cone, fall back to tier table for human-eq, and mark **low confidence**.

If the median is zero because the source row has no countable diff, treat the
rate as **unusable**, not fast. Use the tier fallback and record the data-quality
gap for the next calibration pass.

### 4. Convert each item

**Primary conversion from the agent's own estimate:**

```text
agent_labor_h ≈ agent_estimated_human_h / 43.3
```

Apply the same conversion to the low and high human-hour inputs to preserve the
agent's original uncertainty.

**Human-equivalent cross-check from file tiers:**

```text
human_equivalent_h = Σ(inserted_lines_in_tier / tier_rate)
```

Keep deletion credit separate:

```text
cleanup_credit_h = deleted_lines / 120
```

When a nonzero work-type row has a reasonable sample size and comparable item
size, a second projection is:

```text
agent_labor_h ≈
  (item_net_lines / median_net_lines_for_type)
  × median_agent_h_for_type
```

Compare the agent-estimate conversion, file-tier cross-check, and work-type
projection. If any differ by more than 2×, widen the range and explain the
disagreement rather than averaging it away.

**Human-equivalent:**

```text
human_h ≈ (item_net_lines / median_net_lines_for_type) × median_human_h_for_type
```

(or net_lines / tier_rate when ledger is thin)

**Cone:** scale p25–p75 the same way; if n < 5 use roughly 0.3×–3.5× median labor.

### 5. Aggregate

```text
Labor total     = Σ agent_labor_h          (all items)
Human-eq total  = Σ human_h               (all items)
Schedule wall   = critical_path(agent_labor_h, depends_on, max_parallel)
```

**Critical path (simple, good enough):**

1. If you only know `max_parallel = K` and items are independent:
   `schedule_wall ≈ (Σ agent_labor_h / K)` is a **lower bound only** (optimistic). Prefer (2).
2. Better: assign items to parallel groups / graph nodes.
   `schedule_wall ≈ sum over serial stages of max(agent_labor_h in that stage)`
   Example stages: `[parallel W1|W2|W3|W4] → [integrate] → [closeout]`
   → `max(W1..W4) + integrate + closeout`
3. Add fixed serial overhead you always pay (dispatch, merge, live verify) as its own items.

**Never** report only Σ agent hours as “how long until we finish” when `max_parallel > 1`.

### 6. Cite the basis
Every estimate names the agent's human-hour input, n, rate source, and whether
wall is critical-path or naïve sum:

> chore, n=8, median 0.19h agent / 586 ln → 1100 ln ⇒ 0.36h labor (0.16–1.99h cone).
> Schedule wall: max_parallel=4, critical path 0.42h (not Σ 0.90h).

---

## Output format (required)

```markdown
## Estimate: [work description]

max_parallel: K
method: critical-path | sequential-sum-only (flag if sequential)

| Item | Type | Size | Parallel group | Agent labor h | Cone (p25–p75) | Human-eq h |
|------|------|-----:|----------------|--------------:|---------------:|-----------:|
| ...  | chore | 400 ln | A | 0.4 | 0.2–0.9 | 18 |
| **Labor total (Σ)** | | | | **X.X** | | **NN** |
| **Schedule wall** | | | | **Y.Y** | **lo–hi** | — |

Basis: ledger window YYYY-MM-DD..YYYY-MM-DD, N items; types with n<5 marked low-confidence.
Input: agent-produced human-hour estimate recorded before conversion.
Notes: [serial gates, integration risk, unknown deps]
```

Optional one-liner for humans:

```text
Budget SLA (schedule wall): ≤ Zh   |   Forecast schedule wall: Y.Yh   |   Labor: X.Xh   |   Human-eq: NNh
```

---

## Closing the loop (after the work ships)

1. Measure **actual schedule wall** (session start → done / merge / verify green).
2. Measure **actual labor proxy** if available (sum of worker durations); else skip.
3. Run look-back on the git range: insertions/deletions, file tiers → human-eq actual.
4. Append one anonymized ledger row (no paths, no user ids).
5. Record estimate accuracy:

```text
forecast_schedule_wall_h vs actual_schedule_wall_h
forecast_human_eq_h vs actual_human_eq_h
```

Large misses (>2×) on schedule wall often mean: hidden serial gates, false independence, or ledger `agent_walltime_h` mixing parallel and sequential sessions.

---

## Anti-patterns

| Don’t | Do |
|-------|-----|
| Treat Σ agent hours as calendar time when lanes run in parallel | Report critical-path schedule wall |
| Invent a multi-day phase plan without a forecast table | Run this skill first |
| Publish raw session transcripts or machine paths | Publish rounded metrics + method |
| Require full estimation for trivial one-file fixes | Skip or one-line T1 guess |
| Use a single global “AI is 50×” multiplier | Calibrate by work_type from your ledger |

---

## Minimal worked example (real reconstructed figures, anonymized)

The agent's conventional estimate, after decomposition and cross-checking, is
**64 human-equivalent hours**. Applying the global trace coefficient:

```text
64 / 43.3 = 1.48 agent-labor hours
```

Four independent lanes + integrate, `max_parallel=4`:

| Item | Labor h |
|------|--------:|
| Lane A (infra) | 0.41 |
| Lane B (docs) | 0.32 |
| Lane C (chore) | 0.36 |
| Lane D (docs) | 0.33 |
| Integrate | 0.06 |

- **Labor total** = 1.48 h
- **Schedule wall** = max(0.41, 0.32, 0.36, 0.33) + 0.06 = **0.47 h**
- **Human-equivalent input** = 64 h

A human “finish in four hours” constraint bounds **schedule wall**, not labor sum.

---

## Public sharing

You may share this skill file as-is. When posting results:

- Prefer **method + rounded metrics** over internal tool names.
- Strip absolute paths, hostnames, emails, and customer data.
- Label figures as **observed**, **forecast**, or **look-back**.

---

## Optional companion (not required)

A separate **look-back effort accounting** pass classifies shipped diffs by tier, computes human-eq, and records agent attended wall-clock so this skill’s rates stay honest. Keep that ledger private; share only aggregates if you publish.

---

*Portable draft · real coefficients from one anonymized personal calibration ·
dual forecast: labor Σ + schedule wall (critical path)*