diff options
| author | Craig Jennings <c@cjennings.net> | 2026-07-11 01:56:07 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-07-11 01:56:07 -0500 |
| commit | 99bd213002f2bd24192d15ff9ae69a0379b2f5be (patch) | |
| tree | 27ae8c0fa517ae65b8e68a006cb43c862bad55db /voice | |
| parent | 81ca16f9b516112ae17727a09b8b36538f9db21d (diff) | |
| download | rulesets-99bd213002f2bd24192d15ff9ae69a0379b2f5be.tar.gz rulesets-99bd213002f2bd24192d15ff9ae69a0379b2f5be.zip | |
docs(review): drop praise from approve summaries, print inline text at the gate
An approve summary now carries no praise, not even a bare positive like "Clean." or "Solid fix." Lead with the substantive pointer (the design note pinned inline) and close with the verdict. This removes the bare-positive carve-out from review-code's Posted Summary Voice and from voice pattern #40, and updates the worked examples.
The review gate must also print the full prose of every inline comment, never a description of it. The exact words post under my name, so I have to see them before I approve. Made explicit in review-code Phase 5 and commits.md Shape 1.
From a DeepSat review session where I approved "One design note inline, not a blocker. Approving."
Diffstat (limited to 'voice')
| -rw-r--r-- | voice/SKILL.md | 6 | ||||
| -rw-r--r-- | voice/references/voice-profile.org | 15 |
2 files changed, 13 insertions, 8 deletions
diff --git a/voice/SKILL.md b/voice/SKILL.md index 4690b97..19eb38b 100644 --- a/voice/SKILL.md +++ b/voice/SKILL.md @@ -44,9 +44,9 @@ Terse is a budget, not an adjective. Each publish-artifact type has a target sha |----------|--------| | Commit body | Skip entirely when the subject line carries the change. Otherwise short paragraphs: the constraint, bug, or tradeoff. No play-by-play. | | PR description | Problem / Fix / Why / Testing, each section tight. | -| PR review summary | One long sentence or a few short ones. Verdict closes it. Verdict formulas ("Approving.", "Requesting changes.") are valid sentences here. | +| PR review summary | Lead with the substantive pointer, verdict closes it. No praise, not even a bare positive (#40). Verdict formulas ("Approving.", "Requesting changes.") are valid sentences here. | | Inline pin (finding) | ~4 sentences in stems shape (#42): where the bug is, the fix, why it's better. | -| Praise comment | One sentence naming what's good. Nothing else (#40). | +| Praise comment (inline only) | One sentence naming what's good. Nothing else (#40). Never in the summary body. | | Follow-up approval after prior feedback was addressed | Exactly "Approved." | ## Your Task @@ -348,7 +348,7 @@ See `voice/references/voice-profile.org` §39 for problem, basis, examples, and ### 40. Praise vs Correction Asymmetry [personal] -**Rule.** Praise on a PR review is short and unjustified (the author knows why their good change is good). Correction always explains the why, gently and briefly, the way a mentor would. Never as a verdict from on high. **Verification narration is the same defect as justified praise:** "I traced X and it's safe because..." pads the compliment with the reviewer's homework. Tracing the code is the reviewer's job, not content for the comment — if verification found a problem, the problem gets the words; if it found nothing, it gets zero words. +**Rule.** Praise on a PR review is short and unjustified (the author knows why their good change is good). Correction always explains the why, gently and briefly, the way a mentor would. Never as a verdict from on high. **Verification narration is the same defect as justified praise:** "I traced X and it's safe because..." pads the compliment with the reviewer's homework. Tracing the code is the reviewer's job, not content for the comment — if verification found a problem, the problem gets the words; if it found nothing, it gets zero words. **An approve summary carries no praise at all** — not even a bare positive ("Clean.", "Solid fix."). Lead the summary with the substantive pointer (the design note pinned inline) and close with the verdict: "One design note inline, not a blocker. Approving." An approve with nothing to flag is just "Approving." Short unjustified praise survives only as an inline pin on the line it refers to, never in the summary body. See `voice/references/voice-profile.org` §40 for problem, basis, examples, and history. diff --git a/voice/references/voice-profile.org b/voice/references/voice-profile.org index 088f0eb..765d513 100644 --- a/voice/references/voice-profile.org +++ b/voice/references/voice-profile.org @@ -1308,9 +1308,9 @@ Local absolute paths (=/home/<user>/...=, =/Users/<user>/...=), private repo nam Personal mode only. General and prose skip because the rule assumes a PR review context. *** Rule -Praise on a PR review is short and unjustified (the author knows why their good change is good). Correction always explains the why, gently and briefly, the way a mentor would, never as a verdict from on high. Keep it brief either way. +Praise on a PR review is short and unjustified (the author knows why their good change is good), and it survives only as an inline pin on the line it refers to. Correction always explains the why, gently and briefly, the way a mentor would, never as a verdict from on high. Keep it brief either way. -On an approve summary: praise plus verdict, nothing else. Cut any clause that describes or justifies the change. "Clean fix on the stacking bug, the tri-state is the right level to solve it at, and the tests cover the edges. Approving." becomes "Clean fix on the stacking bug. Approving." If a clause references what the code does or why it works, delete it. +On an approve summary: no praise at all, not even a bare positive ("Clean.", "Solid fix."). Lead with the substantive pointer — the design note pinned inline — and close with the verdict; an approve with nothing to flag is just "Approving." "Clean fix on the stacking bug, the tri-state is the right level to solve it at, and the tests cover the edges. Approving." becomes "One design note inline, not a blocker. Approving." (or just "Approving." with nothing to flag). Cut any clause that describes, justifies, or compliments the change — if a clause references what the code does, why it works, or how good it is, delete it. On a finding or change-request: always give the why, gently and briefly. Not "Move this to a helper." but "I'd pull this into one helper — three copies of the same rule means the next change has to touch all three, and missing one brings the bug back." @@ -1329,9 +1329,11 @@ Nice clean migration, the provider mocks and the Normal/Boundary/Error cases are *** After #+begin_example -Clean migration. Approving. One note inline: I'd rename `x` to `provider` — it reads as a generic placeholder and the next person won't know it's the resolved provider without tracing it. +One naming note inline, not a blocker. Approving. #+end_example +The rename rationale (`x` reads as a generic placeholder; the next person won't know it's the resolved provider without tracing it) lives in the inline pin, not the summary — the summary points, the pin teaches. + *** Before (verification narration) #+begin_example All three fixes look right. I traced useMapActions and the unmount cleanup is safe because the hook returns a memoized object, and the provider wraps the whole app so neither call site lands on the no-op path. @@ -1339,16 +1341,19 @@ All three fixes look right. I traced useMapActions and the unmount cleanup is sa *** After #+begin_example -All three fixes are clean and well-aimed. +Approving. #+end_example +Nothing to flag, so the summary is the bare verdict. The old "All three fixes are clean and well-aimed" is itself praise, and praise is now cut from the approve summary entirely. + *** Detection -In a PR review summary or comment: a praise clause that explains why the good thing is good, a praise clause followed by the verification work that supports it, or a finding or change-request that states what to fix without saying why. +In a PR review summary or comment: any praise on an approve summary (including a bare positive), a praise clause that explains why the good thing is good, a praise clause followed by the verification work that supports it, or a finding or change-request that states what to fix without saying why. *** History - Original SKILL.md entry: praise-versus-correction asymmetry for PR review. - 2026-05-29: migrated to this file as the canonical home per the pairing rule. - 2026-06-10: verification-narration variant added after the third recurrence — a review draft praised a fix and then narrated the verification supporting the praise (the #236 draft). Added to the SKILL.md rule line and the high-recurrence attestation set. Craig's call, from the work-project session. +- 2026-07-11: bare-positive carve-out removed. An approve summary now carries no praise at all, not even "Clean." / "Solid fix." — lead with the substantive pointer, close with the verdict. Craig's ruling from a DeepSat review session (approved "One design note inline, not a blocker. Approving."). Same change applied to review-code's Posted Summary Voice and commits.md Shape 1. ** §41 No Emphasis Formatting |
