What happened
During an Akiflow backfill of 2026-08-23 I needed to size one work block: how long was Elliot actually in session dd8f02c7 ("Session ID validity check"). Instead of running one command, I dumped user prompts with --mode dump --role user --format json, printed 22 raw timestamps, and eyeballed the clusters by hand to guess "~40 min, then a break, then ~28 min."
--mode engagement --break 20m answers it exactly, in one line:
57m ratio 0.33 you 22 ai 84 12:24pm-3:16pm Other Claude Code - Session ID validity check [dd8f02c7]
Total: 57m active across 1 session(s), 12:24pm-3:16pm span (2h51m)
Breaks >20m in the merged stream: 1 - 1:04pm->2:05pm (1h00m)
Prompt gaps: median 2m, p90 14m
Per-session active minutes, a summed total, the wall-clock span, AND every break named with start/end. My hand estimate was wrong (28m vs the real ~17m for the back half).
Why I missed it
references/modes.md documents engagement correctly and completely - the mechanics, --break, the attention semantics. The problem is SKILL.md, which is what actually gets read first:
- The quick-lookup table row is
| My real attention time | python "$PY" --mode engagement --date today |. "My real attention time" reads as a vanity/self-tracking metric, not as "the deterministic way to size a block of work from a transcript."
- Neither
--break nor --gap appears anywhere in SKILL.md. There is a prose callout for dump ("the workhorse for what happened in this window") and one for Codex review gates, but nothing equivalent for engagement.
- Result: the ladder in SKILL.md sent me to step 2 (post-process
dump JSON) for a question step 1 already answers.
Requested change
In skills/estack-read-agent-history/SKILL.md:
- Reword the quick-lookup row so it names the job, e.g.
| **How long was I actually in this? (sizes a block)** | python "$PY" --mode engagement --file <s.jsonl> --break 20m |
- Add a short prose callout next to the existing
dump one, saying engagement does the math (active minutes + total + span + named breaks) and that hand-reading prompt timestamps to size a block is the anti-pattern it exists to prevent.
- Name the two tuning knobs in SKILL.md, since they change the answer:
--break (default 10m, engagement) and --gap (default 15m, timeline blocks).
Related
~/.claude/skills/akiflow-backfill/SKILL.md Step 4 trigger #1 pointed at --mode session-report for this question. I have changed it to point at engagement and to route to this skill for the flags rather than restating them - one source of truth, no divergence. Filing here so the substance lives in this skill.
What happened
During an Akiflow backfill of 2026-08-23 I needed to size one work block: how long was Elliot actually in session
dd8f02c7("Session ID validity check"). Instead of running one command, I dumped user prompts with--mode dump --role user --format json, printed 22 raw timestamps, and eyeballed the clusters by hand to guess "~40 min, then a break, then ~28 min."--mode engagement --break 20manswers it exactly, in one line:Per-session active minutes, a summed total, the wall-clock span, AND every break named with start/end. My hand estimate was wrong (28m vs the real ~17m for the back half).
Why I missed it
references/modes.mddocumentsengagementcorrectly and completely - the mechanics,--break, the attention semantics. The problem isSKILL.md, which is what actually gets read first:| My real attention time | python "$PY" --mode engagement --date today |. "My real attention time" reads as a vanity/self-tracking metric, not as "the deterministic way to size a block of work from a transcript."--breaknor--gapappears anywhere in SKILL.md. There is a prose callout fordump("the workhorse for what happened in this window") and one for Codex review gates, but nothing equivalent forengagement.dumpJSON) for a question step 1 already answers.Requested change
In
skills/estack-read-agent-history/SKILL.md:| **How long was I actually in this? (sizes a block)** | python "$PY" --mode engagement --file <s.jsonl> --break 20m |dumpone, sayingengagementdoes the math (active minutes + total + span + named breaks) and that hand-reading prompt timestamps to size a block is the anti-pattern it exists to prevent.--break(default 10m, engagement) and--gap(default 15m, timeline blocks).Related
~/.claude/skills/akiflow-backfill/SKILL.mdStep 4 trigger #1 pointed at--mode session-reportfor this question. I have changed it to point atengagementand to route to this skill for the flags rather than restating them - one source of truth, no divergence. Filing here so the substance lives in this skill.