Align PR Review Action Guidance with Agreed Style Recommendations

[yetanothertw]

Context: Recent Slack thread highlights inconsistency between the docs review action guidance and the established style guide regarding recommendations and modal verbs (should/we recommend).

Task:

• Update the PR review action logic and messages to clearly align with the Slack consensus:
  • Prefer active, second-person, and imperative tone for recommendations where there is a single best approach.
  • "We recommend" should be tolerated only sparingly and never as a mandate; only use when no clearer, user-focused phrasing is possible.
  • Avoid "should/could/would", passive voice, and ambiguous advice.
• Document references and link to the style guide sections for rationale.
• Example thread for context: contributors have found previous review bot suggestions confusing and not in sync with https://www.elastic.co/docs/contribute-docs/style-guide/voice-tone#avoid-ambiguity and https://www.elastic.co/docs/contribute-docs/style-guide/grammar-spelling#verb-tense

Goal: Reduce contributor confusion by ensuring the PR review automation and style guide messaging are in sync.

/cc Doc team for review and input.

View original Slack conversation