docs: add why-shorthand and how-to-respond guides

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 22:57:12 -04:00
parent 34c9653f46
commit e236a2efdb
2 changed files with 122 additions and 0 deletions
@@ -0,0 +1,71 @@
+# How to Respond in Shorthand (For Claude)
+
+## The Rule
+
+Mirror the user's density. Shorthand in → shorthand out.
+
+## Response Patterns
+
+### Status Updates
+```
+# verbose:
+"I've successfully connected to pve173 and checked the ZFS pool status.
+Everything looks healthy with no degraded drives."
+
+# shorthand:
+pve173 → tank healthy, 0 degraded
+```
+
+### Results with Data
+```
+# verbose:
+"I found 3 containers that are currently stopped: CT 105 (ollama),
+CT 629 (openclaw), and CT 118 (test). Would you like me to start any of them?"
+
+# shorthand:
+stopped CTs: 105 (ollama), 629 (openclaw), 118 (test)
+start any?
+```
+
+### Errors / Blockers
+```
+# verbose:
+"I tried to SSH into pve197 but the connection was refused.
+This might be because the SSH service isn't running or there's
+a firewall rule blocking the connection."
+
+# shorthand:
+pve197 SSH refused — service down or firewall?
+```
+
+### Multi-step Progress
+```
+# verbose:
+"First I'll read the Caddyfile, then add the new entry, then
+reload Caddy. Let me start by reading the current configuration."
+
+# shorthand:
+plan: read caddy → add entry → reload
+reading...
+```
+
+### Confirmations
+```
+# verbose:
+"Done! I've added the wiki.sethpc.xyz reverse proxy entry pointing
+to 192.168.0.160:3000 and reloaded Caddy. The site should be
+accessible now."
+
+# shorthand:
+done. wiki.sethpc.xyz → .160:3000 added, caddy reloaded.
+```
+
+## Rules
+
+1. **Match density** — user terse → you terse. User verbose → you verbose.
+2. **Use same operators** — if user writes `→`, respond with `→`
+3. **Use known aliases** — `pve173` not "the PowerEdge node"
+4. **Lead with result** — answer first, context after (if needed)
+5. **Skip narration** — no "Let me...", "I'll now...", "First I'll..."
+6. **Questions stay short** — `start any?` not "Would you like me to start any of them?"
+7. **Errors = signal** — state what failed + likely cause, nothing else