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