Merge pull request #205 from netresearch/retro/probe-and-pr-body-rules

docs: a probe command is read-only; write the PR body in its own call

Author: CybotTM

skills/git-workflow/references/advanced-git.md

@@ -185,6 +185,36 @@ git merge --no-ff cherry-pick-fixes
 
 ## Stashing
 
+### A probe command is read-only
+
+Comparing two revisions, checking what a script used to do, reproducing a bug
+against an older build — that work is exploratory, and it must not move the
+working tree. Never put `git stash`, `git reset`, `git checkout --` or
+`git restore` inside a command whose purpose is to find something out.
+
+The failure is silent, which is what makes it worth a rule. A probe that
+stashes uncommitted work looks exactly like a probe that found nothing: the
+command prints its output, the tree is quietly a different tree, and the next
+edit lands on top of a state nobody chose. Recovery is `git stash pop`, but
+only if you notice.
+
+Extract the other revision instead of moving to it:
+
+```bash
+# ✅ Compare against another revision without touching the tree
+git show origin/main:path/to/script.sh > /tmp/old-script.sh
+bash /tmp/old-script.sh --check
+
+# ✅ A whole old tree, still without moving
+git worktree add /tmp/old-tree origin/main
+
+# ❌ Wrong — mutates the working tree in the middle of an inspection
+old=$(cd src && git stash -q; ./script.sh; true)
+```
+
+If a probe genuinely needs a clean tree, commit first (see the sibling rules on
+selective revert and selective commit) — do not stash your way there.
+
 ### Basic Stash Operations
 
 ```bash

skills/git-workflow/references/pull-request-workflow.md

@@ -365,6 +365,38 @@ minutes apart in writing — which is exactly why the disagreement is worth
 catching. Two figures for one quantity means at least one is answering a
 question you are no longer asking.
 
+### Write the body in its own tool call, after the push
+
+A body that cites a commit can only be written once that commit is on the
+remote, and the hash belongs in it by lookup — `git rev-parse --short HEAD` or
+`git log -1 --format=%h` — never typed from memory. A reader who follows a
+wrong hash finds nothing, and the claim it supported becomes unverifiable.
+
+That ordering has a second, sharper reason: **a denied command loses every side
+effect it contained.** Bundling the push, a heredoc that writes the body file,
+and `gh pr edit --body-file` into one shell invocation means a gate that rejects
+any part of it rejects all of it — and the parts that already ran do not roll
+back. Observed: the push landed, the heredoc never ran because the same call was
+rejected for naming a not-yet-pushed hash, and the following command failed with
+`no such file or directory` — a confusing error two steps downstream of the
+actual refusal.
+
+```bash
+# ✅ Three calls, each with one job
+git push
+git rev-parse --short HEAD          # take the hash from here
+# …write body.md…
+gh pr edit 123 --body-file body.md
+
+# ❌ One call: the gate rejects the whole thing, the push already happened,
+#    and the body file that the next step needs was never created
+git push && cat > body.md <<'EOF' … EOF && gh pr edit 123 --body-file body.md
+```
+
+The general rule: never bundle a file write with a push or an API call. Keep
+state-changing steps separable, so a refusal costs you the step and not the
+scaffolding around it.
+
 ### When you already have the fix, lead with it
 
 Issue templates order evidence before solution — they are written for reports