estimetry 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/README.md +50 -6
- package/dist/application/task/show-calibration.js +12 -8
- package/dist/application/task/task-cards.js +1 -1
- package/dist/domain/calibration/applicable-coefficient.js +35 -19
- package/dist/domain/calibration/calibration-policy.js +39 -0
- package/dist/domain/calibration/calibration.js +21 -36
- package/dist/domain/calibration/level-parts.js +41 -0
- package/dist/domain/calibration/ratio-samples.js +34 -0
- package/dist/domain/estimate/estimate.js +22 -5
- package/dist/infrastructure/persistence/records.js +1 -1
- package/dist/infrastructure/persistence/yaml-config-store.js +6 -5
- package/dist/infrastructure/persistence/yaml-estimate-reader.js +20 -12
- package/dist/integrations/tools/content/commands.js +8 -6
- package/dist/interface/cli/commands/calibrate-command.js +18 -0
- package/dist/interface/cli/help.js +3 -1
- package/dist/interface/cli/presenters/text/estimate-text.js +42 -13
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,22 @@ All notable changes to estimetry. Versions follow [semantic versioning](https://
|
|
|
4
4
|
|
|
5
5
|
## Unreleased
|
|
6
6
|
|
|
7
|
+
## 0.3.1 — 2026-11-22
|
|
8
|
+
|
|
9
|
+
- `emt calibrate` names the calibration settings in force on its second line, and says when they are the defaults: `Settings: calibration.minTasks 1, calibration.shrink 2 (the defaults); see emt help calibrate.` The first line and `--json` stay as they were.
|
|
10
|
+
- `emt --help` and `emt help calibrate` name the data directory as estimetry finds it: `$ESTIMETRY_HOME`, else `$XDG_DATA_HOME/estimetry`, else `~/.local/share/estimetry`; the help of calibrate takes the defaults from the calibration itself.
|
|
11
|
+
|
|
12
|
+
## 0.3.0 — 2026-11-22
|
|
13
|
+
|
|
14
|
+
- **Calibration from the first closed task.** The coefficient an estimate applies is the median of fact over estimate shrunk towards 1 with the weight n / (n + k) (`calibration.shrink`, 2 by default), instead of nothing until a slice has 5 tasks. The slices form a chain — all your tasks, the technology of the query with the most tasks, the task type — each shrunk towards the one above by the tasks no deeper slice holds, so every task counts once; the deepest applies, and the overall slice now counts too. `emt calibrate` names the slice, the number of tasks and the weight.
|
|
15
|
+
- **Pessimistic coefficient.** `c · e^(ln 2 / √n)`, at most 1 while your estimates run high: the agent multiplies the pessimistic hours by it and the optimistic and most likely hours by the coefficient. The estimate file takes it as `calibration.pessimistic`; the base calibration compares with is still likely over the coefficient.
|
|
16
|
+
- **Without calibration** an estimate is now only when no task is closed yet, every closed task is left out or has no estimate, there are fewer tasks than your `calibration.minTasks`, or some cards come from a newer estimetry; `emt calibrate` says which.
|
|
17
|
+
- New defaults: `calibration.minTasks: 1`, `calibration.shrink: 2`. A `minTasks` you set without `shrink` means `shrink: 0`; `minTasks: 5` alone gives the coefficient of earlier versions wherever they gave one, and the median of all your tasks where neither the type nor a technology has 5; the pessimistic hours get the pessimistic coefficient there too, a reserve earlier versions did not give. The README shows what to expect from each setting.
|
|
18
|
+
- `calibration.json` has schema 3: `weight` instead of `applicable` in every slice, and `shrink`. It is rewritten by the next closing or `emt rebuild`.
|
|
19
|
+
- `emt calibrate --json` has `schemaVersion: 2`: `coefficient` is `{ value, pessimistic, slice: { kind, key? }, n, weight }`, slices carry `weight` instead of `applicable`, and `shrink` sits beside `minTasks`.
|
|
20
|
+
- `emt calibrate --help` names `calibration.minTasks` and `calibration.shrink` with their defaults, and `emt --help` says where `config.yaml` lives.
|
|
21
|
+
- Run `emt upgrade` once: the skills are written again.
|
|
22
|
+
|
|
7
23
|
## 0.2.0 — 2026-11-21
|
|
8
24
|
|
|
9
25
|
- **Codex.** `estimetry init --tools codex`, or picking Codex in `init`, sets up the hooks of Codex (in `~/.codex/hooks.json`, or `.codex/hooks.json` of the project with `--shared-hooks`) and the `emt-…` skills (in `~/.agents/skills`, or `.agents/skills`), called as `$emt-…`. Sessions of Codex are measured like those of Claude Code, and both tools may serve one task. Codex runs a hook only once you trust it, and the agent's commands in a sandbox: in a terminal `init` asks whether to trust the estimetry hooks and to let the task commands (`emt start`, `extra`, `close`…) out of the sandbox, and records both with yes or `--trust-hooks` (`~/.codex/config.toml`, `~/.codex/rules/estimetry.rules`). `emt upgrade` trusts again the hooks it changes when you trusted them before; `emt status` warns while they are not trusted. Requires Codex 0.145 or newer.
|
package/README.md
CHANGED
|
@@ -33,7 +33,7 @@ To update later: `npm install -g estimetry@latest`, then `emt upgrade` once (see
|
|
|
33
33
|
|
|
34
34
|
The skills are the same in both tools: Claude Code calls them as `/emt-…`, Codex as `$emt-…` (`$emt-estimate`, `$emt-start`). This README names them the Claude Code way.
|
|
35
35
|
|
|
36
|
-
Every closed task makes the next estimate more grounded: `emt similar` finds past tasks like the new one, and `emt calibrate` gives your own coefficient
|
|
36
|
+
Every closed task makes the next estimate more grounded: `emt similar` finds past tasks like the new one, and `emt calibrate` gives your own coefficient from the first closed task, more confident with every next one.
|
|
37
37
|
|
|
38
38
|
## Help
|
|
39
39
|
|
|
@@ -91,7 +91,7 @@ Codex has no personal settings inside a project, so the hooks of a personal inst
|
|
|
91
91
|
|
|
92
92
|
With `--track-commits` a `post-commit` hook is installed into the repository's hooks directory. This respects `core.hooksPath`, worktrees and husky (`.husky/post-commit`). An existing hook keeps its content: estimetry adds its own block between `# >>> estimetry >>>` and `# <<< estimetry <<<`. The hook runs estimetry in the background, so commits never wait for it. Colleagues without estimetry see nothing. A personal hook (in `.git`, or a hooks directory outside the repository) runs this installation by its paths, like the Claude Code hooks, so a commit from an IDE started from the Dock is recorded too. A hook the project commits (husky, `core.hooksPath` inside the repository) holds no paths of your machine and needs `estimetry` on `PATH`.
|
|
93
93
|
|
|
94
|
-
No task data ever goes into the repository. Tasks, estimates and the event journal live in `~/.local/share/estimetry
|
|
94
|
+
No task data ever goes into the repository. Tasks, estimates and the event journal live in `ESTIMETRY_HOME` if set, else in `$XDG_DATA_HOME/estimetry/`, else in `~/.local/share/estimetry/`; the paths below name the last.
|
|
95
95
|
|
|
96
96
|
### Flags
|
|
97
97
|
|
|
@@ -134,8 +134,10 @@ emt calibrate --type feature --revise # for a revision of a task in progress
|
|
|
134
134
|
```
|
|
135
135
|
|
|
136
136
|
- **Similarity** weighs the shared technologies (half), the type of the first estimate and, with `--hours`, the size. Each task shows what its similarity is made of. Without `--stack`, the stack of the project counts.
|
|
137
|
-
- **The coefficient** is the median of fact over estimate
|
|
138
|
-
- **
|
|
137
|
+
- **The coefficient** comes from the first closed task. It is the median of fact over estimate, shrunk towards 1 with the weight n / (n + k), `k` being `calibration.shrink` (2 by default): one task weighs ⅓, two ½, six ¾. The slices form a chain: all your tasks, the technology of the query with the most tasks, the task type. Each is shrunk towards the one above by the tasks no deeper slice holds, so every task counts once, and the deepest one applies. `emt calibrate` names the slice, the number of tasks and the weight; below 50% the agent tells you the coefficient is still cautious.
|
|
138
|
+
- **The pessimistic coefficient**, `c · e^(ln 2 / √n)`, keeps a reserve while the tasks are few; while your estimates run high (`c < 1`) it is at most 1.
|
|
139
|
+
- **Without calibration** the estimate is only when no task is closed yet, every closed task is left out or has no estimate, there are fewer than your `calibration.minTasks`, or some cards come from a newer estimetry. `emt calibrate` says which, and the agent tells you.
|
|
140
|
+
- **A calibrated estimate** multiplies the optimistic and most likely hours of every part by the coefficient and the pessimistic hours by the pessimistic coefficient, and records both (`calibrated: true`, `calibration.coefficient`, `calibration.pessimistic`), so the next coefficient is computed from the estimate before it. A reserve goes only into the pessimistic hours, on top of that: extra work you absorbed is already in the coefficient.
|
|
139
141
|
- **Nothing is written** by `emt similar` and `emt calibrate`; `calibration.json` is updated by closings and `emt rebuild`.
|
|
140
142
|
- **A changed email.** Calibration is personal, by `author.id` in `config.yaml`. List earlier ids so that their cards stay yours:
|
|
141
143
|
|
|
@@ -309,13 +311,55 @@ Names, descriptions and the retro sit in a separate `text` section of the card,
|
|
|
309
311
|
- how well the code volume was forecast;
|
|
310
312
|
- which kinds of parts run over.
|
|
311
313
|
|
|
312
|
-
|
|
314
|
+
Every slice has a weight, n / (n + k), next to its median and mean (see [Estimating a task](#estimating-a-task) for how the coefficient is built from them):
|
|
315
|
+
|
|
316
|
+
```json
|
|
317
|
+
{
|
|
318
|
+
"schemaVersion": 3,
|
|
319
|
+
"minTasks": 1,
|
|
320
|
+
"shrink": 2,
|
|
321
|
+
"authors": {
|
|
322
|
+
"you@example.com": {
|
|
323
|
+
"tasks": 4,
|
|
324
|
+
"ratio": {
|
|
325
|
+
"overall": { "n": 4, "median": 0.5, "mean": 0.55, "weight": 0.667 },
|
|
326
|
+
"byType": { "feature": { "n": 3, "median": 0.6, "mean": 0.62, "weight": 0.6 } }
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
**Settings.** Two settings in `config.yaml` of the data directory (`~/.local/share/estimetry/`, see [Setting up a project](#setting-up-a-project-estimetry-init) for `ESTIMETRY_HOME` and `XDG_DATA_HOME`) decide how soon calibration starts and how strongly it acts:
|
|
313
334
|
|
|
314
335
|
```yaml
|
|
315
336
|
calibration:
|
|
316
|
-
minTasks:
|
|
337
|
+
minTasks: 1 # a slice counts from this many closed tasks; below it in all your tasks, no coefficient
|
|
338
|
+
shrink: 2 # k in n / (n + k): larger is more cautious, 0 applies the median as it is
|
|
317
339
|
```
|
|
318
340
|
|
|
341
|
+
Setting `minTasks` without `shrink` means `shrink: 0`: a threshold you chose yourself keeps the coefficient it gave.
|
|
342
|
+
|
|
343
|
+
**What to expect.** Say every closed task took half of its estimate (fact over estimate 0.5), all of one type and technology. The coefficient and the pessimistic coefficient after 1, 3, 5 and 10 closed tasks (— is without calibration):
|
|
344
|
+
|
|
345
|
+
| Settings | 1 task | 3 tasks | 5 tasks | 10 tasks |
|
|
346
|
+
|---|---|---|---|---|
|
|
347
|
+
| default: `minTasks: 1`, `shrink: 2` | ×0.79 / ×1.00 | ×0.66 / ×0.98 | ×0.61 / ×0.83 | ×0.56 / ×0.70 |
|
|
348
|
+
| faster: `shrink: 1` | ×0.71 / ×1.00 | ×0.59 / ×0.89 | ×0.56 / ×0.77 | ×0.53 / ×0.66 |
|
|
349
|
+
| more cautious: `shrink: 5` | ×0.89 / ×1.00 | ×0.77 / ×1.00 | ×0.71 / ×0.96 | ×0.63 / ×0.78 |
|
|
350
|
+
| later start: `minTasks: 3`, `shrink: 2` | — | ×0.66 / ×0.98 | ×0.61 / ×0.83 | ×0.56 / ×0.70 |
|
|
351
|
+
| as in 0.2: `minTasks: 5` | — | — | ×0.50 / ×0.68 | ×0.50 / ×0.62 |
|
|
352
|
+
| the median as it is: `shrink: 0` | ×0.50 / ×1.00 | ×0.50 / ×0.75 | ×0.50 / ×0.68 | ×0.50 / ×0.62 |
|
|
353
|
+
|
|
354
|
+
- The coefficient moves from 1 towards your median as tasks close; `shrink` sets how fast. The pessimistic coefficient stays at 1 while there is little experience and comes down to the coefficient with it.
|
|
355
|
+
- When your estimates run low, nothing caps the pessimistic coefficient: with fact over estimate 1.5 the default gives ×1.14 / ×2.29 after one task and ×1.40 / ×1.75 after ten.
|
|
356
|
+
- With tasks of several types and technologies the coefficient comes from the chain of slices: the tasks of the type weigh by their number, your other tasks fill in the rest of the weight, and what is still missing stays at 1.
|
|
357
|
+
- `minTasks: 5` gives the coefficient of earlier versions wherever they gave one, with two differences. When neither the type nor a technology has 5 tasks, the median of all your tasks applies, where earlier versions gave none. The pessimistic hours are multiplied by the pessimistic coefficient, not by the coefficient, so they keep a reserve earlier versions did not give.
|
|
358
|
+
|
|
359
|
+
**Seeing them.** The second line of `emt calibrate` names the settings in force, and says when they are the defaults: `Settings: calibration.minTasks 1, calibration.shrink 2 (the defaults); see emt help calibrate.` `emt calibrate --json` has them as `minTasks` and `shrink`.
|
|
360
|
+
|
|
361
|
+
**Changing them.** Edit `config.yaml` and run `emt calibrate --type <type> --stack <a,b>`: it computes from your cards at once and names the coefficient, the slice, the number of tasks and the weight. Estimates already saved keep their coefficient. `calibration.json` follows at the next closing or with `emt rebuild`, which also rewrites a `calibration.json` of an earlier schema.
|
|
362
|
+
|
|
319
363
|
Tasks in parallel mode count with their sequential equivalent. Abandoned tasks and tasks with manual time only are left out.
|
|
320
364
|
|
|
321
365
|
Revised tasks give two accuracies:
|
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
import { applicableCoefficient } from '../../domain/calibration/applicable-coefficient.js';
|
|
2
|
-
import {
|
|
2
|
+
import { authorCards, calibrate, } from '../../domain/calibration/calibration.js';
|
|
3
3
|
import { otherAuthors } from '../../domain/calibration/other-authors.js';
|
|
4
4
|
import { estimateQuery } from './estimate-query.js';
|
|
5
|
-
|
|
5
|
+
/** 2: the coefficient with its pessimistic value and weight, the weight of a slice instead of `applicable` (dynamic-calibration). */
|
|
6
|
+
export const CALIBRATION_VIEW_SCHEMA_VERSION = 2;
|
|
6
7
|
const NO_TASKS = {
|
|
7
8
|
n: 0,
|
|
8
9
|
median: null,
|
|
9
10
|
mean: null,
|
|
10
|
-
|
|
11
|
+
weight: 0,
|
|
11
12
|
excluded: {},
|
|
12
13
|
uncertain: 0,
|
|
13
14
|
backgroundAgents: 0,
|
|
@@ -35,10 +36,10 @@ export class ShowCalibration {
|
|
|
35
36
|
const { cards, skipped } = this.cards.allCards();
|
|
36
37
|
const author = this.authors.current();
|
|
37
38
|
const aliases = this.authors.toCurrent();
|
|
38
|
-
const
|
|
39
|
+
const policy = this.settings.policy();
|
|
39
40
|
// Only the author's section is shown: other authors' cards are not computed at all.
|
|
40
|
-
const own =
|
|
41
|
-
const mine = calibrate(own, {
|
|
41
|
+
const own = authorCards(cards, author, aliases);
|
|
42
|
+
const mine = calibrate(own, { policy }).authors[author];
|
|
42
43
|
const revise = input.revise === true;
|
|
43
44
|
const type = query.type?.value;
|
|
44
45
|
const pick = (slices, empty) => ({
|
|
@@ -50,8 +51,11 @@ export class ShowCalibration {
|
|
|
50
51
|
schemaVersion: CALIBRATION_VIEW_SCHEMA_VERSION,
|
|
51
52
|
query: { type: type ?? null, stack: [...query.stack.values], revise },
|
|
52
53
|
// A calibration from an incomplete set of cards could give a wrong coefficient.
|
|
53
|
-
coefficient: skipped.length > 0
|
|
54
|
-
|
|
54
|
+
coefficient: skipped.length > 0
|
|
55
|
+
? null
|
|
56
|
+
: applicableCoefficient(cards, { author, aliases, estimate: query, revise }, policy),
|
|
57
|
+
minTasks: policy.minTasks,
|
|
58
|
+
shrink: policy.shrink,
|
|
55
59
|
tasks: mine?.tasks ?? 0,
|
|
56
60
|
ratio: pick(mine?.ratio, NO_TASKS),
|
|
57
61
|
revised: pick(mine?.revised, { ...NO_TASKS, countedAtShare: null }),
|
|
@@ -53,7 +53,7 @@ export class TaskCards {
|
|
|
53
53
|
}
|
|
54
54
|
const cards = stored.map((card) => card.schema === 'current' ? card.card : card.schema === 'newer' ? undefined : this.upgrade(card.card));
|
|
55
55
|
// A card that cannot be read even by its fields is left out, as a broken file is.
|
|
56
|
-
return calibrate(cards.filter((card) => card !== undefined), {
|
|
56
|
+
return calibrate(cards.filter((card) => card !== undefined), { policy: this.settings.policy(), aliases: this.aliases.toCurrent() });
|
|
57
57
|
});
|
|
58
58
|
}
|
|
59
59
|
/**
|
|
@@ -1,26 +1,42 @@
|
|
|
1
|
+
import { authorCards } from './calibration.js';
|
|
2
|
+
import { levelParts } from './level-parts.js';
|
|
3
|
+
import { ratioSampling } from './ratio-samples.js';
|
|
4
|
+
import { median, round } from './statistics.js';
|
|
5
|
+
/** The spread of the ratio in logarithms the pessimistic coefficient reserves for: a factor of 2 at one task. */
|
|
6
|
+
const SIGMA = Math.log(2);
|
|
1
7
|
/**
|
|
2
|
-
* The coefficient an estimate may apply (calibration-query spec)
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
8
|
+
* The coefficient an estimate may apply (calibration-query spec), from all the
|
|
9
|
+
* cards: the author's are taken as calibration takes them (`authorCards`).
|
|
10
|
+
* Going down the levels (`levelParts`), each part shrinks towards the level
|
|
11
|
+
* above in logarithms by the weight of its own tasks; the overall part towards
|
|
12
|
+
* 1, an empty part equals the level above. The deepest level is applied: its
|
|
13
|
+
* part is its whole slice. A new estimate takes the main ratio; a revision of
|
|
14
|
+
* a task in progress, `revised`.
|
|
6
15
|
*/
|
|
7
|
-
export function applicableCoefficient(
|
|
8
|
-
|
|
16
|
+
export function applicableCoefficient(cards, query, policy) {
|
|
17
|
+
const own = authorCards(cards, query.author, query.aliases);
|
|
18
|
+
const parts = levelParts(ratioSampling(own, query.revise === true), query.estimate, policy);
|
|
19
|
+
const applied = parts.at(-1);
|
|
20
|
+
if (applied === undefined) {
|
|
9
21
|
return null;
|
|
10
22
|
}
|
|
11
|
-
|
|
12
|
-
const
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
23
|
+
let logarithm = 0;
|
|
24
|
+
for (const part of parts) {
|
|
25
|
+
const middle = median(part.ratios);
|
|
26
|
+
if (middle !== null) {
|
|
27
|
+
const weight = policy.partWeight(part.ratios.length);
|
|
28
|
+
logarithm = weight * Math.log(middle) + (1 - weight) * logarithm;
|
|
29
|
+
}
|
|
16
30
|
}
|
|
17
|
-
const
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
31
|
+
const n = applied.ratios.length;
|
|
32
|
+
const value = Math.exp(logarithm);
|
|
33
|
+
const upper = value * Math.exp(SIGMA / Math.sqrt(n));
|
|
34
|
+
return {
|
|
35
|
+
value: round(value),
|
|
36
|
+
pessimistic: round(value < 1 ? Math.min(1, upper) : upper),
|
|
37
|
+
slice: applied.slice,
|
|
38
|
+
n,
|
|
39
|
+
weight: round(policy.partWeight(n)),
|
|
40
|
+
};
|
|
25
41
|
}
|
|
26
42
|
//# sourceMappingURL=applicable-coefficient.js.map
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
export const DEFAULT_MIN_TASKS = 1;
|
|
2
|
+
export const DEFAULT_SHRINK = 2;
|
|
3
|
+
/**
|
|
4
|
+
* How calibration weighs a slice (calibration spec): from `calibration.minTasks`
|
|
5
|
+
* tasks a slice has the weight n / (n + k) with k = `calibration.shrink` and is a
|
|
6
|
+
* level of the coefficient; each level is shrunk towards the one above by the
|
|
7
|
+
* weight of its own tasks (`partWeight`).
|
|
8
|
+
*/
|
|
9
|
+
export class CalibrationPolicy {
|
|
10
|
+
minTasks;
|
|
11
|
+
shrink;
|
|
12
|
+
constructor(minTasks, shrink) {
|
|
13
|
+
this.minTasks = minTasks;
|
|
14
|
+
this.shrink = shrink;
|
|
15
|
+
}
|
|
16
|
+
static DEFAULT = new CalibrationPolicy(DEFAULT_MIN_TASKS, DEFAULT_SHRINK);
|
|
17
|
+
/**
|
|
18
|
+
* The settings of `config.yaml`; an invalid value counts as not given. A
|
|
19
|
+
* threshold chosen without `shrink` means no shrinking: the user who picked
|
|
20
|
+
* the sample a coefficient needs keeps the coefficient they had.
|
|
21
|
+
*/
|
|
22
|
+
static fromConfig(given) {
|
|
23
|
+
const minTasks = given.minTasks !== undefined && Number.isInteger(given.minTasks) && given.minTasks >= 1 ? given.minTasks : undefined;
|
|
24
|
+
const shrink = given.shrink !== undefined && Number.isFinite(given.shrink) && given.shrink >= 0 ? given.shrink : undefined;
|
|
25
|
+
return new CalibrationPolicy(minTasks ?? DEFAULT_MIN_TASKS, shrink ?? (minTasks === undefined ? DEFAULT_SHRINK : 0));
|
|
26
|
+
}
|
|
27
|
+
/** The weight of the observations of a slice of n tasks: 0 below `minTasks`. */
|
|
28
|
+
weight(n) {
|
|
29
|
+
return n < this.minTasks ? 0 : this.partWeight(n);
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* The weight of the own tasks of a level in the chain, n / (n + k), without
|
|
33
|
+
* the threshold: `minTasks` is checked on the whole slice. 0 without tasks.
|
|
34
|
+
*/
|
|
35
|
+
partWeight(n) {
|
|
36
|
+
return n === 0 ? 0 : n / (n + this.shrink);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
//# sourceMappingURL=calibration-policy.js.map
|
|
@@ -1,22 +1,22 @@
|
|
|
1
1
|
import { stackLabels } from '../estimate/stack-labels.js';
|
|
2
|
-
import {
|
|
2
|
+
import { ratioSampling } from './ratio-samples.js';
|
|
3
3
|
import { EXTRA_CATEGORIES } from '../measurement/extra.js';
|
|
4
4
|
import { isRevised, linesPerHour, partsByKind, volumeAccuracy, } from './code-and-parts.js';
|
|
5
5
|
import { median, round } from './statistics.js';
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
export const
|
|
6
|
+
import { CalibrationPolicy } from './calibration-policy.js';
|
|
7
|
+
/** 3: the weight of a slice instead of `applicable`, and `shrink` (dynamic-calibration); readers check the version. */
|
|
8
|
+
export const CALIBRATION_SCHEMA_VERSION = 3;
|
|
9
9
|
const UNCERTAINTY_LIMIT = 0.05;
|
|
10
10
|
/** Calibration from the cards of closed tasks, by author (design §10, calibration spec). */
|
|
11
11
|
export function calibrate(all, options = {}) {
|
|
12
|
-
const
|
|
12
|
+
const policy = options.policy ?? CalibrationPolicy.DEFAULT;
|
|
13
13
|
const cards = normalized(all, options.aliases);
|
|
14
14
|
const authors = {};
|
|
15
15
|
const byId = new Map(cards.map((card) => [card.task.id, card]));
|
|
16
16
|
for (const author of [...new Set(cards.map((card) => card.author))].sort()) {
|
|
17
|
-
authors[author] = forAuthor(cards.filter((card) => card.author === author), byId,
|
|
17
|
+
authors[author] = forAuthor(cards.filter((card) => card.author === author), byId, policy);
|
|
18
18
|
}
|
|
19
|
-
return { schemaVersion: CALIBRATION_SCHEMA_VERSION, minTasks, authors };
|
|
19
|
+
return { schemaVersion: CALIBRATION_SCHEMA_VERSION, minTasks: policy.minTasks, shrink: policy.shrink, authors };
|
|
20
20
|
}
|
|
21
21
|
/**
|
|
22
22
|
* Cards as calibration compares them: a card of an alias is the author's
|
|
@@ -29,20 +29,23 @@ export function normalized(cards, aliases = new Map()) {
|
|
|
29
29
|
task: { ...card.task, stack: stackLabels(card.task.stack) },
|
|
30
30
|
}));
|
|
31
31
|
}
|
|
32
|
-
|
|
32
|
+
/** The cards of one author as calibration compares them (`normalized`): the cards of their aliases included. */
|
|
33
|
+
export function authorCards(cards, author, aliases) {
|
|
34
|
+
return normalized(cards, aliases).filter((card) => card.author === author);
|
|
35
|
+
}
|
|
36
|
+
function forAuthor(cards, byId, policy) {
|
|
33
37
|
const estimated = cards.filter((card) => card.estimate !== null);
|
|
34
|
-
const main =
|
|
35
|
-
const
|
|
36
|
-
const later = sampled(revisedCards, revisedExclusion, revisedRatioOf);
|
|
38
|
+
const main = ratioSampling(cards, false);
|
|
39
|
+
const later = ratioSampling(cards, true);
|
|
37
40
|
const kept = main.samples.map((sample) => sample.card);
|
|
38
41
|
// Rolled back work leaves lines that say nothing about the volume of the task.
|
|
39
42
|
const volumeCards = kept.filter((card) => !hasExclude(card) && !(card.convertedFrom === 1 && card.revised));
|
|
40
43
|
const volumeExcluded = kept.length - volumeCards.length;
|
|
41
44
|
return {
|
|
42
45
|
tasks: cards.length,
|
|
43
|
-
ratio: slices(main, (
|
|
44
|
-
revised: slices(later, (
|
|
45
|
-
...ratioStats(samples, reasons,
|
|
46
|
+
ratio: slices(main, (samples, reasons) => ratioStats(samples, reasons, policy)),
|
|
47
|
+
revised: slices(later, (samples, reasons) => ({
|
|
48
|
+
...ratioStats(samples, reasons, policy, (card) => card.fact.counted.uncertaintyShare),
|
|
46
49
|
countedAtShare: median(samples.flatMap(({ card }) => {
|
|
47
50
|
const at = card.revisions.at(-1)?.countedAtMinutes;
|
|
48
51
|
return at === undefined || card.fact.counted.totalMinutes === 0 ? [] : [at / card.fact.counted.totalMinutes];
|
|
@@ -63,29 +66,11 @@ function forAuthor(cards, byId, minTasks) {
|
|
|
63
66
|
function hasExclude(card) {
|
|
64
67
|
return card.revisions.some((revision) => revision.spent === 'exclude');
|
|
65
68
|
}
|
|
66
|
-
function sampled(cards, exclude, ratio) {
|
|
67
|
-
const samples = [];
|
|
68
|
-
const excluded = [];
|
|
69
|
-
for (const card of cards) {
|
|
70
|
-
const reason = exclude(card);
|
|
71
|
-
if (reason !== undefined) {
|
|
72
|
-
excluded.push({ card, reason });
|
|
73
|
-
continue;
|
|
74
|
-
}
|
|
75
|
-
const value = ratio(card);
|
|
76
|
-
if (value === undefined) {
|
|
77
|
-
excluded.push({ card, reason: 'renegotiated-without-groups' });
|
|
78
|
-
}
|
|
79
|
-
else {
|
|
80
|
-
samples.push({ card, ratio: value });
|
|
81
|
-
}
|
|
82
|
-
}
|
|
83
|
-
return { samples, excluded };
|
|
84
|
-
}
|
|
85
69
|
/** Overall, by type and by each technology of the stack. */
|
|
86
|
-
function slices(sampled,
|
|
70
|
+
function slices(sampled, stats) {
|
|
87
71
|
const all = [...sampled.samples.map((s) => s.card), ...sampled.excluded.map((e) => e.card)];
|
|
88
72
|
const slice = (keep) => stats(sampled.samples.filter((sample) => keep(sample.card)), sampled.excluded.filter((item) => keep(item.card)).map((item) => item.reason));
|
|
73
|
+
const typeOf = sampled.typeOf;
|
|
89
74
|
const types = [...new Set(all.flatMap((card) => typeOf(card) ?? []))].sort();
|
|
90
75
|
const stacks = [...new Set(all.flatMap((card) => card.task.stack))].sort();
|
|
91
76
|
return {
|
|
@@ -129,7 +114,7 @@ function revisionStats(cards) {
|
|
|
129
114
|
}
|
|
130
115
|
return { byType, excluded: fromV1 === 0 ? {} : { 'card-v1': fromV1 } };
|
|
131
116
|
}
|
|
132
|
-
function ratioStats(samples, reasons,
|
|
117
|
+
function ratioStats(samples, reasons, policy, uncertaintyOf = (card) => card.fact.uncertaintyShare) {
|
|
133
118
|
const ratios = samples.map((sample) => sample.ratio);
|
|
134
119
|
const excluded = {};
|
|
135
120
|
for (const reason of reasons) {
|
|
@@ -139,7 +124,7 @@ function ratioStats(samples, reasons, minTasks, uncertaintyOf = (card) => card.f
|
|
|
139
124
|
n: ratios.length,
|
|
140
125
|
median: median(ratios),
|
|
141
126
|
mean: ratios.length === 0 ? null : round(ratios.reduce((a, b) => a + b, 0) / ratios.length),
|
|
142
|
-
|
|
127
|
+
weight: round(policy.weight(ratios.length)),
|
|
143
128
|
excluded,
|
|
144
129
|
uncertain: samples.filter((sample) => (uncertaintyOf(sample.card) ?? 0) > UNCERTAINTY_LIMIT).length,
|
|
145
130
|
backgroundAgents: samples.filter((sample) => sample.card.backgroundAgents).length,
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The levels of the coefficient, from overall to the deepest, each with the
|
|
3
|
+
* tasks it alone counts (calibration-query spec). A level counts when its whole
|
|
4
|
+
* slice has a weight above 0; the overall slice, the technology of the query
|
|
5
|
+
* with the most tasks (the first alphabetically on a tie), the type of the
|
|
6
|
+
* query. The deepest level takes all of its tasks, each level above only those
|
|
7
|
+
* no deeper level holds: every task counts once. Without a weight in the
|
|
8
|
+
* overall slice there are no levels.
|
|
9
|
+
*/
|
|
10
|
+
export function levelParts(sampling, query, policy) {
|
|
11
|
+
const levels = levelsOf(sampling, query, policy);
|
|
12
|
+
const deeper = new Set();
|
|
13
|
+
const parts = [];
|
|
14
|
+
for (const level of [...levels].reverse()) {
|
|
15
|
+
const own = level.samples.filter((sample) => !deeper.has(sample.card));
|
|
16
|
+
own.forEach((sample) => deeper.add(sample.card));
|
|
17
|
+
parts.unshift({ slice: level.slice, ratios: own.map((sample) => sample.ratio) });
|
|
18
|
+
}
|
|
19
|
+
return parts;
|
|
20
|
+
}
|
|
21
|
+
function levelsOf(sampling, query, policy) {
|
|
22
|
+
const level = (slice, keep) => {
|
|
23
|
+
const samples = sampling.samples.filter((sample) => keep(sample.card));
|
|
24
|
+
return policy.weight(samples.length) > 0 ? [{ slice, samples }] : [];
|
|
25
|
+
};
|
|
26
|
+
const overall = level({ kind: 'overall' }, () => true);
|
|
27
|
+
if (overall.length === 0) {
|
|
28
|
+
return [];
|
|
29
|
+
}
|
|
30
|
+
const technology = query.stack.values
|
|
31
|
+
.flatMap((key) => level({ kind: 'stack', key }, (card) => card.task.stack.includes(key)))
|
|
32
|
+
.sort((a, b) => b.samples.length - a.samples.length || keyOf(a.slice).localeCompare(keyOf(b.slice)))
|
|
33
|
+
.slice(0, 1);
|
|
34
|
+
const type = query.type?.value;
|
|
35
|
+
const byType = type === undefined ? [] : level({ kind: 'type', key: type }, (card) => sampling.typeOf(card) === type);
|
|
36
|
+
return [...overall, ...technology, ...byType];
|
|
37
|
+
}
|
|
38
|
+
function keyOf(slice) {
|
|
39
|
+
return slice.kind === 'overall' ? '' : slice.key;
|
|
40
|
+
}
|
|
41
|
+
//# sourceMappingURL=level-parts.js.map
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { isRevised } from './code-and-parts.js';
|
|
2
|
+
import { exclusion, ratioOf, revisedExclusion, revisedRatioOf } from './task-ratio.js';
|
|
3
|
+
/**
|
|
4
|
+
* Which cards a ratio counts and with what value (calibration spec): the main
|
|
5
|
+
* ratio — whole fact over the first estimate; `revised` — counted fact over the
|
|
6
|
+
* current estimate of revised tasks. Calibration slices and the applicable
|
|
7
|
+
* coefficient both take it from here.
|
|
8
|
+
*/
|
|
9
|
+
export function ratioSampling(cards, revised) {
|
|
10
|
+
const estimated = cards.filter((card) => card.estimate !== null);
|
|
11
|
+
return revised
|
|
12
|
+
? { ...sampled(estimated.filter(isRevised), revisedExclusion, revisedRatioOf), typeOf: (card) => card.currentEstimate?.type }
|
|
13
|
+
: { ...sampled(estimated, exclusion, ratioOf), typeOf: (card) => card.estimate?.type };
|
|
14
|
+
}
|
|
15
|
+
function sampled(cards, exclude, ratio) {
|
|
16
|
+
const samples = [];
|
|
17
|
+
const excluded = [];
|
|
18
|
+
for (const card of cards) {
|
|
19
|
+
const reason = exclude(card);
|
|
20
|
+
if (reason !== undefined) {
|
|
21
|
+
excluded.push({ card, reason });
|
|
22
|
+
continue;
|
|
23
|
+
}
|
|
24
|
+
const value = ratio(card);
|
|
25
|
+
if (value === undefined) {
|
|
26
|
+
excluded.push({ card, reason: 'renegotiated-without-groups' });
|
|
27
|
+
}
|
|
28
|
+
else {
|
|
29
|
+
samples.push({ card, ratio: value });
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
return { samples, excluded };
|
|
33
|
+
}
|
|
34
|
+
//# sourceMappingURL=ratio-samples.js.map
|
|
@@ -19,9 +19,12 @@ export class Estimate {
|
|
|
19
19
|
basedOn;
|
|
20
20
|
calibrated;
|
|
21
21
|
coefficient;
|
|
22
|
+
pessimisticCoefficient;
|
|
22
23
|
constructor(parts, type, stack, codeVolume, rationale, basedOn, calibrated,
|
|
23
|
-
/** What calibration multiplied the
|
|
24
|
-
coefficient
|
|
24
|
+
/** What calibration multiplied the optimistic and likely hours by; undefined when it was not applied. */
|
|
25
|
+
coefficient,
|
|
26
|
+
/** What calibration multiplied the pessimistic hours by; not part of the base of the estimate. */
|
|
27
|
+
pessimisticCoefficient) {
|
|
25
28
|
this.parts = parts;
|
|
26
29
|
this.type = type;
|
|
27
30
|
this.stack = stack;
|
|
@@ -30,13 +33,23 @@ export class Estimate {
|
|
|
30
33
|
this.basedOn = basedOn;
|
|
31
34
|
this.calibrated = calibrated;
|
|
32
35
|
this.coefficient = coefficient;
|
|
36
|
+
this.pessimisticCoefficient = pessimisticCoefficient;
|
|
33
37
|
}
|
|
34
38
|
/** @throws InvalidEstimate when there are no parts or part ids repeat. */
|
|
35
39
|
static of(input) {
|
|
36
40
|
const issues = [];
|
|
37
|
-
|
|
41
|
+
const positive = (value) => Number.isFinite(value) && value > 0;
|
|
42
|
+
if (input.coefficient === undefined ? input.pessimisticCoefficient !== undefined : !positive(input.coefficient)) {
|
|
38
43
|
issues.push({ path: 'calibration.coefficient', message: 'expected a number greater than 0' });
|
|
39
44
|
}
|
|
45
|
+
const pessimistic = input.pessimisticCoefficient;
|
|
46
|
+
if (pessimistic !== undefined && !positive(pessimistic)) {
|
|
47
|
+
issues.push({ path: 'calibration.pessimistic', message: 'expected a number greater than 0' });
|
|
48
|
+
}
|
|
49
|
+
else if (pessimistic !== undefined && input.coefficient !== undefined && pessimistic < input.coefficient) {
|
|
50
|
+
// `emt calibrate` never gives one below the other: the two are swapped.
|
|
51
|
+
issues.push({ path: 'calibration.pessimistic', message: 'expected no less than calibration.coefficient' });
|
|
52
|
+
}
|
|
40
53
|
if (input.parts.length === 0) {
|
|
41
54
|
issues.push({ path: 'parts', message: 'the estimate needs at least one part' });
|
|
42
55
|
}
|
|
@@ -54,7 +67,7 @@ export class Estimate {
|
|
|
54
67
|
throw new InvalidEstimate(issues);
|
|
55
68
|
}
|
|
56
69
|
const rationale = input.rationale?.trim() || undefined;
|
|
57
|
-
return new Estimate([...input.parts], input.type?.trim() || undefined, stackLabels(input.stack ?? []), input.codeVolume, rationale, [...(input.basedOn ?? [])], input.calibrated ?? false, input.coefficient);
|
|
70
|
+
return new Estimate([...input.parts], input.type?.trim() || undefined, stackLabels(input.stack ?? []), input.codeVolume, rationale, [...(input.basedOn ?? [])], input.calibrated ?? false, input.coefficient, input.pessimisticCoefficient);
|
|
58
71
|
}
|
|
59
72
|
static fromData(data) {
|
|
60
73
|
return Estimate.of({
|
|
@@ -66,6 +79,7 @@ export class Estimate {
|
|
|
66
79
|
...(data.basedOn === undefined ? {} : { basedOn: data.basedOn }),
|
|
67
80
|
calibrated: data.calibrated,
|
|
68
81
|
...(data.calibration === undefined ? {} : { coefficient: data.calibration.coefficient }),
|
|
82
|
+
...(data.calibration?.pessimistic === undefined ? {} : { pessimisticCoefficient: data.calibration.pessimistic }),
|
|
69
83
|
});
|
|
70
84
|
}
|
|
71
85
|
/**
|
|
@@ -92,6 +106,9 @@ export class Estimate {
|
|
|
92
106
|
get groups() {
|
|
93
107
|
return groupsOf(this.parts);
|
|
94
108
|
}
|
|
109
|
+
calibrationData(coefficient) {
|
|
110
|
+
return this.pessimisticCoefficient === undefined ? { coefficient } : { coefficient, pessimistic: this.pessimisticCoefficient };
|
|
111
|
+
}
|
|
95
112
|
toData() {
|
|
96
113
|
return {
|
|
97
114
|
schemaVersion: ESTIMATE_SCHEMA_VERSION,
|
|
@@ -102,7 +119,7 @@ export class Estimate {
|
|
|
102
119
|
...(this.rationale === undefined ? {} : { rationale: this.rationale }),
|
|
103
120
|
...(this.basedOn.length === 0 ? {} : { basedOn: [...this.basedOn] }),
|
|
104
121
|
calibrated: this.calibrated,
|
|
105
|
-
...(this.coefficient === undefined ? {} : { calibration:
|
|
122
|
+
...(this.coefficient === undefined ? {} : { calibration: this.calibrationData(this.coefficient) }),
|
|
106
123
|
};
|
|
107
124
|
}
|
|
108
125
|
}
|
|
@@ -142,7 +142,7 @@ function isEstimateData(value) {
|
|
|
142
142
|
!optional(value['basedOn'], isStringArray) ||
|
|
143
143
|
!optionalString(value['rationale']) ||
|
|
144
144
|
!optional(value['codeVolume'], isObject) ||
|
|
145
|
-
!optional(value['calibration'], (c) => isObject(c) && typeof c['coefficient'] === 'number')) {
|
|
145
|
+
!optional(value['calibration'], (c) => isObject(c) && typeof c['coefficient'] === 'number' && optional(c['pessimistic'], (p) => typeof p === 'number'))) {
|
|
146
146
|
return false;
|
|
147
147
|
}
|
|
148
148
|
try {
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { CalibrationPolicy } from '../../domain/calibration/calibration-policy.js';
|
|
2
2
|
import { isShareMode } from '../../application/ports/sharing-preference.js';
|
|
3
3
|
import { IdlePolicy } from '../../domain/measurement/idle-policy.js';
|
|
4
4
|
import { Author } from '../../domain/shared/author.js';
|
|
@@ -60,11 +60,12 @@ export class YamlConfigStore {
|
|
|
60
60
|
problem: `${this.layout.configFile}: measurement.checkpointMinutes must be a whole number from 10 to 30; using ${DEFAULT_CHECKPOINT_MINUTES}`,
|
|
61
61
|
};
|
|
62
62
|
}
|
|
63
|
-
/** `calibration.minTasks
|
|
64
|
-
|
|
63
|
+
/** `calibration.minTasks` and `calibration.shrink`; a value that is not a number counts as not given. */
|
|
64
|
+
policy() {
|
|
65
65
|
const calibration = this.read()['calibration'];
|
|
66
|
-
const
|
|
67
|
-
|
|
66
|
+
const settings = typeof calibration === 'object' && calibration !== null ? calibration : {};
|
|
67
|
+
const number = (value) => (typeof value === 'number' ? value : undefined);
|
|
68
|
+
return CalibrationPolicy.fromConfig({ minTasks: number(settings['minTasks']), shrink: number(settings['shrink']) });
|
|
68
69
|
}
|
|
69
70
|
/** `author.aliases`: strings other than the author's own id; anything but a list counts as none. */
|
|
70
71
|
authorAliases() {
|
|
@@ -74,7 +74,7 @@ class EstimateParser {
|
|
|
74
74
|
this.issue('calibrated', 'expected true or false');
|
|
75
75
|
}
|
|
76
76
|
const codeVolume = this.codeVolume(value['codeVolume']);
|
|
77
|
-
const
|
|
77
|
+
const calibration = this.calibration(value['calibration']);
|
|
78
78
|
if (this.issues.length > 0 || parts.some((part) => part === undefined)) {
|
|
79
79
|
return undefined;
|
|
80
80
|
}
|
|
@@ -86,24 +86,32 @@ class EstimateParser {
|
|
|
86
86
|
...(rationale === undefined ? {} : { rationale }),
|
|
87
87
|
...(codeVolume === undefined ? {} : { codeVolume }),
|
|
88
88
|
calibrated: calibrated === true,
|
|
89
|
-
...
|
|
89
|
+
...calibration,
|
|
90
90
|
}));
|
|
91
91
|
}
|
|
92
|
-
|
|
92
|
+
calibration(value) {
|
|
93
93
|
if (value === undefined) {
|
|
94
|
-
return
|
|
94
|
+
return {};
|
|
95
95
|
}
|
|
96
96
|
if (!isObject(value)) {
|
|
97
97
|
this.issue('calibration', 'expected a mapping with `coefficient`');
|
|
98
|
-
return
|
|
99
|
-
}
|
|
100
|
-
this.unknownFields(value, ['coefficient'], 'calibration.');
|
|
101
|
-
const coefficient = value['coefficient'];
|
|
102
|
-
if (typeof coefficient !== 'number' || !(coefficient > 0)) {
|
|
103
|
-
this.issue('calibration.coefficient', 'expected a number greater than 0');
|
|
104
|
-
return undefined;
|
|
98
|
+
return {};
|
|
105
99
|
}
|
|
106
|
-
|
|
100
|
+
this.unknownFields(value, ['coefficient', 'pessimistic'], 'calibration.');
|
|
101
|
+
const positive = (field) => {
|
|
102
|
+
const number = value[field];
|
|
103
|
+
if (typeof number !== 'number' || !(number > 0)) {
|
|
104
|
+
this.issue(`calibration.${field}`, 'expected a number greater than 0');
|
|
105
|
+
return undefined;
|
|
106
|
+
}
|
|
107
|
+
return number;
|
|
108
|
+
};
|
|
109
|
+
const coefficient = positive('coefficient');
|
|
110
|
+
const pessimistic = value['pessimistic'] === undefined ? undefined : positive('pessimistic');
|
|
111
|
+
return {
|
|
112
|
+
...(coefficient === undefined ? {} : { coefficient }),
|
|
113
|
+
...(pessimistic === undefined ? {} : { pessimisticCoefficient: pessimistic }),
|
|
114
|
+
};
|
|
107
115
|
}
|
|
108
116
|
part(value, path) {
|
|
109
117
|
if (!isObject(value)) {
|
|
@@ -15,7 +15,7 @@ estimetry compares estimates with the actual effort of AI-agent development and
|
|
|
15
15
|
Never name an effort or a deadline for a task before \`{{skill:emt-estimate}}\` is done, even when asked casually. The estimate rests on the user's own past tasks, not on a general sense of how long things take:
|
|
16
16
|
- agree with the user on the task type and the technologies the task really touches;
|
|
17
17
|
- \`emt similar\` shows closed tasks like it, \`emt calibrate\` the user's coefficients and the one the estimate may apply;
|
|
18
|
-
- with a coefficient, multiply the hours of every part by
|
|
18
|
+
- with a coefficient, multiply the optimistic and most likely hours of every part by its value, the pessimistic hours by its pessimistic value; without one, say plainly that the estimate is without calibration and why;
|
|
19
19
|
- give the estimate by parts of the plan, each with optimistic, most likely and pessimistic hours, and save it only after the user approves it.
|
|
20
20
|
|
|
21
21
|
## Measuring
|
|
@@ -64,12 +64,14 @@ export const COMMANDS = [
|
|
|
64
64
|
3. **Parts.** Split the work into parts of the plan with hours as optimistic ≤ most likely ≤ pessimistic. Include manual testing and review when the work needs them. Add up a preliminary most likely total.
|
|
65
65
|
With a development flow (OpenSpec), link every part to its change: \`group\` is the name of the change. When the change does not exist yet, agree its kebab-case name with the user now, put it into \`group\`, and create the change under exactly that name later — otherwise progress, completion of changes and the fact by parts cannot follow the estimate. Several changes give several groups.
|
|
66
66
|
4. **Similar tasks.** \`emt similar --type <type> --stack <a,b> --hours <preliminary total> --json\`. Compare the parts with the facts of the similar tasks, their extra work and lessons; adjust the parts. Name the tasks you rely on — they go into \`basedOn\`. If there are none, say so.
|
|
67
|
-
5. **Calibration.** \`emt calibrate --type <type> --stack <a,b> --json\`.
|
|
68
|
-
- If \`coefficient\` is not null, multiply the optimistic
|
|
69
|
-
- If \`coefficient\` is null, say plainly that the estimate is **without calibration** and why
|
|
67
|
+
5. **Calibration.** \`emt calibrate --type <type> --stack <a,b> --json\`. Apply only the coefficient \`emt calibrate\` gives, never one of your own.
|
|
68
|
+
- If \`coefficient\` is not null, multiply the optimistic and most likely hours of every part by \`coefficient.value\` and the pessimistic hours by \`coefficient.pessimistic\`, and write \`calibrated: true\` and \`calibration: { coefficient: <value>, pessimistic: <pessimistic> }\`. Name the slice, the number of tasks and the weight, for example "×0.59 from 3 feature tasks, weight 60%". With a weight below 50% (one task at the default \`shrink\`), say that there is little experience yet and the coefficient is cautious; at 50% or more, do not call it cautious.
|
|
69
|
+
- If \`coefficient\` is null, say plainly that the estimate is **without calibration** and why, as \`emt calibrate\` without \`--json\` words it: no closed task yet, fewer closed tasks than the user set in \`calibration.minTasks\`, every closed task left out or none of them has an estimate, or cards it could not read (estimetry needs an update). Write \`calibrated: false\`.
|
|
70
|
+
- A revision (\`--revise\`) follows the same rules with the coefficient of estimates made during work.
|
|
70
71
|
6. **Reserve.** Put a reserve only into the pessimistic hours, never into the most likely hours or a part of its own, and name its source in \`rationale\`:
|
|
71
72
|
- with calibration, only for missed scope (\`missedScope\`): extra work absorbed by tasks is already in the coefficient;
|
|
72
73
|
- without calibration, for extra work (\`extras\`, absorbed) and missed scope.
|
|
74
|
+
The reserve goes on top of the pessimistic hours already multiplied by \`coefficient.pessimistic\`: that coefficient covers how little the ratio is known yet, it is not a reserve for extra work.
|
|
73
75
|
Cross-check with lines per hour (\`linesPerHour\`, \`codeVolume\`) only as a self-check: if it disagrees strongly, say so and explain, but do not recompute the estimate from lines.
|
|
74
76
|
7. **Approval.** Show the estimate as a table: parts, hours, what it rests on (similar tasks, coefficient or "without calibration", reserve). Wait for the user to approve or change it.
|
|
75
77
|
8. **Save.** Write the approved estimate to a YAML file outside the repository, for example in a temporary directory, and save it: \`emt estimate save <file>\` (for a task in progress: \`emt estimate revise <file> ...\`, see the estimetry skill). If it reports errors, fix every listed field and save again.
|
|
@@ -80,14 +82,14 @@ export const COMMANDS = [
|
|
|
80
82
|
stack: [typescript, node]
|
|
81
83
|
basedOn: [T-12, T-17]
|
|
82
84
|
calibrated: true
|
|
83
|
-
calibration: { coefficient: 1.
|
|
85
|
+
calibration: { coefficient: 1.23, pessimistic: 1.64 }
|
|
84
86
|
rationale: Why the numbers are what they are, what they rest on, where the reserve is.
|
|
85
87
|
parts:
|
|
86
88
|
- name: implementation
|
|
87
89
|
kind: implementation # analysis, implementation, auto-tests, manual-testing, review, docs, other
|
|
88
90
|
who: agents # agents, user or both
|
|
89
91
|
group: export-invoices-pdf # the change of the part, with a development flow
|
|
90
|
-
hours: { optimistic: 2.
|
|
92
|
+
hours: { optimistic: 2.46, likely: 3.69, pessimistic: 6.56 }
|
|
91
93
|
\`\`\`
|
|
92
94
|
|
|
93
95
|
9. Tell the user that time is not measured until the task starts, and offer to start it now with \`{{skill:emt-start}}\` (\`emt start\`; \`--at "YYYY-MM-DD HH:MM"\` if work already began).
|
|
@@ -1,10 +1,28 @@
|
|
|
1
|
+
import { CalibrationPolicy } from '../../../domain/calibration/calibration-policy.js';
|
|
1
2
|
import { presenterFor } from '../cli-context.js';
|
|
2
3
|
import { parseLabels } from '../parse-input.js';
|
|
4
|
+
const { minTasks, shrink } = CalibrationPolicy.DEFAULT;
|
|
5
|
+
/**
|
|
6
|
+
* The settings `emt calibrate` follows: help names them with the defaults of
|
|
7
|
+
* the policy, the README shows what to expect from each. The data directory is
|
|
8
|
+
* resolved as `StorageLayout.resolve` does.
|
|
9
|
+
*/
|
|
10
|
+
const SETTINGS_HELP = `
|
|
11
|
+
Settings, in config.yaml of the data directory ($ESTIMETRY_HOME, else
|
|
12
|
+
$XDG_DATA_HOME/estimetry, else ~/.local/share/estimetry):
|
|
13
|
+
calibration.minTasks a slice counts from this many closed tasks; with fewer
|
|
14
|
+
in all your tasks there is no coefficient (default ${minTasks})
|
|
15
|
+
calibration.shrink k in the weight n / (n + k) of a slice: larger is more
|
|
16
|
+
cautious, 0 applies the median as it is (default ${shrink})
|
|
17
|
+
minTasks set without shrink means shrink: 0; minTasks: 5 alone gives the
|
|
18
|
+
coefficients of 0.2. Change them and run calibrate again: it recomputes from
|
|
19
|
+
your cards at once. The README shows what to expect from each setting.`;
|
|
3
20
|
export function registerCalibrateCommand(program, ctx) {
|
|
4
21
|
program
|
|
5
22
|
.command('calibrate')
|
|
6
23
|
.helpGroup('Tasks and estimates')
|
|
7
24
|
.description('show your coefficients for a type and a stack, and the one an estimate may apply')
|
|
25
|
+
.addHelpText('after', SETTINGS_HELP)
|
|
8
26
|
.option('--type <type>', 'task type of the task being estimated')
|
|
9
27
|
.option('--stack <labels>', 'comma-separated technologies the task touches; defaults to the stack of the project')
|
|
10
28
|
.option('--revise', 'for a revision of a task in progress: the coefficient of estimates made during work')
|
|
@@ -105,7 +105,9 @@ export function formatHelp(command, helper) {
|
|
|
105
105
|
}
|
|
106
106
|
if (root) {
|
|
107
107
|
out.push('Options:', ...helper.visibleOptions(command).map((option) => row(` ${optionTerm(option)}`, optionText(option))));
|
|
108
|
-
out.push(` Most commands print JSON with --json
|
|
108
|
+
out.push(` Most commands print JSON with --json.`);
|
|
109
|
+
out.push(` Settings: config.yaml in $ESTIMETRY_HOME, else $XDG_DATA_HOME/estimetry,`);
|
|
110
|
+
out.push(` else ~/.local/share/estimetry; those of calibration: "${name} help calibrate".`, '');
|
|
109
111
|
out.push('Examples:', ...EXAMPLES.map((example) => ` ${example.split(' && ').map((part) => `${name} ${part}`).join(' && ')}`), '');
|
|
110
112
|
out.push(`Run "${name} <command> --help" for details, e.g. "${name} help task new".`);
|
|
111
113
|
}
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { CalibrationPolicy } from '../../../../domain/calibration/calibration-policy.js';
|
|
1
2
|
import { formatMinutes, percent, table } from './format.js';
|
|
2
3
|
export function similarText(view) {
|
|
3
4
|
const query = [
|
|
@@ -71,7 +72,7 @@ function queried(slices) {
|
|
|
71
72
|
}
|
|
72
73
|
export function calibrationText(view) {
|
|
73
74
|
const slices = queried(view.ratio);
|
|
74
|
-
const lines = [coefficientLine(view,
|
|
75
|
+
const lines = [coefficientLine(view), settingsLine(view)];
|
|
75
76
|
lines.push('', 'Fact over the first estimate:');
|
|
76
77
|
const ratioRows = [
|
|
77
78
|
['overall', statsText(view.ratio.overall)],
|
|
@@ -102,25 +103,47 @@ export function calibrationText(view) {
|
|
|
102
103
|
lines.push(...cardNotes({ skipped: [], otherAuthors: view.otherAuthors }));
|
|
103
104
|
return lines.join('\n');
|
|
104
105
|
}
|
|
105
|
-
/** The coefficient to apply, or why there is none. */
|
|
106
|
-
function coefficientLine(view
|
|
106
|
+
/** The coefficient to apply with what it rests on, or why there is none. */
|
|
107
|
+
function coefficientLine(view) {
|
|
107
108
|
const coefficient = view.coefficient;
|
|
108
|
-
const what = view.query.revise ? 'estimates made during work' : 'first estimates';
|
|
109
109
|
if (coefficient !== null) {
|
|
110
|
-
|
|
111
|
-
|
|
110
|
+
const what = view.query.revise ? 'estimates made during work' : 'first estimates';
|
|
111
|
+
const slice = coefficient.slice.kind === 'overall' ? 'overall' : `${coefficient.slice.kind} ${coefficient.slice.key}`;
|
|
112
|
+
const value = times(coefficient.value);
|
|
113
|
+
const pessimistic = times(coefficient.pessimistic);
|
|
114
|
+
return (`Coefficient ${value} from ${coefficient.n} ${coefficient.n === 1 ? 'task' : 'tasks'} (weight ${percent(coefficient.weight)}), ` +
|
|
115
|
+
`slice ${slice}; pessimistic ${pessimistic} (${what}): ` +
|
|
116
|
+
`multiply the optimistic and most likely hours of every part by ${value}, the pessimistic hours by ${pessimistic}.`);
|
|
112
117
|
}
|
|
113
118
|
if (view.skipped.length > 0) {
|
|
114
119
|
// Not the sample: calibration without some cards could name a wrong coefficient.
|
|
115
120
|
return (`Without calibration: cards of a newer estimetry (${view.skipped.join(', ')}) cannot be read, ` +
|
|
116
121
|
'so no coefficient is given — update estimetry.');
|
|
117
122
|
}
|
|
118
|
-
const counts = (view.query.revise ? queried(view.revised) : slices).map(([name, stats]) => `${name} ${stats.n} of ${view.minTasks}`);
|
|
119
123
|
const overall = view.query.revise ? view.revised.overall : view.ratio.overall;
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
+
if (view.tasks === 0) {
|
|
125
|
+
return 'Without calibration: no closed task yet.';
|
|
126
|
+
}
|
|
127
|
+
if (overall.n === 0) {
|
|
128
|
+
if (view.query.revise) {
|
|
129
|
+
return 'Without calibration: no revised task counts yet.';
|
|
130
|
+
}
|
|
131
|
+
// A card without an estimate is neither a sample nor left out: there is nothing below to point to.
|
|
132
|
+
return Object.keys(overall.excluded).length === 0
|
|
133
|
+
? 'Without calibration: none of the closed tasks has an estimate.'
|
|
134
|
+
: 'Without calibration: none of the closed tasks counts (see what is left out below).';
|
|
135
|
+
}
|
|
136
|
+
return `Without calibration: ${overall.n} of ${view.minTasks} tasks needed (calibration.minTasks).`;
|
|
137
|
+
}
|
|
138
|
+
/** The calibration settings in force, with or without a coefficient; `emt help calibrate` describes them. */
|
|
139
|
+
function settingsLine(view) {
|
|
140
|
+
const defaults = view.minTasks === CalibrationPolicy.DEFAULT.minTasks && view.shrink === CalibrationPolicy.DEFAULT.shrink;
|
|
141
|
+
const mark = defaults ? ' (the defaults)' : '';
|
|
142
|
+
return `Settings: calibration.minTasks ${view.minTasks}, calibration.shrink ${view.shrink}${mark}; see emt help calibrate.`;
|
|
143
|
+
}
|
|
144
|
+
/** A coefficient in text: two decimals are enough to read; `--json` keeps three. */
|
|
145
|
+
function times(value) {
|
|
146
|
+
return `×${Math.round(value * 100) / 100}`;
|
|
124
147
|
}
|
|
125
148
|
/** Revisions by category and `spent`, and extra work by category: shares of the base. */
|
|
126
149
|
function revisionAndExtraLines(view) {
|
|
@@ -148,7 +171,9 @@ function statsText(stats) {
|
|
|
148
171
|
return 'no tasks';
|
|
149
172
|
}
|
|
150
173
|
const excluded = Object.entries(stats.excluded).map(([reason, n]) => `${reason} ${n}`);
|
|
151
|
-
|
|
174
|
+
// The weight of a whole slice is not what its level weighs in the coefficient: only the coefficient line names one.
|
|
175
|
+
const tooFew = stats.weight > 0 ? '' : ', too few to apply';
|
|
176
|
+
return (`${stats.n} tasks, median ×${stats.median}, mean ×${stats.mean}${tooFew}` +
|
|
152
177
|
`${stats.revised > 0 ? `, ${stats.revised} revised` : ''}${stats.uncertain > 0 ? `, ${stats.uncertain} uncertain` : ''}` +
|
|
153
178
|
`${excluded.length > 0 ? `; left out: ${excluded.join(', ')}` : ''}`);
|
|
154
179
|
}
|
|
@@ -170,7 +195,7 @@ export function estimateText(estimate) {
|
|
|
170
195
|
const context = [
|
|
171
196
|
estimate.type,
|
|
172
197
|
estimate.stack === undefined ? undefined : estimate.stack.join(', '),
|
|
173
|
-
estimate.calibrated ?
|
|
198
|
+
estimate.calibrated ? calibratedText(estimate.calibration) : 'without calibration',
|
|
174
199
|
estimate.basedOn === undefined ? undefined : `based on ${estimate.basedOn.join(', ')}`,
|
|
175
200
|
].filter((part) => part !== undefined);
|
|
176
201
|
return table([
|
|
@@ -182,4 +207,8 @@ export function estimateText(estimate) {
|
|
|
182
207
|
}),
|
|
183
208
|
]);
|
|
184
209
|
}
|
|
210
|
+
function calibratedText(calibration) {
|
|
211
|
+
const pessimistic = calibration?.pessimistic === undefined ? '' : `, pessimistic ×${calibration.pessimistic}`;
|
|
212
|
+
return `calibrated ×${calibration?.coefficient ?? '?'}${pessimistic}`;
|
|
213
|
+
}
|
|
185
214
|
//# sourceMappingURL=estimate-text.js.map
|