From f32f0fa8a38aff31ccdad805701539dcdd0cc2e1 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Wed, 19 Aug 2026 13:57:55 +0200 Subject: [PATCH] docs(references): point no-editorializing at its canonical copy The rule lived in five repos as three different texts. This copy was a strict prefix of the canonical one in git-workflow-skill -- `diff` reports additions only, no divergence -- so it was the same rule minus the line-wrapping section that copy has been gaining since. matrix-skill and netresearch-branding already carry the pointer; this brings the convention to the last two public repos holding the full copy (A23, netresearch/skill-repo-skill#157). german-technical-writing keeps its own file: that one is not a copy, its scope paragraph deliberately limits the rule to the German artifacts that skill governs. Nothing is lost when offline: SKILL.md states the rule in a sentence at the point of use, and the reference is the long form. Assisted-by: claude-code:claude-opus-5 Agent-Session: https://claude.ai/code/session_01CT41JfSGYEJJaBUZxg7xzu Agent-Host: 32116e Signed-off-by: Sebastian Mendel --- .../references/no-editorializing.md | 40 +------------------ 1 file changed, 1 insertion(+), 39 deletions(-) diff --git a/skills/github-project/references/no-editorializing.md b/skills/github-project/references/no-editorializing.md index f6cf3e0..7793a06 100644 --- a/skills/github-project/references/no-editorializing.md +++ b/skills/github-project/references/no-editorializing.md @@ -1,41 +1,3 @@ # No editorializing — inform, don't sell (tone, not wordlist) -Applies to every written artifact: commit messages, PR/MR descriptions, review -comments, issue/ticket text, chat — and code comments, docstrings, -documentation, README and changelog files. - -Editorializing is a matter of **tone and intent, not specific words** — no -banned-word list catches it, and the same word can be fine or not depending on -whether it carries a fact. The failure is writing about *how good, clean, or -careful the work is* instead of *what it does*. The reader has the diff and the -artifact; anything that only flatters the work or reassures them adds nothing, -and to a reviewer it reads as salesmanship — it provokes a counter-reaction -before they reach the substance. - -Apply three tests before a sentence stays: - -1. **Deletion** — remove the phrase. Did the reader lose a fact? If not, cut it. -2. **Subject** — is the sentence about the change, or about *you / your work* - (its quality, your diligence)? The latter goes. -3. **Voice** — would a terse maintainer write this, or does it read like a - cover letter? - -Two recurring failure modes: - -- **Announcing the expected.** Passing tests, clean linters, "documented", "no - regressions", "works as expected" are the baseline — do not narrate them. - State a check's status only to flag an *exception* (something knowingly - failing or skipped). In a test/verification list, say what was *added or - covered*, not that it is green. - -- **Self-praise and reassurance.** Grading your own output ("clean", "robust", - "elegant", "foolproof", "tidy", "genuinely new", "production-ready"); framings - that reassure ("the honest breaking change", "deliberately scoped, not - hidden", "where it belongs"); and the diligence humble-brag ("I carefully…", - "I made sure to…", "thoroughly tested"). These describe the author, not the - change. Show the fact; drop the framing. (The words are only symptoms — judge - by the three tests above, not by the word.) - -Use plain labels, not graded ones: "Breaking change", "Tests", "Limitations" — -not "Tests (all green)" or "Breaking change (honest)". If a limitation's cause -matters, it is already stated in the item. +Canonical copy: [no-editorializing.md](https://github.com/netresearch/git-workflow-skill/blob/main/skills/git-workflow/references/no-editorializing.md). See there.