From 14779e4edbb84afdc73c2c654b6c04dfdd675f1d Mon Sep 17 00:00:00 2001
From: Bunyamin inan <mail@bunyamininan.com>
Date: Sun, 21 Jun 2026 18:48:24 +0200
Subject: [PATCH] docs: add truthful naming standard

---
 .../engineering-playbook/skills/code-review/SKILL.md |  7 +++++--
 .../skills/coding-standards/SKILL.md                 | 12 ++++++++++--
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/plugins/engineering-playbook/skills/code-review/SKILL.md b/plugins/engineering-playbook/skills/code-review/SKILL.md
index 9aa8b76..d3c456c 100644
--- a/plugins/engineering-playbook/skills/code-review/SKILL.md
+++ b/plugins/engineering-playbook/skills/code-review/SKILL.md
@@ -23,8 +23,8 @@ Use those standards as hard review criteria, not background suggestions.
    diff, commit diff, staged changes, or working-tree changes.
 2. Inspect every changed file line by line. For each changed class, method,
    function, variable, route, config value, migration, test, and dependency
-   boundary, check whether the implementation is correct and whether the names
-   reveal the real behavior.
+   boundary, check whether the implementation is correct and whether the text
+   and names reveal the real behavior.
 3. Read surrounding code until the intent, call paths, data flow, side effects,
    and failure behavior are clear. Do not review a line in isolation when nearby
    code changes its meaning.
@@ -45,6 +45,9 @@ Use those standards as hard review criteria, not background suggestions.
 6. Prefer small, local fixes that preserve the existing architecture. Suggest
    broader redesign only when the local fix would hide a deeper correctness or
    maintainability problem.
+7. Report truthful naming violations as `Normal` severity by default. Escalate
+   only when the misleading name creates a blocker-level correctness, security,
+   or data risk.
 
 ## Output Format
 
diff --git a/plugins/engineering-playbook/skills/coding-standards/SKILL.md b/plugins/engineering-playbook/skills/coding-standards/SKILL.md
index e58edd3..00e8aad 100644
--- a/plugins/engineering-playbook/skills/coding-standards/SKILL.md
+++ b/plugins/engineering-playbook/skills/coding-standards/SKILL.md
@@ -17,8 +17,6 @@ description: >-
   private/protected method or dedicated class with a name that explains the
   intent. A reader should understand what the logic means from the name before
   reading the implementation.
-- Name methods, classes, variables, and use cases after what they actually do,
-  including important side effects. Do not use names that hide behavior.
 - Avoid negative boolean names for methods, variables, value objects, and
   persisted fields. Prefer positive names such as `isEnabled` or
   `isPubliclyAvailable` instead of `isDisabled`, `isPaused`, or other names
@@ -28,6 +26,16 @@ description: >-
   `does...` only for methods that return `bool` and do not throw.
 - In PHP tests, mark test methods with the `#[Test]` attribute instead of the `test...` prefix or `@test` docblock annotation.
 
+## Rule: Truthful Naming
+All text and names must tell the truth about the implementation they represent.
+
+1. Name classes, methods, variables, use cases, tests, comments, and labels
+   after what they actually do or mean.
+2. Include important side effects, boundaries, and failure behavior in the name
+   when omitting them would mislead the reader.
+3. Prefer renaming over hiding behavior behind vague, aspirational, or
+   overly-polished language.
+
 ## Rule: Hexagonal Architecture
 Follow hexagonal architecture as the baseline.