Add naming guide to triggers and conditions

[joostlek]

Proposed change

Add naming guide to triggers and conditions

Type of change

• Document existing features within Home Assistant
• Document new or changing features for which there is an existing pull request elsewhere
• Spelling or grammatical corrections, or rewording for improved clarity
• Editing or restructuring documentation guidelines
• Changes to the backend of this documentation
• Remove stale or deprecated documentation

Checklist

• I have read and followed the documentation guidelines.
• I have verified that my changes render correctly in the documentation.

Additional information

• This PR fixes or closes issue: fixes #
• Link to relevant existing code or pull request:

Summary by CodeRabbit

• Documentation
  • Added clearer naming guidelines for automation triggers and conditions.
  • Included rules for how titles should be written, with guidance for tense, phrasing, and event-specific patterns.
  • Documented consistent key naming conventions, including supported lowercase snake_case formats and state/value-based variants.

[coderabbitai]

🧹 Nitpick comments (3)

docs/automations.md (3)

126-126: 📐 Maintainability & Code Quality | 🔵 Trivial

Use a more direct and authoritative verb.

Replace "Prefer" with "Use" to maintain a direct, authoritative tone in instructional documentation.

-Lead with the entity type even for sensor and zone triggers. Prefer "Dropdown selection changed" over "Selection changed", and "Zone entered" over "Entered zone".
+Lead with the entity type even for sensor and zone triggers. Use "Dropdown selection changed" over "Selection changed", and "Zone entered" over "Entered zone".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/automations.md` at line 126, The wording in the automation trigger
guidance is too tentative, so update the sentence in the documentation to use a
direct instruction instead of “Prefer.” In the relevant text about entity-type
phrasing for sensor and zone triggers, keep the examples like “Dropdown
selection changed” and “Zone entered,” but replace “Prefer” with “Use” to match
the authoritative tone.

---

267-267: 📐 Maintainability & Code Quality | 🔵 Trivial

Use a more direct prohibition.

Replace "avoid" with "Do not use" to maintain an authoritative tone in instructional documentation.

-Include the entity type even for value conditions, and avoid bare property names such as "Volume".
+Include the entity type even for value conditions, and do not use bare property names such as "Volume".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/automations.md` at line 267, The wording in the value-based conditions
guidance is too soft and should be made more direct. Update the sentence in the
documentation to use a prohibition instead of “avoid,” specifically in the
section describing the “[Entity type] [property]” variant, so it clearly says
not to use bare property names like “Volume” and keeps the authoritative tone.

Source: Path instructions

---

138-138: 📐 Maintainability & Code Quality | 🔵 Trivial

Replace "at the moment" with a concise adverb.

Per the Microsoft Style Guide, replace the wordy phrase "at the moment" with a concise adverb such as "when" or "as." Also remove "more natural and" to state the requirement directly.

-Open with "Triggers when". A trigger fires at the moment the event happens, so "when" is more natural and more accurate than "after".
+Open with "Triggers when". A trigger fires when the event happens, so "when" is more accurate than "after".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/automations.md` at line 138, The wording in the automation description
should be tightened to follow the style guide by replacing the phrase “at the
moment” with a concise adverb such as “when” or “as,” and removing the extra
phrasing around “more natural and” so the guidance is stated directly; update
the sentence in the relevant documentation text to keep the same meaning with
fewer words.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/automations.md`:
- Line 126: The wording in the automation trigger guidance is too tentative, so
update the sentence in the documentation to use a direct instruction instead of
“Prefer.” In the relevant text about entity-type phrasing for sensor and zone
triggers, keep the examples like “Dropdown selection changed” and “Zone
entered,” but replace “Prefer” with “Use” to match the authoritative tone.
- Line 267: The wording in the value-based conditions guidance is too soft and
should be made more direct. Update the sentence in the documentation to use a
prohibition instead of “avoid,” specifically in the section describing the
“[Entity type] [property]” variant, so it clearly says not to use bare property
names like “Volume” and keeps the authoritative tone.
- Line 138: The wording in the automation description should be tightened to
follow the style guide by replacing the phrase “at the moment” with a concise
adverb such as “when” or “as,” and removing the extra phrasing around “more
natural and” so the guidance is stated directly; update the sentence in the
relevant documentation text to keep the same meaning with fewer words.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 11eb6b59-9f17-4654-97cb-2b2478f3c720

📥 Commits

Reviewing files that changed from the base of the PR and between c6ac27b and a088695.

📒 Files selected for processing (1)

• docs/automations.md