dckc
fe3f9dae75
The description repeated the body's procedure (which file, the losing diagnosis, the exact winning? replies). Keep only trigger phrases and artifact names, and add two missed triggers: reading a recording without the magic words, and how to set one up. Drop the link to ../lab-notebook-template.md and the mention of a `watchme` specimen capture; neither exists in this repo. Generated-by: Claude Opus 5.5
3.5 KiB
name, description
| name | description |
|---|---|
| watchme | Watch me — terminal / shell session recorded with `script -f` (a typescript, `.tmp/*.script`) as shared ground truth. Use when the operator says "watch me", "losing", or "winning?"; when diagnosing a shell session from its recorded transcript instead of asking for a re-telling; when asked how to record a terminal session. |
Watch Me: a typescript as shared ground truth
Long, interactive, or risky sessions happen in a terminal whose scrollback
dies with the window. script -f xyz.script records the whole session to a
file in the working directory, so both the operator and an agent can read
what was done and what the machine said.
Pattern
Start the recording before the work:
script -f xyz.script
-fflushes after each write, so the tail is readable while the session is still running — not only after it ends.- Name the file for the task, next to the work:
.tmp/mouse-problem.script,.tmp/dm93.script— under.tmp/at the workspace root. The name is the shared handle; it is how the operator later says "watch me" and points the agent at the log. Unless the operator names a file, the newest.tmp/*.scriptis the one in play.
Then drive the actual work inside the recorded shell. When something stalls or finishes, the operator invokes one of two moves.
The two triggers
"losing" — read the tail of the script for what was done and the symptoms: the commands typed, the errors, warnings, and hang signs they produced. Diagnose from that evidence rather than asking the operator to re-tell it.
"winning?" — compare the tail of the script against the current goal and answer one of exactly two ways:
- "Yes, that's as expected; next, do X." — the session did what it should; the goal is not met yet.
- "Yes, as expected. Done!" — the session did what it should and the goal is met.
The goal is the yardstick; the script is the claim. Resist an in-between "partially winning": winning is a verdict against the goal, not a read on the moment. A run that ends short of the goal was never winning — a team ahead 4–1 in the third that loses 6–4 was losing all along.
What the log gives you
A util-linux script capture brackets the session:
Script started on 2026-09-02 23:47:55-05:00 [TERM="linux" TTY="/dev/tty1" COLUMNS="240" LINES="67"]
...
Script done on 2026-09-02 23:48:46-05:00 [COMMAND_EXIT_CODE="0"]
The header records when, on which TTY, and the terminal geometry; the footer records the exit code.
For a longer session the value is that one file holds both halves of the
story: the operator's commands and the machine's responses, interleaved in
order. tail it while it is live; grep it after the fact.
Relationship to the lab notebook
The typescript is raw evidence; a lab notebook is interpretation. Read the script to establish what happened, then promote the finding — hypothesis, evidence, next question — into a notebook entry so it survives independently of the transcript.
Caveats
- Typescripts carry terminal control sequences: bracketed-paste markers,
color codes, and cursor movement appear inline (e.g.
[?2004h). Read through them, or filter before quoting. - Captures grow fast — tens of thousands of lines for a long session. Read the tail by default, not the whole file.
- These are local working artifacts, not deliverables. Keep them out of version control unless a session is itself the thing worth preserving.
Reference
man script(util-linux) —-f,--flush