diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md
index 97d618407e..aba7324a99 100644
--- a/docs/src/content/docs/reference/frontmatter-full.md
+++ b/docs/src/content/docs/reference/frontmatter-full.md
@@ -143,7 +143,10 @@ on:
   # created, updated, or closed
   # (optional)
   pull_request:
-    # List of pull request event types to trigger on
+    # Pull request event types to trigger on. Note: 'converted_to_draft' and
+    # 'ready_for_review' represent state transitions (events) rather than states.
+    # While technically valid to listen for both, consider if you need to handle both
+    # transitions or just one.
     # (optional)
     types: []
       # Array of strings
diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json
index 0b39ee2af9..c23fcd6ddd 100644
--- a/pkg/parser/schemas/main_workflow_schema.json
+++ b/pkg/parser/schemas/main_workflow_schema.json
@@ -235,7 +235,8 @@
               "properties": {
                 "types": {
                   "type": "array",
-                  "description": "List of pull request event types to trigger on",
+                  "description": "Pull request event types to trigger on. Note: 'converted_to_draft' and 'ready_for_review' represent state transitions (events) rather than states. While technically valid to listen for both, consider if you need to handle both transitions or just one.",
+                  "$comment": "converted_to_draft and ready_for_review are logically opposite state transitions. Using both may indicate unclear intent.",
                   "items": {
                     "type": "string",
                     "enum": [