Session Observatory — Live Event Logging
Most session retrospectives are written from memory at the end. Memory is
lossy. This skill captures the habit of logging events as they happen, so the
retrospective has real data to work with.
When to Activate
- At session start — log
start <mission-name> as one of the first
Bash tool calls, so the started_commit is recorded.
- When friction hits — hook fired repeatedly, tool failed, command took
longer than expected, user corrected you.
- When something works unusually well — a technique that you'd recommend
to future sessions.
- Before and after irreversible actions — commits, pushes, destructive ops.
- On progress markers — every ~10% through a long job.
- At session close — log
end, then run generate.mjs to produce the
SESSION-RETRO.md.
Commands
# Start
node tools/session-retro/observe.mjs start "<mission-name>"
# Log an event
node tools/session-retro/observe.mjs event <kind> "<label>" '<json-payload>'
# Check in on the log
node tools/session-retro/observe.mjs status
# End (archives current.jsonl to a dated file)
node tools/session-retro/observe.mjs end
Event Kinds (standard)
| Kind |
When |
Example label |
friction |
Something took more effort than it should have |
"read-before-edit hook fired N times" |
win |
Something worked notably well |
"idempotent pipeline saved 3 re-runs" |
correction |
User or hook corrected direction |
"user reminded: no Co-Authored-By" |
tool-use |
Notable tool invocation |
"installed better-sqlite3 as optional dep" |
decision |
Judgment call deserving review |
"committed 1,881 generated files" |
gap |
Missing skill/agent/chipset |
"no batch-rewriter for N-script cascade" |
checkpoint |
Progress marker for long-running work |
"Pass 2 chapters: 300/602" |
Free-form kinds are allowed but less useful for aggregation. Prefer the
standard list.
Payload Conventions
Payloads are free-form JSON. Common fields:
count — numeric count of the occurrencefile / files — paths involvedduration_min — wall-clock timecost / tokens — resource spendimpact — "workflow" | "output" | "blocked" | "none"opportunity — what skill/agent would have helped
Retroactive Logging
If you didn't log live, you can backfill at session close by reviewing what
happened and calling observe event for each remembered moment. Better than
nothing. The timestamp will be session-end rather than event-time, but the
kinds and labels are still useful.
Integration with Retrospective Generator
Events from current.jsonl are consumed by
tools/session-retro/generate.mjs and rendered in the SESSION-RETRO.md under
Observations, grouped by kind. The human-authored sections
(What Worked, What Could Be Better) then reference specific events as
evidence.
Example — This Skill's First Use
The release-history feature session logged 33 events retroactively:
- 6 friction (read-before-edit fires, 11-script cascade, no checkpoint for
LLM run, ghost-seeding cascade, over-eager regex, hidden drift)
- 4 wins (background Monitor, idempotent pipeline, recursive self-improvement,
fresh-repo demo)
- 3 corrections (no Co-Authored-By, dev not main, link chapter files)
- 4 decisions (publish full tree, SQLite default, allowlist gates, Commits column)
- 4 gaps (batch-rewriter, portable-schema, decision-framework, session-token)
- 3 tool-uses (better-sqlite3, claude -p, git tags)
- 9 checkpoints (pass-by-pass progress)
Those 33 events became the concrete evidence for the retro's
"What Worked" / "What Could Be Better" / "Recommendations" sections.
Anti-patterns
- Logging every command. Too noisy. Log inflection points.
- Vague labels. "Problem happened" is useless. "Retro extractor missed
H3 headings — 57 files hid as a result" is useful.
- Skipping at session close. The log isn't useful if
end never runs
and the JSONL never archives. Generate the retro before context dies.
Related
tools/session-retro/observe.mjs — the logger itselftools/session-retro/generate.mjs — the retrospective generatordecision-framework-invoker — often co-fires with decision events
1---2name: session-observatory-live3description: Conversational guide for using tools/session-retro/observe.mjs to capture friction, wins, corrections, decisions, gaps, tool-use, and checkpoints as they happen during a session. Use at session start (to kick off the log), at inflection points (to record events), and at session end (to archive and feed the retrospective generator).4---5
6# Session Observatory — Live Event Logging
7
8Most session retrospectives are written from memory at the end. Memory is
9lossy. This skill captures the habit of logging events as they happen, so the
10retrospective has real data to work with.
11
12## When to Activate
13
14- **At session start** — log `start <mission-name>` as one of the first
15 Bash tool calls, so the started_commit is recorded.
16- **When friction hits** — hook fired repeatedly, tool failed, command took
17 longer than expected, user corrected you.
18- **When something works unusually well** — a technique that you'd recommend
19 to future sessions.
20- **Before and after irreversible actions** — commits, pushes, destructive ops.
21- **On progress markers** — every ~10% through a long job.
22- **At session close** — log `end`, then run `generate.mjs` to produce the
23 SESSION-RETRO.md.
24
25## Commands
26
27```bash
28# Start
29node tools/session-retro/observe.mjs start "<mission-name>"
30
31# Log an event
32node tools/session-retro/observe.mjs event <kind> "<label>" '<json-payload>'
33
34# Check in on the log
35node tools/session-retro/observe.mjs status
36
37# End (archives current.jsonl to a dated file)
38node tools/session-retro/observe.mjs end
39```
40
41## Event Kinds (standard)
42
43| Kind | When | Example label |
44|------|------|---------------|
45| `friction` | Something took more effort than it should have | `"read-before-edit hook fired N times"` |
46| `win` | Something worked notably well | `"idempotent pipeline saved 3 re-runs"` |
47| `correction` | User or hook corrected direction | `"user reminded: no Co-Authored-By"` |
48| `tool-use` | Notable tool invocation | `"installed better-sqlite3 as optional dep"` |
49| `decision` | Judgment call deserving review | `"committed 1,881 generated files"` |
50| `gap` | Missing skill/agent/chipset | `"no batch-rewriter for N-script cascade"` |
51| `checkpoint` | Progress marker for long-running work | `"Pass 2 chapters: 300/602"` |
52
53Free-form kinds are allowed but less useful for aggregation. Prefer the
54standard list.
55
56## Payload Conventions
57
58Payloads are free-form JSON. Common fields:
59
60- `count` — numeric count of the occurrence
61- `file` / `files` — paths involved
62- `duration_min` — wall-clock time
63- `cost` / `tokens` — resource spend
64- `impact` — `"workflow"` | `"output"` | `"blocked"` | `"none"`
65- `opportunity` — what skill/agent would have helped
66
67## Retroactive Logging
68
69If you didn't log live, you can backfill at session close by reviewing what
70happened and calling `observe event` for each remembered moment. Better than
71nothing. The timestamp will be session-end rather than event-time, but the
72kinds and labels are still useful.
73
74## Integration with Retrospective Generator
75
76Events from `current.jsonl` are consumed by
77`tools/session-retro/generate.mjs` and rendered in the SESSION-RETRO.md under
78**Observations**, grouped by kind. The human-authored sections
79(`What Worked`, `What Could Be Better`) then reference specific events as
80evidence.
81
82## Example — This Skill's First Use
83
84The release-history feature session logged 33 events retroactively:
85- 6 friction (read-before-edit fires, 11-script cascade, no checkpoint for
86 LLM run, ghost-seeding cascade, over-eager regex, hidden drift)
87- 4 wins (background Monitor, idempotent pipeline, recursive self-improvement,
88 fresh-repo demo)
89- 3 corrections (no Co-Authored-By, dev not main, link chapter files)
90- 4 decisions (publish full tree, SQLite default, allowlist gates, Commits column)
91- 4 gaps (batch-rewriter, portable-schema, decision-framework, session-token)
92- 3 tool-uses (better-sqlite3, claude -p, git tags)
93- 9 checkpoints (pass-by-pass progress)
94
95Those 33 events became the concrete evidence for the retro's
96"What Worked" / "What Could Be Better" / "Recommendations" sections.
97
98## Anti-patterns
99
100- **Logging every command.** Too noisy. Log inflection points.
101- **Vague labels.** "Problem happened" is useless. "Retro extractor missed
102 H3 headings — 57 files hid as a result" is useful.
103- **Skipping at session close.** The log isn't useful if `end` never runs
104 and the JSONL never archives. Generate the retro before context dies.
105
106## Related
107
108- `tools/session-retro/observe.mjs` — the logger itself
109- `tools/session-retro/generate.mjs` — the retrospective generator
110- `decision-framework-invoker` — often co-fires with `decision` events
majiayu000