From 60936a86e93c30fa3ef7931e7aab231455b5de70 Mon Sep 17 00:00:00 2001
From: Dan Connolly <dckc@madmode.com>
Date: Wed, 7 Oct 2026 00:43:14 -0500
Subject: [PATCH] Add watchme skill

---
 watchme/SKILL.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 watchme/SKILL.md

diff --git a/watchme/SKILL.md b/watchme/SKILL.md
new file mode 100644
index 0000000..7d09727
--- /dev/null
+++ b/watchme/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: watchme
+description: Use when the operator says "watch me", "losing", or "winning?" about a session recorded with `script -f xyz.script` — the typescript is shared ground truth. Unless otherwise stated, the newest `.tmp/*.script` is the file to look at. For "losing", read the tail for what was done and what the machine said, diagnosing from evidence instead of asking for a re-telling. For "winning?", answer one of exactly "Yes, that's as expected; next, do X." or "Yes, as expected. Done!" — no partial verdicts.
+---
+
+# 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. `watchme` is a short specimen — the smallest useful
+capture, including the escape noise described below.
+
+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; the [lab notebook](../lab-notebook-template.md)
+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`