recording-work-time

Recording work time

Strict and mechanical. Do these things at these moments. No judgement calls, no interpretation, no estimation reasoning — this skill exists so that referencing it does not pull estimation ideas into a working session.

Starting an effort

start_effort(title, kind, plan_path, summary_text, optimistic, likely, pessimistic, rationale, work_slices) creates the effort and takes the plan's slice titles up front, as work_slices, a list of titles. This is not incidental: the initial slice count is what makes later drift measurable. Do not create the effort with an empty slice list and add slices afterwards to get to the plan's real inventory — that throws away the baseline. Once the effort is under way, add_slice is for slices that were not in that original list — scope growth, not initial setup.

When to clock in

• Starting work on a slice: clock_in(effort, work_slice).
• Starting effort-level work with no slice — a design conversation, a retrospective: clock_in(effort).
• A meeting that is part of the work: clock_in(effort, kind="meeting", internal=<people we pay for, including the user>, external=<people we do not>, participants=<names, if known now>).

clock_in refuses when an interval is already open. That refusal is correct; clock out first rather than working around it.

clock_in also refuses when work_slice is given but is not a live slice on that effort — dropped, or simply mistyped — raising UnknownSlice. A stale slice identifier is a plausible mistake mid-effort; treat the refusal as a prompt to check the identifier, not as something to route around. A closed slice is still clockable, deliberately: a merged pull request can still need post-merge fixes, and that time belongs to the slice it came from.

If the names were not to hand when clocking into the meeting, participants can be left out and attached later — or corrected — with annotate_interval(effort, interval, internal=, external=, participants=, note=). It works on any interval, not only meetings, and is also the way to attach a note after the fact.