From a5ce6046abd27832c0f36c56c8c63512716329b1 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Mon, 22 Dec 2025 12:33:17 -0800
Subject: [PATCH] docs: Update witness template to use gt nudge/peek
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces raw tmux send-keys with gt nudge in spawn processing.
Adds Session Communication section to key commands reference.
Adds warning against raw tmux send-keys.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 internal/templates/roles/witness.md.tmpl | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/internal/templates/roles/witness.md.tmpl b/internal/templates/roles/witness.md.tmpl
index 79604635..263c8540 100644
--- a/internal/templates/roles/witness.md.tmpl
+++ b/internal/templates/roles/witness.md.tmpl
@@ -128,13 +128,16 @@ Look for signs Claude is ready:
 ### Step 3: Nudge to Start Working
 Once Claude appears ready, send the work instruction:
 ```bash
-tmux send-keys -t gt-{{ .RigName }}-<polecat> "Check your inbox with 'gt mail inbox' and begin working on your assigned issue." Enter
+gt nudge {{ .RigName }}/<polecat> "Check your inbox with 'gt mail inbox' and begin working on your assigned issue."
 ```
 
+⚠️ **Always use `gt nudge`** - never raw `tmux send-keys`. The nudge command
+handles the timing correctly; raw send-keys drops the Enter key.
+
 ### Step 4: Verify Work Started
 After nudging, check the session again:
 ```bash
-gt session capture {{ .RigName }}/<polecat> -n 30
+gt peek {{ .RigName }}/<polecat> 30
 ```
 
 Look for signs the polecat is working:
@@ -284,7 +287,13 @@ gt handoff --cycle
 - `gt session stop {{ .RigName }}/<name>` - Stop a session
 - `gt session stop {{ .RigName }}/<name> --force` - Force stop
 - `gt polecat remove {{ .RigName }}/<name>` - Remove polecat worktree
-- `gt session capture {{ .RigName }}/<name> -n 50` - Get recent output
+
+### Session Communication
+- `gt nudge {{ .RigName }}/<name> "message"` - Send message reliably
+- `gt peek {{ .RigName }}/<name>` - View recent session output
+- `gt peek {{ .RigName }}/<name> 50` - View last 50 lines
+
+⚠️ **Never use raw `tmux send-keys`** - it drops the Enter key. Always use `gt nudge`.
 
 ### Communication
 - `gt mail inbox` - Check your messages