$LEDGER

1. $CLAUDE_ESTIMATION_DIR

   — explicit override.

2. ~/.claude/estimation

   — the portable default.

$LEDGER/
  ledger/
    chats.ndjson       # one row per Claude Code conversation (mined)
    tasks.ndjson       # one row per unit of work; the reference class lives here
    estimates.ndjson   # one row per quote this skill emitted, for scoring
  calibration.json     # population priors + per-class empirical quantiles

$SKILL/scripts/

extract.mjs

stitch.mjs

digest.mjs

calibrate.mjs

slice.mjs

task.sub_tasks[]

record.mjs

score.mjs

calibrate.mjs

score.mjs

calibrate.mjs

score.mjs

estimates.ndjson

record.mjs

score.mjs

schema: "estimate.v1"

{"schema":"estimate.v1",
 "estimate_id":"2026-08-31-add-oauth-provider",
 "date":"2026-08-31",
 "task":"add-oauth-provider",
 "ticket":null,
 "task_desc_hash":null,
 "features":{"type":"feature-epic","novelty":"adaptation","precedent":"saml-provider"},
 "class":{"neighbors":["example-api/TICKET-3880"],"n":1,"gate":"prior-only"},
 "quoted":{"agent_hours":{"p50":76,"lo":50,"hi":150},
           "human_rounds":{"p50":null,"lo":600,"hi":1000},
           "calendar_days":{"p50":null,"lo":28,"hi":49}},
 "source":"ledger-neighbor+bounded-adjustment"}

• estimate_id

  is the join key

  record.mjs --estimate-id

  takes. Default it to

  <date>-<task>

  . Once a task is recorded against it, the id is written back onto the task row as

  estimate_id

  , so the link is never re-guessed.

• task

  is a slug, and it must be one

  record.mjs

  can find later: the ticket key, the branch name, or the phrase the classifier will summarise the work as. Matching runs

  estimate_id → ticket → task_desc_hash → task_id slug → summary → epic-slice slug → sub-deliverable slug

  , first hit wins. A quote that matched an epic slice is scored against that slice's hours, not the epic's — scoring "the webhook part" against a 76-hour integration would report a 60× miss on a quote that was never about the integration.

  score.mjs

  names the slice in

  sub_task

  when it does this.

• quoted

  carries the three axes the ledger measures —

  agent_hours

  ,

  human_rounds

  ,

  calendar_days

  — and no others. A band quoted in weeks is stored in days. Quote something on every axis you can: an axis with no band is silently unscorable, which is how an estimator ends up with a coverage number built from one axis.

• lo

  /

  hi

  are the band you actually committed to (the P50→P85 span, or the regime-split range).

  score.mjs

  scores coverage at 80% nominal against them.

• p50

  may be null, and then

  score.mjs

  uses the band's log midpoint (

  sqrt(lo*hi)

  ) and flags every ratio derived from it — so a derived centre is never mistaken for something you said.

• task_desc_hash

  — sha256 of the anchor-stripped description. Optional but preferred when there is no ticket: it keeps prose out of the ledger while still matching later.

agent_h_p50

agent_h_band

rounds_band

calendar_weeks_band

stitch.mjs

main

REPORT-2026

isPlausibleTicketKey

eligibleTicketKeys

backfill.mjs

classify.mjs

audit.mjs

• No testable acceptance criteria. Nobody can say what "done" is, in a way a test or a concrete observation could settle.
• No converged implementation strategy. Two or more materially different approaches are still live, and the choice changes the work by more than one bucket.

Not estimable yet — recommend a timeboxed spike. Missing:

<the specific criterion or the unresolved fork>

. Timebox:

<1 bucket on the ladder>

, and the deliverable of the spike is the missing thing, not the feature. Re-run the estimate after the spike; it will be a different (and much tighter) class.

$LEDGER/ledger/tasks.ndjson

1. k = 1–3 nearest neighbours on the feature vector. Small k on purpose — larger k regresses to the mean and destroys what made analogy work.
2. If the tight class has n < 5, widen to the whole

   task_type

   class and say you widened.
3. If still thin, fall back to the population priors in

   calibration.json

   and say the estimate is prior-based.

field_reliability

reliable: true

reliable: false

task_type

task_type

n

epic-slice

calibration.json

reference_classes["epic-slice"]

by_task_type

slice.mjs

task_type

human_rounds ≈ ceil(human_equivalent_minutes / 30)

node $SKILL/scripts/score.mjs

• If it prints TOO EARLY TO CALL (fewer than 5 scored pairs), quote the class straight and say the estimator itself is unvalidated. Do not apply a correction derived from one or two points — a single ratio is an observation, not a bias.
• Once it reports a geometric mean ratio over n ≥ 5, prefer EBS ratio resampling: draw whole historical estimate/actual ratios with replacement (100+ draws) and divide the class centre by each draw. Same principle — whole observed values, resampled, never averaged. Note this in

  source

  on the logged row so the provenance survives.

w = n/(n+κ)

calibrate.mjs

calibrate.mjs

**85% of your similar tasks finished in ≤ X agent-hours, ≤ Y human rounds, Z calendar days**
(class: <description>, n=<N>, neighbors: <task ids>)

• P50 line — "half finished in ≤ …", so the typical case is visible next to the limit.
• Regime call — the distribution is bimodal, not a spread around a centre. Say which mode you think this is in and why: agent-nails-it (precedent exists, tests verify, narrow blast radius) or integration-thrash (verification is human-eyes or prod-only, no precedent, external surface). Where both are live, give both with rough weights. A single blended number sits in the trough between the modes and describes almost nothing.
• Blow-up risk flags, each named, only the ones that apply: vague spec · human-eyes-only verification · wide blast radius · external waits · no precedent in repo. Name the flag and the specific thing that triggered it.
• External calendar waits, listed separately. App review, a platform approval, someone else's deploy window, a human decision. This is dead time, not work — never fold it into agent-hours; it is why calendar days and agent-hours are separate axes.
• The review tail is part of calendar days. If done means merged, the estimate does not stop at "code written" — that is the part that got faster. Review time is up 441% and agent-authored PRs wait 5.3× longer for pickup. Include the wait for a reviewer explicitly whenever the task ends in a PR someone else must merge.
• "Split this" whenever the estimate exceeds the class P85. Right-sizing beats budgeting more. Propose the actual split into ≤1-bucket pieces, do not just advise it.

estimate.v1

$LEDGER/ledger/estimates.ndjson

task

record.mjs

LEDGER=${CLAUDE_ESTIMATION_DIR:-~/.claude/estimation}
cat >> $LEDGER/ledger/estimates.ndjson <<'EOF'
{"schema":"estimate.v1","estimate_id":"2026-09-01-csv-export","date":"2026-09-01","task":"TICKET-1234","ticket":"TICKET-1234","features":{"task_type":"feature","greenfield":false,"precedent_in_repo":"example-api/TICKET-1180","self_verifiable":"tests","blast_radius":9},"class":{"neighbors":["example-api/TICKET-1180","example-api/TICKET-1204"],"n":7,"gate":"p50-only"},"quoted":{"agent_hours":{"p50":3,"lo":1.5,"hi":9},"human_rounds":{"p50":12,"lo":6,"hi":30},"calendar_days":{"p50":1,"lo":1,"hi":4}},"source":"class-p50+one-bucket-precedent-adjustment"}
EOF

2026-09-01-csv-export

• Log what you told the user, not a hedged version. A band quietly widened in the ledger manufactures coverage the estimator never earned.
• Never edit a logged row once work has started. A quote revised with knowledge of the outcome is not a quote. Log a second row and let both score.

record

duration ≈ rounds × (per-round agent time + per-round human wait)

Human round count is the dominant predictor (r ≈ 0.83 on measured data). First-turn duration predicts nothing (r ≈ 0.0).

• A long first turn is a good sign, not a bad one. It predicts fewer rounds — front-loaded framing pays for itself. Never quote a task as slow because it started slow.
• Waiting for permission prompts is the largest recoverable loss. Approval gaps are 52% of long intra-task pauses, median 32 minutes each. If the user's setup asks for approval per tool call, that — not model speed — is what is costing them the afternoon.

• It reads Claude Code conversation JSONL under

  ~/.claude*/projects/

  (both accounts) from this machine only.
• Nothing leaves the machine except the classification calls, which go to the Anthropic API as

  claude -p

  — the same place the user's normal sessions already go.
• What gets stored: task shape and durations. Not the conversation text.
• It is reversible:

  rm -rf ~/.claude/estimation

  .

.jsonl

nice -n 19 ionice -c3 node --max-old-space-size=2048 $SKILL/scripts/backfill.mjs \
  --root ~/.claude/projects

/tmp/claude/task-estimator-backfill/

<chat_id>.jsonl

<chat_id>/subagents/agent-*.jsonl

.meta.json

extract.mjs

subagents

loc_added

loc_removed

files_edited

repos

active_min

sidecar_count

per_type

Task

Agent

toolStats

• Nothing folds into the parent's own fields. A subagent's minutes run inside its parent's wall clock, so adding them would count time that was spent once, twice. The chat's

  loc_added

  ,

  files_edited

  and

  agent_active_min

  never move.
• Nothing is counted twice inside

  subagents

  either. Where the parent did report

  toolStats

  for a spawn and a sidecar for that same

  toolUseId

  exists, the sidecar measurement replaces the reported one — it is the primary record. Spawns with no sidecar keep their reported numbers. Depth-2 agents (spawned by another subagent, so no

  tool_use

  block exists in the parent at all) are added, which is why

  subagents.count

  can exceed the number of spawn blocks.

repo_share

{repo: fraction}

stitch.mjs

agent_hours_by_repo

subagent_hours_by_repo

agent_hours

repos

noise

"permtest"

echo PERMTEST_OK

"qa-probe"

/tmp

calibrate.mjs

digest.mjs

--estimate-only

node $SKILL/scripts/classify.mjs --estimate-only      # count + token/cost/wall estimate
node $SKILL/scripts/classify.mjs --concurrency 3      # then, once they agree

classify.mjs

MAX_THINKING_TOKENS=0

node $SKILL/scripts/digest.mjs --chat <chat-id> \
  | claude -p --model claude-haiku-4-5 \
      --output-format json \
      --system-prompt "$(cat $SKILL/prompts/classify-chat.md)" \
      --tools "" --safe-mode --no-session-persistence \
  | jq -r '.result'

• --tools ""

  — no tool loop. It is a classifier, it reads text and returns JSON.

• --safe-mode

  — no CLAUDE.md, skills, hooks, MCP servers. Keeps the classifier uncontaminated by project instructions and keeps the prompt prefix stable, so the batch gets prompt-cache hits. Auth still works normally (unlike

  --bare

  ).

• --no-session-persistence

  — critical. Without it every classification writes a new JSONL into

  ~/.claude*/projects/

  , which the next backfill would mine as a chat. The ledger would start eating its own tail.

• --output-format json

  returns an envelope; the model's text is

  .result

  , and it may still arrive fenced. Strip ``` fences before parsing. Optionally harden with

  --json-schema

  using the Schema block from the prompt file.

classified_at

classifier_model

• Labels come from the main chat — the classification that called itself

  main

  , tie-broken by agent-active minutes. Labels do not vote: averaging a bugfix and a refactor produces neither.

• outcome

  is decided by the artifact, not by the classifier. A task with

  commits > 0

  or a non-empty

  prs

  is

  shipped

  , full stop — those fields come from git and

  gh

  output, not from a model reading a truncated digest, and they are exactly the standard done means merged sets. The classifier keeps only the two verdicts an artifact cannot express:

  shipped-then-reverted

  and

  abandoned

  (in both, the commit exists and something else happened).

  outcome_source

  records

  deterministic

  or

  classifier

  and

  classifier_outcome

  keeps the original, so an audit can still score the model. This exists because the classifier ran 2.3:1 too pessimistic — a sonnet audit moved 62 rows

  unknown → shipped

  against 27 the other way, all of it the "prefer unknown over a guess" rule firing on a digest that simply did not show the commit line.

• external_waits

  and

  user_touchpoint_kinds

  are unioned over every chat. They are a quantity and a set, not labels — a wait that happened in chat 3 is still dead time the task paid for.
• Epics stay merged, and keep their detail. A multi-chat task is one row (splitting it is exactly the under-merging that makes a ledger flatter itself), with every chat's own labels preserved in a

  sub_deliverables[]

  array. A single chat that reports several units of work contributes several entries too.

classified_at

stitch_confidence

shipped

abandoned

prompts/audit-task.md

audit.mjs

rate

node $SKILL/scripts/audit.mjs --plan-only     # what would be sampled, and why
node $SKILL/scripts/audit.mjs --rate 5

calibration.json

• The rate is reported on the stride stratum only. The other three strata are deliberately the hardest rows, so their agreement is not a population rate.

• outcome

  is scored on the value the ledger actually holds, which for a row with an artifact is the deterministic one. That is the right number for "can I trust this field", but it is not a measurement of the classifier —

  classifier_outcome

  is what to score the model against.

calibrate.mjs

reliable

unmeasured

prompts/audit-task.md

• off_spec_corrections

  — a value outside the field's own enum. A "correction" in a different vocabulary is a different question answered.

• corrections_contradicting_deterministic_fields

  —

  outcome → unknown

  on a row whose

  commits

  /

  prs

  came out of git. The judge sees at most six truncated digests; the record is the census and the digest is a sample, so "I did not see the commit" is not a finding.

• self_contradicting_corrections

  — a

  false

  whose correction repeats the value already in the record. It asserts a disagreement and then fails to name one.

field_reliability.stitch

over_merged_share

agreement_on_well_stitched_rows

correct

task_type

correct

over-merged

task_type

reliable

stitch.mjs

slice.mjs

calibrate.mjs

score.mjs

node $SKILL/scripts/slice.mjs --min-chats 6      # refresh the epic sub_deliverables first
node $SKILL/scripts/calibrate.mjs --ledger $LEDGER/ledger --out $LEDGER/calibration.json
node $SKILL/scripts/score.mjs                    # add --json for the machine-readable form

• Interval coverage — of the quotes that have actuals, what fraction landed inside the quoted P80 band? It should be ~80%. Below that the quotes are too tight; well above, too loose.

  score.mjs

  prints the binomial acceptance band at the current n beside it; quote that band and never call a miss without it. At n=1 the band is 0–100%.
• Signed bias — the median of log(actual / quoted P50), so over- and under-estimation do not cancel, reported alongside the geometric mean ratio. Never average ratios linearly: 4× and 0.25× are the same error in opposite directions, and their arithmetic mean (2.1×) invents a bias that is not there.
• WIS-lite decomposition at n ≥ 5 — the 80% interval score split into sharpness + over-prediction + under-prediction. Read the shares: dominated by sharpness means the bands are too wide, dominated by under-prediction means the quotes are too low. Below n = 5 it is withheld, and "withheld" is the honest report — do not substitute a number.
• Quotes still awaiting actuals — every one is a task that finished without record mode running. Name them; that is the loop leaking.
• Per-class n, and which classes cleared the 5 / 10 / 20 gates since last time.
• Anything that moved: a class that just became quotable, a class whose coverage collapsed.

calibrate.mjs

• NEVER wait on a process with

  pgrep

  ,

  pkill -0

  ,

  ps | grep

  or any loop built on them.

  pgrep -f node

  ,

  pgrep -f backfill

  and friends match the checking process itself — the shell running the check, the subshell, the grep — so the loop observes a match forever and never exits. Two agents deadlocked on exactly this against this corpus. There is no safe flag combination; do not reach for

  pgrep -v $$

  either.
  • To wait for something you started: run it in the foreground, or capture its PID and wait on that PID specifically (

    wait <pid>

    for a child;

    kill -0 <pid>

    for a one-shot liveness check that is not in a loop).
  • To coordinate between separate runs: use a PID file.

    record.mjs

    writes

    $LEDGER/ledger/.record.lock

    containing its own pid, refuses immediately if a live holder exists (it never polls), and takes the lock over when the recorded pid is gone.

    --force-lock

    overrides. A killed run therefore never wedges the ledger, and nothing ever scans the process table.
  • A single, non-looping

    ps

    snapshot to answer "is a backfill running right now" is fine. It is the loop that kills you, not the tool.

• nice -n 19 ionice -c3

  on anything that walks the corpus (

  backfill.mjs

  ,

  classify.mjs

  ,

  audit.mjs

  ,

  record.mjs

  on a large transcript). The user is working on this box.
• Bound the heap:

  node --max-old-space-size=2048

  . Individual transcripts reach 140 MB; an unbounded run will happily take the machine with it.
• Never parallelise the extract pass. Files are processed sequentially, one big transcript at a time, on purpose.
• Scratch goes in

  /tmp/claude/task-estimator*/

  , never in a repo and never in the ledger. Back the ledger up there before any run that rewrites it.
• Ledger writes are atomic (temp file + rename) so a concurrent reader never sees a half-written NDJSON. Keep it that way — use

  writeNdjsonAtomic

  from

  lib.mjs

  .

references/

• METR RCT 2025 (16 expert devs, 246 real tasks in repos they maintain) — 19% slower with AI while believing they were 20% faster; a 39-point perception gap that does not self-correct with experience, and it was largest for experts in large mature repos — exactly the conditions here. This is why self-reports are banned as calibration input and why the ledger is mined rather than asked for.
• Done inflation ~7× — agent-declared completion overstates real completion on a maintainer-review basis, hiding ~26 minutes of remediation per "pass". Done means merged or accepted. Nothing else counts.
• Rounds, not minutes — measured r ≈ 0.83 between human round count and total duration (0.82 in the 651-session corpus; assistant steps score higher still at 0.86), against r ≈ 0.0 for first-turn duration and only 0.53 for LOC. Per-round agent work is stable at ~9s/step and a median turn near 45s; all the variance lives in the round count.
• 78 / 22 bimodality — 78% of high-complexity tasks finished under 25% of expected effort, while 22% of low-complexity tasks blew past 180%, driven by validation and integration rather than coding. The joint distribution is bimodal, so a single central number sits in the trough. The readiness gate is the cheapest filter on which mode a task is in: the blowups correlate with absent or untestable acceptance criteria.
• Anchoring (Løhre & Jørgensen) — an irrelevant number moves estimates 4–5×, survives explicit instructions to ignore it, and survives an obviously unqualified source. Hence anchor-stripping happens before any reasoning, not as a caveat afterwards. Same-person re-estimates of an identical task deviate 71%, so no remembered estimate is ever data.
• Reference-class forecasting (Kahneman/Lovallo/Flyvbjerg) — outside view first, then a bounded one-bucket inside-view shift. Software's class base rate is a 73% mean overrun with an 18% tail averaging +447%: fat-tailed, so P85 by default and P95 whenever an external dependency is in play.
• Evidence-Based Scheduling (Spolsky) — resample whole estimate/actual ratios; never average velocity, because averaging deletes exactly the tail draws that produce the overruns. Rework is charged back to the original item — filing it separately is how a history silently reports itself as accurate.
• Sample-size gates (Vacanti) — 5 for a median, ~11 before the observed range means anything, 10–20 before publishing an upper limit; 15 fresh points beat 150 stale ones. A personal P85 at n=11 spans 0.31–2.26× the truth, which is why everything below n≈20 is shrunk toward the population prior.
• Empirical quantiles, not fits — a fitted lognormal lands at ×0.72 of the true median and ×1.72 at p95, while raw empirical quantiles scored leave-one-out coverage of 49.9 / 79.8 / 89.9 against nominal 50 / 80 / 90 — essentially exact. Sort the actuals and read the quantile off the data, in log space.
• Only 35% of tasks land within 2× of the median. At that dispersion a point estimate is indefensible; the interval is the answer.
• The constraint moved downstream — task throughput +33.7% alongside review time +441%, pickup +156%, churn +861%, and 38% of agentic PR failures are "never reviewed". An estimate that stops at "code written" measures the part that got faster. And with coding only ~30–40% of a developer's calendar time, any claimed end-to-end gain above ~40% is a measurement error, not a result.