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
89 lines
3.5 KiB
Markdown
89 lines
3.5 KiB
Markdown
---
|
||
name: watchme
|
||
description: 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:
|
||
|
||
```sh
|
||
script -f xyz.script
|
||
```
|
||
|
||
- `-f` flushes 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/*.script` is 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`
|