From 3eee0b062dd9cf71af56fb0e7f1aa49d292be54f Mon Sep 17 00:00:00 2001 From: Vadim Zolotokrylin <1125014+zolotokrylin@users.noreply.github.com> Date: Tue, 15 Sep 2026 23:00:26 +0800 Subject: [PATCH 1/3] docs(rules): write messages a reader can check and act on --- docs/rules/DEV-230.md | 10 ++++++++-- docs/rules/DEV-260.md | 40 ++++++++++++++++++++++++++++++++++++++++ docs/rules/README.md | 1 + 3 files changed, 49 insertions(+), 2 deletions(-) create mode 100644 docs/rules/DEV-260.md diff --git a/docs/rules/DEV-230.md b/docs/rules/DEV-230.md index 5bebb30..a0ad97e 100644 --- a/docs/rules/DEV-230.md +++ b/docs/rules/DEV-230.md @@ -25,17 +25,23 @@ applied to every issue, PR description, comment, review reply and chat message. own hesitation or worry. 1. Cut openers that announce a point instead of making it, such as "Worth noting", "Just to add" or "Good question". -1. End with what you need, from whom. When nothing is needed, stop. +1. End with what you need, from whom. When nothing is needed, stop. A hedged + closer such as "Feel free to ask" or "Let me know if you have any questions" + asks for nothing, so cut it. +1. Join clauses with a comma, colon, period or parentheses, which say how the + parts relate. An em dash does not; an en dash belongs only in a number range. ```md Good: Blocked on the MAS field list. @owner, which company fields does MAS receive? I need it to finish the edit gate. Bad: Hi @owner, hope you're well! Great work on the spec so far. I've been looking into the edit gate and I'm a bit worried about the fields... + Let me know if you have any questions. ``` ### Acceptance Criteria - [ ] The first line carries the decision, answer, status or question -- [ ] The message holds no greeting, flattery or personal aside +- [ ] The message holds no greeting, flattery, personal aside or hedged closer - [ ] A message that needs something from someone names what and from whom +- [ ] No em dash appears in prose, and an en dash only inside a number range diff --git a/docs/rules/DEV-260.md b/docs/rules/DEV-260.md new file mode 100644 index 0000000..1aacd4e --- /dev/null +++ b/docs/rules/DEV-260.md @@ -0,0 +1,40 @@ +--- +id: DEV-260 +title: "Define Every Term the Reader Has Not Seen" +status: "active" +enforcement: "manual" +severity: "warning" +depends_on: ["DEV-230"] +--- + +## Problem + +A message built on words the reader has not seen defined, such as "middle +ground" or "eng-month", makes them guess, and two readers guess differently. + +## Solution + +A word earns its place only if it survives the question "what does that mean +here?". The writer knows what they meant; the reader only has the page. + +1. Replace an abstract verb such as "align", "streamline", "formalise" or + "leverage" with the action it stands for. +1. Replace a catch-all such as "everything else" or "the rest" with the list it + covers. +1. Define a term the first time you use it, unless the thread or a linked doc + already defines it. Otherwise replace it with the concrete thing. +1. Refer to an earlier position by stating it or linking it, not by a shorthand + only you hold. + +```md +Good: A month with under 40 logged hours bills by the days worked, not as a + full month. +Bad: This keeps partner protection on light months (no "16h = full month"). +``` + +### Acceptance Criteria + +- [ ] Every term is defined in the message, the thread, or a linked doc +- [ ] No abstract verb stands in for an action that can be named +- [ ] No catch-all stands in for a list that can be given +- [ ] Every earlier position referred to is stated or linked diff --git a/docs/rules/README.md b/docs/rules/README.md index 736b060..050c008 100644 --- a/docs/rules/README.md +++ b/docs/rules/README.md @@ -67,6 +67,7 @@ Where discussion goes, how a message is written, and how work is referenced. - [DEV-240](./DEV-240.md): mention someone only to ask them to act - [DEV-245](./DEV-245.md): post a daily update on the work you own - [DEV-250](./DEV-250.md): settle it async before calling a meeting +- [DEV-260](./DEV-260.md): define every term the reader has not seen ### 3. PR requirements From 0463b215a302d4295fe911ffd1763e9cd9dfe304 Mon Sep 17 00:00:00 2001 From: Vadim <1125014+zolotokrylin@users.noreply.github.com> Date: Mon, 21 Sep 2026 19:07:32 +0800 Subject: [PATCH 2/3] Update docs/rules/DEV-230.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Vadim <1125014+zolotokrylin@users.noreply.github.com> --- docs/rules/DEV-230.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules/DEV-230.md b/docs/rules/DEV-230.md index a0ad97e..493f600 100644 --- a/docs/rules/DEV-230.md +++ b/docs/rules/DEV-230.md @@ -29,7 +29,7 @@ applied to every issue, PR description, comment, review reply and chat message. closer such as "Feel free to ask" or "Let me know if you have any questions" asks for nothing, so cut it. 1. Join clauses with a comma, colon, period or parentheses, which say how the - parts relate. An em dash does not; an en dash belongs only in a number range. + parts relate. An em dash does not show how the parts relate. Use an en dash only in a number range. ```md Good: Blocked on the MAS field list. @owner, which company fields does MAS From fd31b5132a6cdfffa1764f7d04f0b58673970c74 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Mon, 21 Sep 2026 11:15:13 +0000 Subject: [PATCH 3/3] docs(rules): require definitions only for unfamiliar terms --- docs/rules/DEV-260.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/rules/DEV-260.md b/docs/rules/DEV-260.md index 1aacd4e..80c7533 100644 --- a/docs/rules/DEV-260.md +++ b/docs/rules/DEV-260.md @@ -34,7 +34,8 @@ Bad: This keeps partner protection on light months (no "16h = full month"). ### Acceptance Criteria -- [ ] Every term is defined in the message, the thread, or a linked doc +- [ ] Every unfamiliar term is defined in the message, the thread, or a linked + doc - [ ] No abstract verb stands in for an action that can be named - [ ] No catch-all stands in for a list that can be given - [ ] Every earlier position referred to is stated or linked