From d315c8bd65e84441351f53b6e2c4e9751ea0e697 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 13 Dec 2025 04:15:54 +0000
Subject: [PATCH 1/3] Initial plan


From fd6654793a476e932f38dfa8e1a8f2bd64d0de66 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 13 Dec 2025 04:22:44 +0000
Subject: [PATCH 2/3] Add documentation for draft/ready_for_review state
 transitions

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>
---
 pkg/parser/schemas/main_workflow_schema.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json
index 0b39ee2af9d..c23fcd6ddd1 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": [

From 8771d50dc8325c5c5e0da45b5cb0c2338d6c082e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 13 Dec 2025 04:30:17 +0000
Subject: [PATCH 3/3] Completed documentation changes with all validations
 passed

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>
---
 docs/src/content/docs/reference/frontmatter-full.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md
index 97d618407e0..aba7324a990 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