From 7e90e5cae655355da118ec925b73a256deeed892 Mon Sep 17 00:00:00 2001
From: Colin McDonnell <colinmcd94@gmail.com>
Date: Wed, 20 May 2026 02:31:34 +0000
Subject: [PATCH] Align Plan-mode prompts on report_progress as the canonical
 plan tool (#786)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: align Plan-mode prompts on report_progress as the canonical plan tool

Fixes #673.

Three sites disagreed on where Plan output should be posted, letting a
model synthesize a broken third interpretation (initial post via
`report_progress({ target_plan_comment: true })`, which then misses the
`existingPlanCommentId` precondition). This PR aligns all three on
`report_progress` as canonical, with `target_plan_comment` reserved for
revisions only:

- `action/modes.ts` Plan step 4 — spell out that the initial plan post
  uses `report_progress` WITHOUT `target_plan_comment`, and that
  revisions go through `select_mode`'s PlanEdit override.
- `action/mcp/comment.ts` `target_plan_comment` flag description —
  make the "revisions only" precondition explicit and call out the
  initial-post path by name.
- `action/utils/instructions.ts` Progress reporting paragraph — drop
  the misleading "(e.g., Plan comments)" parenthetical that read as
  "use create_issue_comment for plans".

`PlanEdit` (in `action/mcp/selectMode.ts`) was already correct and is
unchanged.

Intentionally out of scope (to keep the fix minimal): a `publish_plan`
tool, removing the vestigial `create_issue_comment({ type: "Plan" })`
branch, hardening the run-end cleanup guard for the
`target_plan_comment but no existingPlanCommentId` fallthrough, and
renaming `target_plan_comment`.

* align create_issue_comment description with report_progress as canonical plan tool
---
 mcp/comment.ts        | 4 ++--
 modes.ts              | 2 +-
 utils/instructions.ts | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/mcp/comment.ts b/mcp/comment.ts
index 2ba0706..1da52bf 100644
--- a/mcp/comment.ts
+++ b/mcp/comment.ts
@@ -68,7 +68,7 @@ export function CreateCommentTool(ctx: ToolContext) {
     description:
       "Create a comment on a GitHub issue or PR. " +
       'Example: `create_issue_comment({ issueNumber: 1234, body: "Thanks for the report." })`. ' +
-      "For progress/plan updates on the current run use report_progress instead. Use type: 'Plan' for plan comments.",
+      "For progress/plan updates on the current run use report_progress instead — plan output (initial post AND revisions) is always posted via report_progress, never via this tool.",
     parameters: Comment,
     execute: execute(async ({ issueNumber, body, type: commentType }) => {
       const bodyWithFooter = addFooter(ctx, body);
@@ -153,7 +153,7 @@ export function EditCommentTool(ctx: ToolContext) {
 export const ReportProgress = type({
   body: type.string.describe("the progress update content to share"),
   "target_plan_comment?": type("boolean").describe(
-    "when true, update the existing plan comment (from select_mode lookup) instead of the progress comment; use when editing an existing plan"
+    "for revising an existing plan comment ONLY. set to true only when the PlanEdit checklist from select_mode tells you to (i.e. a prior plan comment was found for this issue). NEVER set on the initial plan post — the initial plan reuses the run's progress comment and is posted by calling report_progress without this flag."
   ),
 });
 
diff --git a/modes.ts b/modes.ts
index 8122e9c..b14ab7b 100644
--- a/modes.ts
+++ b/modes.ts
@@ -495,7 +495,7 @@ ${PR_SUMMARY_FORMAT}`,
 
 3. Produce a structured, actionable plan with clear milestones.
 
-4. Call \`${t("report_progress")}\` with the plan.`,
+4. Call \`${t("report_progress")}\` with the plan body. Do NOT set \`target_plan_comment\` — that flag is exclusively for revising an existing plan, and \`${t("select_mode")}\` will route you to a separate PlanEdit checklist when a prior plan comment exists for this issue.`,
     },
     {
       name: "Fix",
diff --git a/utils/instructions.ts b/utils/instructions.ts
index 18b4001..d1b1a83 100644
--- a/utils/instructions.ts
+++ b/utils/instructions.ts
@@ -317,7 +317,7 @@ When embedding images (e.g. uploaded screenshots) in comments or PR bodies, alwa
 
 **\`report_progress\`**: call this exactly once at the end of every run with a brief final summary (1-3 sentences) unless the mode guidance instructs otherwise. Never call it for intermediate status updates (e.g., "Checking for changes...", "Starting review...") — the task list handles live progress automatically. Calling \`report_progress\` replaces the task list with your summary and preserves the current task list in a collapsible section. Keep the summary concise — do not repeat what the task list already shows. Focus on the outcome (what was accomplished, links to artifacts) rather than listing individual steps. If something failed, include the tool's error text even when that makes the summary longer.
 
-Never use \`create_issue_comment\` for task progress — that creates duplicate comments and leaves the progress comment stuck in its initial state. \`create_issue_comment\` is only for standalone comments unrelated to your current task (e.g., Plan comments).
+Never use \`create_issue_comment\` for task progress — that creates duplicate comments and leaves the progress comment stuck in its initial state. \`create_issue_comment\` is only for standalone comments unrelated to your current task. Plan output (initial post AND revisions) goes through \`report_progress\` — see the Plan mode guidance for details.
 
 ### If you get stuck