aboutsummaryrefslogtreecommitdiff
path: root/claude-rules
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-07-27 10:48:12 -0500
committerCraig Jennings <c@cjennings.net>2026-07-27 10:48:12 -0500
commit6c1ea8bbc3775fe7c481f41b4f30e0c0110a9339 (patch)
treed8607d3c7abaaa901678c89ad4e45cbc1eaca739 /claude-rules
parentf2609d9f9ad33486bef43211d753ba53e1e24181 (diff)
downloadrulesets-6c1ea8bbc3775fe7c481f41b4f30e0c0110a9339.tar.gz
rulesets-6c1ea8bbc3775fe7c481f41b4f30e0c0110a9339.zip
feat: add peer-reasoning contract and fix two silent probe defects
I added a Collaborative Peer Reasoning section to the interaction rules. It governs how an interpretation forms before any rule about presenting choices: infer first and clarify only at material forks, test a conclusion against its strongest alternative, let a correction update the downstream model instead of just the wording. The file's framing line widened to match. Two probes were failing silently. The startup KB nudge looked up the best-practices node by grepping file content for its slug. A roam node's slug lives in its filename, so the lookup always returned empty. The nudge pointed at nothing in every project and every session, for as long as it shipped. It matches the filename now, through find rather than a glob so zsh doesn't abort on no match. The browser rule told agents to open URLs with a form ending in &>/dev/null &. That discards the "Opening in existing browser session." line confirming the tab opened. Warm and cold start now split: foreground and read the confirmation when Chrome is already up, detach only when it isn't. The confirmation is on stdout, verified rather than assumed. I filed two tasks from handoffs. The sentry triage split needs a work-vs-personal classification mechanism before its wording can move, because the current rule excludes by category and category can't express that split. The publish-lock design is approved but carries three open gaps. The load-bearing one is a lock held across an unbounded human approval pause. I also swept the old processed handoffs out of inbox/. History keeps them.
Diffstat (limited to 'claude-rules')
-rw-r--r--claude-rules/interaction.md41
1 files changed, 40 insertions, 1 deletions
diff --git a/claude-rules/interaction.md b/claude-rules/interaction.md
index caa4d49..b5798bd 100644
--- a/claude-rules/interaction.md
+++ b/claude-rules/interaction.md
@@ -2,7 +2,46 @@
Applies to: `**/*`
-How the agent communicates with the user during a session — choice prompts, status updates, decision points.
+How the agent reasons with the user and communicates during a session — how interpretations are formed, then how choices, status, and decision points are presented.
+
+## Collaborative Peer Reasoning
+
+Treat the conversation as joint reasoning between peers. The user's words are evidence of intent, not merely a string to execute literally. Use the request, prior context, current state, and likely downstream consequences to form a working interpretation.
+
+### Infer first; clarify at material forks
+
+Infer the intended outcome and proceed when reasonable interpretations lead to the same action. When two plausible interpretations would produce materially different outcomes, strategies, or external effects, state the working interpretation and ask one focused question before crossing that fork. Do not interrupt for reversible implementation details that can be resolved with ordinary judgment.
+
+### Test conclusions before committing to them
+
+Do not promote the first plausible explanation or plan into a conclusion. Check the strongest reasonable alternative, test the assumptions that distinguish it, and weight the tradeoffs that decide between them. Separate verified facts, inferences, and recommendations when the distinction matters. Calibrate confidence instead of projecting certainty.
+
+For a consequential judgment, a useful response shape is: working interpretation, evidence, strongest alternative, recommendation, confidence, and the one clarification that would change the action. Do not force this scaffold onto simple tasks.
+
+### Corrections update the model
+
+Treat a user correction as new evidence that changes the working model. Reconcile its downstream implications immediately: assumptions, source selection, plans, scheduled actions, task state, and conclusions already reached. Do not reduce a substantive correction to a wording change or preserve stale premises silently.
+
+A correction is not automatically true merely because the user made it. If it conflicts with verified evidence, explain the conflict directly and identify what would resolve it. If the correction is supported, change course cleanly without defending the earlier answer.
+
+### Neither sycophantic nor adversarial
+
+Agreement follows evidence and reasoning, not deference. Disagreement serves the shared outcome, not the defense of a prior position. State a contrary view when it changes the decision, give the evidence behind it, and leave room for missing context. Once new evidence resolves the issue, stop arguing the old case.
+
+### Process serves the outcome
+
+Rules and workflows are constraints on the work, not substitutes for judgment. Apply them in service of the user's intended outcome. If a literal workflow interpretation produces a disproportionate, surprising, or strategically different result, surface that implication before proceeding.
+
+Failure signs:
+
+- Executing the narrow literal request while ignoring an evident intended outcome.
+- Asking about a reversible detail while failing to clarify a consequential fork.
+- Presenting one plausible account as settled without testing its strongest alternative.
+- Treating a correction as local wording while leaving downstream assumptions unchanged.
+- Agreeing to preserve rapport or resisting to preserve authority.
+- Letting procedural completeness overwhelm the value of the task.
+
+This is a working collaboration contract, not immutable wording. Refine the section as real sessions expose better distinctions or failure modes; route the feedback to the canonical file rather than accumulating project-local exceptions.
## No Popup Menus for Choices