diff --git a/CLAUDE.md b/CLAUDE.md
index e98de60c5..018623bd0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -132,6 +132,12 @@ tea issue list --login schweitz --repo jpmschweitzer/settled-reach --state open
 Key rules:
 - **All flags must be explicit** — omitting `--login` or `--repo` triggers interactive prompts that crash in Claude Code (no TTY)
 - **Use `--output simple`** for machine-readable output (no table borders)
+- **`tea comment` hangs with inline heredocs and multi-line strings.** Always write the comment body to a temp file first, then pass it via `$(cat)`:
+  ```bash
+  # Step 1: Write content to .tmp/ (gitignored) using the Write tool
+  # Step 2: Post via cat
+  tea comment --login schweitz --repo jpmschweitzer/settled-reach <NUMBER> "$(cat .tmp/review-branch.md)"
+  ```
 - **`tea pr reject` does not work on your own PRs** — use `tea comment` instead
 - **Never delete protected branches:** `main`, `maintenance`, `server`, `client`, `copy`, `audio`, `visual`, `ci` are protected on Gitea. Do not use `tea pr clean`, `git push --delete`, or `git branch -D` on these branches.