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

@@ -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
+### Goal
-<1-3 sentences on the approach and why.>
+<1-2 sentences on the user-visible outcome and why.>
 
-### Files to change
+### Approach
-- `path/to/file` — <what changes and why>
+- <high-level code structure or system boundary changes>
-
+- <key decisions, tradeoffs, or rejected alternatives when useful>
-### Steps
-1. <ordered, concrete implementation steps>
 
 ### 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."""

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 "
+    "Plan mode is active. Stay read-only: research the codebase, then record a "
-    "implementation plan with the `save_plan` tool (it publishes the plan to the "
+    "concise, high-level plan with the `save_plan` tool (it publishes the plan to "
-    "review page) and share the plan-review link in the source channel. Do not edit "
+    "the review page) and share the plan-review link in the source channel. Do not "
-    "files, commit, push, or open a PR — wait for the user to approve the plan."
+    "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
+    Once activated, stay read-only: research the codebase, then record a concise,
-    with the ``save_plan`` tool (it publishes the plan to the review page) and
+    high-level plan with the ``save_plan`` tool (it publishes the plan to the
-    share the plan-review link with the user. Do not edit files, commit, push,
+    review page) and share the plan-review link with the user. Do not edit files,
-    or open a PR — the user reviews the plan and approves it before you
+    commit, push, or open a PR — the user reviews the plan and approves it before
-    implement.
+    you implement.
     """
     thread_id = _thread_id_from_config()
     if thread_id:

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
+    fenced code blocks all render. Keep it concise and high level, focusing on
-    change, ordered steps, risks).
+    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.