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

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

how-to-respond.md

@@ -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

why-shorthand.md

@@ -0,0 +1,51 @@
+# Why Use Shorthand with Claude?
+
+## The Problem
+
+Every token costs money and time. A typical conversational prompt uses 2-3x more tokens than necessary — articles, filler words, politeness markers, and redundant context that Claude already knows.
+
+## The Math
+
+| Style | Tokens/msg | 100 msgs/day | Monthly cost (Opus) |
+|-------|-----------|--------------|-------------------|
+| Conversational | ~80 | 8,000 | baseline |
+| Shorthand | ~25 | 2,500 | ~70% less |
+
+Output tokens cost 5x input on most Claude models — but shorter, denser prompts also produce shorter, denser responses. The savings compound.
+
+## What You're NOT Losing
+
+- **Accuracy** — Claude parses structured input *better* than prose. Ambiguity drops.
+- **Nuance** — Operators like `?` `:` `!` express conditionals and negation precisely.
+- **Context** — CLAUDE.md aliases (`pve173`, `tank`, `caddy`) carry full meaning in 1 token.
+
+## What You ARE Gaining
+
+- **Speed** — Less typing, faster responses, shorter round-trips
+- **Clarity** — Structured specs force you to think about what you actually want
+- **Cost** — 50-70% token reduction on input, cascading savings on output
+- **Signal density** — Every token carries meaning, nothing wasted
+
+## When to Use Full Prose
+
+- Teaching Claude something new (novel context it can't infer)
+- Complex reasoning where relationships between ideas matter
+- When you'd write prose to a human colleague too
+
+## The Mental Model
+
+Think of it like SQL vs. English:
+
+```
+-- English:
+"Could you please look at all the users in the database who signed
+up after January 1st and haven't logged in for 30 days, and give
+me their email addresses?"
+
+-- SQL:
+SELECT email FROM users WHERE created > '2025-01-01' AND last_login < NOW() - 30d
+```
+
+Both say the same thing. One is 40 tokens. The other is 15. Claude understands both equally well.
+
+Shorthand is your "SQL for Claude."