From c03a6be7a8d560a06ff8407ea02f1225bcc38160 Mon Sep 17 00:00:00 2001
From: Ramon Nogueira <ramon.nogueira@langchain.dev>
Date: Mon, 29 Jun 2026 15:31:14 -0400
Subject: [PATCH] chore: keep plan guidance high-level (#1634)

Co-authored-by: Ramon Nogueira <270434257+ramon-langchain@users.noreply.github.com>
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
---
 agent/prompt.py                | 18 ++++++++----------
 agent/tools/enter_plan_mode.py | 18 +++++++++---------
 agent/tools/save_plan.py       |  5 +++--
 3 files changed, 20 insertions(+), 21 deletions(-)

diff --git a/agent/prompt.py b/agent/prompt.py
index fde3c174..56b0bba4 100644
--- a/agent/prompt.py
+++ b/agent/prompt.py
@@ -117,25 +117,23 @@ You are in a read-only research-and-planning phase. Your single deliverable is a
 
 **You MAY (read-only):** clone and read the repo (`read_file`, `ls`, `glob`, `grep`, read-only `execute` like `git clone`/`status`/`log`/`diff`, `cat`, `rg`), research with `web_search`/`fetch_url`, and ask clarifying questions via `slack_thread_reply` / `linear_comment`.
 
-**Workflow:** explore the relevant code aggressively, clarify ambiguity, then save ONE recommended plan with `save_plan` (pass the full Markdown as `plan_markdown`) using this structure:
+**Workflow:** explore the relevant code enough to choose a sound approach, clarify ambiguity, then save ONE concise recommended plan with `save_plan` (pass the full Markdown as `plan_markdown`) using this structure. Keep it high level: focus on desired behavior, architecture boundaries, product decisions, tradeoffs, rollout/migration concerns, and verification. Avoid file/function-level details and exhaustive file lists unless a specific implementation detail is unusually tricky, risky, or controversial. Aim for about one page or less unless the task truly requires more.
 
 ```
 ## Plan: <short title>
 
-### Overview
-<1-3 sentences on the approach and why.>
+### Goal
+<1-2 sentences on the user-visible outcome and why.>
 
-### Files to change
-- `path/to/file` — <what changes and why>
-
-### Steps
-1. <ordered, concrete implementation steps>
+### Approach
+- <high-level code structure or system boundary changes>
+- <key decisions, tradeoffs, or rejected alternatives when useful>
 
 ### Risks & considerations
-- <edge cases, migrations, cross-file impacts>
+- <edge cases, migrations, compatibility, product implications>
 
 ### Verification
-- <specific test files, lint, manual checks>
+- <targeted tests or manual checks that prove the behavior>
 ```
 
 After saving, post a brief completion message with the plan-review link via `slack_thread_reply` (Slack) or `linear_comment` (Linear), invite the user to review/comment/approve, then stop. Do not implement — you will be re-invoked with the approval and any feedback."""
diff --git a/agent/tools/enter_plan_mode.py b/agent/tools/enter_plan_mode.py
index 191e1ee7..a1d97e89 100644
--- a/agent/tools/enter_plan_mode.py
+++ b/agent/tools/enter_plan_mode.py
@@ -15,10 +15,10 @@ from ..dashboard.plan_store import PLAN_STATUS_PLANNING, set_plan_status
 logger = logging.getLogger(__name__)
 
 _ENTERED_MESSAGE = (
-    "Plan mode is active. Stay read-only: research the codebase, then record your "
-    "implementation plan with the `save_plan` tool (it publishes the plan to the "
-    "review page) and share the plan-review link in the source channel. Do not edit "
-    "files, commit, push, or open a PR — wait for the user to approve the plan."
+    "Plan mode is active. Stay read-only: research the codebase, then record a "
+    "concise, high-level plan with the `save_plan` tool (it publishes the plan to "
+    "the review page) and share the plan-review link in the source channel. Do not "
+    "edit files, commit, push, or open a PR — wait for the user to approve the plan."
 )
 
 
@@ -31,11 +31,11 @@ async def enter_plan_mode(tool_call_id: Annotated[str, InjectedToolCallId]) -> C
     NOT triggered by the word "plan" appearing in the request; use your
     judgment about whether planning is genuinely warranted.
 
-    Once activated, stay read-only: research the codebase, then record your plan
-    with the ``save_plan`` tool (it publishes the plan to the review page) and
-    share the plan-review link with the user. Do not edit files, commit, push,
-    or open a PR — the user reviews the plan and approves it before you
-    implement.
+    Once activated, stay read-only: research the codebase, then record a concise,
+    high-level plan with the ``save_plan`` tool (it publishes the plan to the
+    review page) and share the plan-review link with the user. Do not edit files,
+    commit, push, or open a PR — the user reviews the plan and approves it before
+    you implement.
     """
     thread_id = _thread_id_from_config()
     if thread_id:
diff --git a/agent/tools/save_plan.py b/agent/tools/save_plan.py
index df7dd73c..d346d35b 100644
--- a/agent/tools/save_plan.py
+++ b/agent/tools/save_plan.py
@@ -32,8 +32,9 @@ async def save_plan(plan_markdown: str) -> dict[str, Any]:
     again to overwrite the plan with a revised version when addressing feedback.
 
     Write the plan in standard Markdown — headings, bullet/numbered lists, and
-    fenced code blocks all render. Structure it clearly (overview, files to
-    change, ordered steps, risks).
+    fenced code blocks all render. Keep it concise and high level, focusing on
+    approach, decisions/tradeoffs, risks, and verification; avoid file/function
+    details unless they are unusually tricky or controversial.
 
     Args:
         plan_markdown: The full plan, as a Markdown document.