This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 6ed2e0c79156a0a8a226b4219d45df2bd0a5576b Author: Stephen Mallette <[email protected]> AuthorDate: Fri Aug 21 12:52:41 2026 -0400 Require asking why an alternative was rejected An inferred reason is indistinguishable from a recorded one, so a guess reads as fact later. The agent now asks when it is reconstructing rather than recalling, and the redirect nudge says so at the moment a rejection happens. Assisted-by: Claude Code:claude-opus-5 --- .beads/PRIME.md | 8 ++++++++ bin/beads-agent-hook.sh | 4 +++- docs/src/dev/developer/for-committers.asciidoc | 7 +++++++ 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/.beads/PRIME.md b/.beads/PRIME.md index b445e4e32e..633894e06a 100644 --- a/.beads/PRIME.md +++ b/.beads/PRIME.md @@ -76,6 +76,14 @@ PRIME.md describes"), never a judgment ("rejected as worse"). A mechanism can be later: when the problem it names no longer applies, the option is worth reconsidering. A judgment cannot, so the option stays dead by default. The chosen decision needs a reason too. +**If you cannot say why the operator rejected it, ask before writing the bead.** An inferred +reason is indistinguishable from a recorded one, so a guess does not read as a guess three years +later — it reads as fact and gets trusted. "The operator preferred the other one" is the verdict +again, not a reason. Ask what the chosen option buys and what the rejected one would have cost, +and write that answer. Ask while the conversation is live: section 5 forbids editing a design in +place, so a reason invented now is permanent. Doubt is the trigger — if you are reconstructing +rather than recalling, you are guessing. + **Cite code as `file[sha]`** — `GryoPool.java[bece4a34c7]`, with enough path to be unambiguous (`pom.xml` is 36 different files). No line numbers, no symbol names: both drift, and the sentence around the citation already says what it points at. The sha has to be reachable from a diff --git a/bin/beads-agent-hook.sh b/bin/beads-agent-hook.sh index 0bb4dd1191..4519f06ec8 100755 --- a/bin/beads-agent-hook.sh +++ b/bin/beads-agent-hook.sh @@ -149,7 +149,9 @@ was underway or where it stopped." if printf '%s' "$prompt" | tr '[:upper:]' '[:lower:]' | grep -Eq "$REDIRECT_RE"; then text="That prompt reads as a redirect. If an alternative was just rejected, create the decision bead and its rejected sibling now, while the reasoning is exact — operator -redirects are the highest-signal capture trigger there is." +redirects are the highest-signal capture trigger there is. If the reason was not stated +outright, ask for it rather than inferring one. An inferred reason is indistinguishable +from a recorded one later, which makes guessing worse than asking." fi ;; diff --git a/docs/src/dev/developer/for-committers.asciidoc b/docs/src/dev/developer/for-committers.asciidoc index 9713b86684..a311f2a886 100644 --- a/docs/src/dev/developer/for-committers.asciidoc +++ b/docs/src/dev/developer/for-committers.asciidoc @@ -174,6 +174,13 @@ followed, since both are stored as decisions. The value of the pair lies in the than in the verdict. An objection expressed as a concrete mechanism can be tested again later, and an alternative whose objection no longer holds is precisely the one worth reopening. +Because the reason carries that weight, an agent is instructed to ask for it rather than infer +it. A reason it reconstructed reads exactly like one it was told, and nothing downstream can +separate the two, so a plausible guess is more damaging than an absent bead. Answering that +question with the mechanism rather than the preference is what makes the record worth keeping, +and the answer cannot be corrected quietly later, since an agent is forbidden from editing +reasoning already written. + [[beads-structure]] === The Shape of a Plan
