From eea6f19dfb6d049153904a2caeeaa2f3a69a1876 Mon Sep 17 00:00:00 2001 From: Edbert Chan Date: Fri, 11 Sep 2026 18:07:41 -0700 Subject: [PATCH] diu word lists: five kinds of wording to avoid in replies Five phrase lists under engine/hooks/diu-stop/phrases/ name the kinds of wording that left the user asking what a reply meant: words the assistant made up, raw code or setting names, internal tool names, tech jargon and abbreviations, and status words. Data and one test only; nothing reads them yet. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Gnua5cuAAF1ey1b7zRqJCC Change-Id: I4860c82b5b8a8a6b84a9397e289c7023fd5d7730 --- .../phrases/plain-words-code-names.json | 17 +++++ .../phrases/plain-words-internal-names.json | 18 +++++ .../phrases/plain-words-made-up-labels.json | 18 +++++ .../phrases/plain-words-status-words.json | 18 +++++ .../phrases/plain-words-tech-jargon.json | 18 +++++ .../hooks/diu-stop/tests/test_plain_words.py | 75 +++++++++++++++++++ 6 files changed, 164 insertions(+) create mode 100644 engine/hooks/diu-stop/phrases/plain-words-code-names.json create mode 100644 engine/hooks/diu-stop/phrases/plain-words-internal-names.json create mode 100644 engine/hooks/diu-stop/phrases/plain-words-made-up-labels.json create mode 100644 engine/hooks/diu-stop/phrases/plain-words-status-words.json create mode 100644 engine/hooks/diu-stop/phrases/plain-words-tech-jargon.json create mode 100644 engine/hooks/diu-stop/tests/test_plain_words.py diff --git a/engine/hooks/diu-stop/phrases/plain-words-code-names.json b/engine/hooks/diu-stop/phrases/plain-words-code-names.json new file mode 100644 index 0000000..85b9f69 --- /dev/null +++ b/engine/hooks/diu-stop/phrases/plain-words-code-names.json @@ -0,0 +1,17 @@ +{ + "checker": "plain-words-code-names", + "meaning": "The reply puts a raw code, config, or function name in front of the user as if it were a word, without saying in everyday words what it does.", + "reads": "exchange", + "match": [ + "Set disable-model-invocation: true on the skill.", + "It flips desiredEnabled: true.", + "materialize_revision now calls realpath.", + "The check reads EXIT_CODES and PULL_REF_RE." + ], + "not_match": [ + "The skill is hidden from the automatic skill list, so only a typed command can start it.", + "The worker is switched on.", + "The replay tool now follows folder shortcuts before comparing paths (backtest_detector.py:102)." + ], + "on_hit": "plain-words: the last reply named code or settings without saying what they do in everyday words." +} diff --git a/engine/hooks/diu-stop/phrases/plain-words-internal-names.json b/engine/hooks/diu-stop/phrases/plain-words-internal-names.json new file mode 100644 index 0000000..2f0201c --- /dev/null +++ b/engine/hooks/diu-stop/phrases/plain-words-internal-names.json @@ -0,0 +1,18 @@ +{ + "checker": "plain-words-internal-names", + "meaning": "The reply names an internal tool, worker, queue, or process step as if the user already knows what it is, without saying what it does.", + "reads": "exchange", + "match": [ + "It points at a real design gap in e2e-autofix.", + "Run the invoker-watcher first.", + "The backlog grew after the redeploy before it started shrinking.", + "Preflight passes and the review unit is engine-runtime.", + "The merge gate is review_ready." + ], + "not_match": [ + "The worker that retries failed browser tests is making many copies of one job.", + "The repo's pre-publish check passes.", + "You asked about the merge queue: it is the line of PRs waiting for checks before they merge." + ], + "on_hit": "plain-words: the last reply named an internal tool or step without saying what it does." +} diff --git a/engine/hooks/diu-stop/phrases/plain-words-made-up-labels.json b/engine/hooks/diu-stop/phrases/plain-words-made-up-labels.json new file mode 100644 index 0000000..cc21570 --- /dev/null +++ b/engine/hooks/diu-stop/phrases/plain-words-made-up-labels.json @@ -0,0 +1,18 @@ +{ + "checker": "plain-words-made-up-labels", + "meaning": "The reply uses a label the assistant made up while working, which the user has not used, and does not say in everyday words what it means.", + "reads": "exchange", + "match": [ + "No hook decides differently.", + "The hooks only gain replay functions.", + "Is this the right safety line?", + "That was the fake problem.", + "Each slice passes on its own." + ], + "not_match": [ + "The hook's logic does not change; this is a simple refactor.", + "Each hook gets a small extra function that replays old chats; the live hook never calls it.", + "You asked about the safety line: it is one sentence saying why the change cannot break anything." + ], + "on_hit": "plain-words: the last reply used a made-up label; say what it means in everyday words or drop it." +} diff --git a/engine/hooks/diu-stop/phrases/plain-words-status-words.json b/engine/hooks/diu-stop/phrases/plain-words-status-words.json new file mode 100644 index 0000000..c018486 --- /dev/null +++ b/engine/hooks/diu-stop/phrases/plain-words-status-words.json @@ -0,0 +1,18 @@ +{ + "checker": "plain-words-status-words", + "meaning": "The reply uses a status word or state label without saying what actually happened or why.", + "reads": "exchange", + "match": [ + "Three tests were capped.", + "The reset is blocked.", + "That would double count.", + "Only a restart picks up newer code.", + "The branch is stale." + ], + "not_match": [ + "Three tests hit the retry limit, so they stopped and now need a person.", + "The restart could not run because a check refused it.", + "The running program still uses the version it loaded earlier; a restart loads the current version." + ], + "on_hit": "plain-words: the last reply used a status word without saying what happened." +} diff --git a/engine/hooks/diu-stop/phrases/plain-words-tech-jargon.json b/engine/hooks/diu-stop/phrases/plain-words-tech-jargon.json new file mode 100644 index 0000000..7e0e6ab --- /dev/null +++ b/engine/hooks/diu-stop/phrases/plain-words-tech-jargon.json @@ -0,0 +1,18 @@ +{ + "checker": "plain-words-tech-jargon", + "meaning": "The reply uses technical jargon or an abbreviation the user has not used, without a plain explanation next to it.", + "reads": "exchange", + "match": [ + "It died on a 401 unauthorized.", + "That is a remote infra gap.", + "The script ships as an SEA.", + "Mostly regex false positives.", + "Force-push with lease, then a three-way apply." + ], + "not_match": [ + "The login had expired, so the server refused the request.", + "The problem is on the other machines, not this laptop.", + "Most of the alarms were wrong: the word matched but the meaning did not." + ], + "on_hit": "plain-words: the last reply used jargon or an abbreviation without a plain explanation." +} diff --git a/engine/hooks/diu-stop/tests/test_plain_words.py b/engine/hooks/diu-stop/tests/test_plain_words.py new file mode 100644 index 0000000..9b7a2d3 --- /dev/null +++ b/engine/hooks/diu-stop/tests/test_plain_words.py @@ -0,0 +1,75 @@ +import os +import sys +import unittest + +HOOK_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +LLM_JUDGE_DIR = os.path.join(os.path.dirname(HOOK_DIR), "llm-judge") +sys.path.insert(0, LLM_JUDGE_DIR) + +import phrases + +PHRASES_DIR = os.path.join(HOOK_DIR, "phrases") +PREFIX = "plain-words-" +CATEGORIES = ( + "plain-words-made-up-labels", + "plain-words-code-names", + "plain-words-internal-names", + "plain-words-tech-jargon", + "plain-words-status-words", +) +EDGE = ".,;:()!?\"'" + + +def _is_pr_number(token): + return token.startswith("#") and token.strip(EDGE).lstrip("#").isdigit() + + +def _is_date(token): + parts = token.strip(EDGE).split("-") + return len(parts) == 3 and len(parts[0]) == 4 and all(part.isdigit() for part in parts) + + +def _load(checker): + return phrases.load(checker, directory=PHRASES_DIR) + + +class TestPlainWords(unittest.TestCase): + def test_every_category_file_is_listed(self): + found = sorted(name[:-5] for name in os.listdir(PHRASES_DIR) if name.startswith(PREFIX) and name.endswith(".json")) + self.assertEqual(found, sorted(CATEGORIES)) + + def test_each_category_loads_and_reads_the_exchange(self): + for checker in CATEGORIES: + with self.subTest(checker=checker): + dictionary = _load(checker) + self.assertEqual(dictionary["reads"], "exchange") + self.assertGreaterEqual(len(dictionary["match"]), 3) + self.assertGreaterEqual(len(dictionary["not_match"]), 2) + self.assertTrue(dictionary["on_hit"].startswith("plain-words:")) + + def test_no_phrase_names_a_pr_number_or_a_date(self): + for checker in CATEGORIES: + dictionary = _load(checker) + for phrase in [dictionary["meaning"], *dictionary["match"], *dictionary["not_match"]]: + for token in phrase.split(): + with self.subTest(checker=checker, token=token): + self.assertFalse(_is_pr_number(token)) + self.assertFalse(_is_date(token)) + + def test_no_phrase_sits_in_two_categories(self): + seen = {} + for checker in CATEGORIES: + dictionary = _load(checker) + for phrase in dictionary["match"] + dictionary["not_match"]: + self.assertNotIn(phrase, seen, f"{phrase!r} is in {seen.get(phrase)} and {checker}") + seen[phrase] = checker + + def test_a_pr_number_and_a_date_are_recognised(self): + self.assertTrue(_is_pr_number("#412.")) + self.assertTrue(_is_date("2026-09-11")) + self.assertFalse(_is_pr_number("#tag")) + self.assertFalse(_is_date("engine-runtime")) + + +if __name__ == "__main__": + unittest.main()