From 58da98fc0d9090750f1e79710ac14a4d656311b7 Mon Sep 17 00:00:00 2001 From: awschmeder Date: Sat, 13 Jun 2026 17:10:44 -0700 Subject: [PATCH 1/4] docs(prompt): enhance apply_diff tool instructions for Gemini model success --- .changeset/improve-apply-diff-prompt.md | 5 +++++ src/core/prompts/tools/native-tools/apply_diff.ts | 7 ++++++- 2 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 .changeset/improve-apply-diff-prompt.md diff --git a/.changeset/improve-apply-diff-prompt.md b/.changeset/improve-apply-diff-prompt.md new file mode 100644 index 0000000000..c6cb65bdf3 --- /dev/null +++ b/.changeset/improve-apply-diff-prompt.md @@ -0,0 +1,5 @@ +--- +"zoo-code": patch +--- + +Enhance the `apply_diff` tool description and parameter instructions to enforce strict `:start_line:` formatting and copy-paste exact matching requirements, improving success rates for Gemini Flash and other smaller/faster models. diff --git a/src/core/prompts/tools/native-tools/apply_diff.ts b/src/core/prompts/tools/native-tools/apply_diff.ts index 3938e4886a..ec3da94d4f 100644 --- a/src/core/prompts/tools/native-tools/apply_diff.ts +++ b/src/core/prompts/tools/native-tools/apply_diff.ts @@ -9,7 +9,12 @@ const DIFF_PARAMETER_DESCRIPTION = `A string containing one or more search/repla [exact content to find] ======= [new content to replace with] ->>>>>>> REPLACE` +>>>>>>> REPLACE + +CRITICAL: +- The ':start_line:[line_number]' header is strictly required. It must follow the exact syntax ':start_line:[integer]' (for example: ':start_line:220'). Do not write headers with shorthand forms like ':220' or variations like ':start_line=220'. +- Copy the exact lines from the source file for a 100% string match including all whitespace, indentation, and newlines. +- Ensure the separator '-------' is on its own line immediately following ':start_line:[line_number]' with a newline.` export const apply_diff = { type: "function", From 69a7cbc3ccdf0a19e4c0491adc0d12dab2b71683 Mon Sep 17 00:00:00 2001 From: awschmeder Date: Sat, 13 Jun 2026 22:05:54 -0700 Subject: [PATCH 2/4] docs: add PR description for issue 611 --- plans/improve-apply-diff-prompt.pr.md | 33 +++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 plans/improve-apply-diff-prompt.pr.md diff --git a/plans/improve-apply-diff-prompt.pr.md b/plans/improve-apply-diff-prompt.pr.md new file mode 100644 index 0000000000..9b27db8d8d --- /dev/null +++ b/plans/improve-apply-diff-prompt.pr.md @@ -0,0 +1,33 @@ +### Related GitHub Issue + +Closes: #611 + +### Description + +This PR enhances the documentation and instructions for the `apply_diff` tool to improve its success rate, particularly for Gemini models. It addresses issues with malformed `:start_line:` syntax and imprecise diff matching by enforcing stricter, clearer requirements in the tool's system instructions and adding a corresponding guideline to `AGENTS.md`. + +### Test Procedure + +- Verify existing `apply_diff` behavior with `apps/vscode-e2e/src/suite/tools/apply-diff.test.ts`. +- Documentation updates applied in `src/core/prompts/tools/native-tools/apply_diff.ts` and `AGENTS.md`. + +### Pre-Submission Checklist + +- [x] **Issue Linked**: This PR is linked to an approved GitHub Issue. +- [x] **Scope**: My changes are focused on the linked issue (one major feature/fix per PR). +- [x] **Self-Review**: I have performed a thorough self-review of my code. +- [x] **Testing**: Existing tests cover the functionality; no new functionality requiring tests was added. +- [x] **Documentation Impact**: I have considered if my changes require documentation updates. +- [x] **Contribution Guidelines**: I have read and agree to the [Contributor Guidelines](/CONTRIBUTING.md). + +### Documentation Updates + +- [x] Yes, documentation updates are required. (This PR updates `apply_diff` tool instructions and `AGENTS.md`). + +### Additional Notes + +None. + +### Get in Touch + +Zoo AI Assistant From 1885e9c3efde0cf77342e3f5179498ece9b3fc83 Mon Sep 17 00:00:00 2001 From: awschmeder Date: Sat, 13 Jun 2026 22:14:44 -0700 Subject: [PATCH 3/4] docs(plan): align PR description plan with actual changes by removing AGENTS.md reference --- plans/improve-apply-diff-prompt.pr.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/plans/improve-apply-diff-prompt.pr.md b/plans/improve-apply-diff-prompt.pr.md index 9b27db8d8d..47c63365e8 100644 --- a/plans/improve-apply-diff-prompt.pr.md +++ b/plans/improve-apply-diff-prompt.pr.md @@ -4,12 +4,14 @@ Closes: #611 ### Description -This PR enhances the documentation and instructions for the `apply_diff` tool to improve its success rate, particularly for Gemini models. It addresses issues with malformed `:start_line:` syntax and imprecise diff matching by enforcing stricter, clearer requirements in the tool's system instructions and adding a corresponding guideline to `AGENTS.md`. +This PR enhances the documentation and instructions for the `apply_diff` tool to improve its success rate, particularly for Gemini models. It addresses issues with malformed `:start_line:` syntax and imprecise diff matching by enforcing stricter, clearer requirements in the tool's system instructions. + +Note: While the issue notes that adding these guidelines to `AGENTS.md` resolved the issue locally, we have integrated them directly into the core prompts (`src/core/prompts/tools/native-tools/apply_diff.ts`) and have purposely omitted modifying `AGENTS.md` to adhere to repository PR hygiene guidelines. ### Test Procedure - Verify existing `apply_diff` behavior with `apps/vscode-e2e/src/suite/tools/apply-diff.test.ts`. -- Documentation updates applied in `src/core/prompts/tools/native-tools/apply_diff.ts` and `AGENTS.md`. +- Prompt instructions updated in `src/core/prompts/tools/native-tools/apply_diff.ts`. ### Pre-Submission Checklist @@ -22,7 +24,7 @@ This PR enhances the documentation and instructions for the `apply_diff` tool to ### Documentation Updates -- [x] Yes, documentation updates are required. (This PR updates `apply_diff` tool instructions and `AGENTS.md`). +- [ ] No documentation updates are required. (Updates are purely internal prompt instruction refinements). ### Additional Notes From d3a564bf36417ed4db2b56d9773158a618f2e3ee Mon Sep 17 00:00:00 2001 From: awschmeder Date: Mon, 22 Jun 2026 21:04:19 -0700 Subject: [PATCH 4/4] docs(prompt): soften :start_line: to strongly recommended and untrack gitignored plan Addresses PR #619 review feedback from edelauna: - :start_line: is optional in the multi-search-replace parser, so describe it as strongly recommended rather than required (truthful while preserving compliance for smaller models). - Remove plans/improve-apply-diff-prompt.pr.md from tracking; plans/ is gitignored. - Align changeset summary with the corrected wording. --- .changeset/improve-apply-diff-prompt.md | 2 +- plans/improve-apply-diff-prompt.pr.md | 35 ------------------- .../prompts/tools/native-tools/apply_diff.ts | 4 +-- 3 files changed, 3 insertions(+), 38 deletions(-) delete mode 100644 plans/improve-apply-diff-prompt.pr.md diff --git a/.changeset/improve-apply-diff-prompt.md b/.changeset/improve-apply-diff-prompt.md index c6cb65bdf3..4f8dc24c1e 100644 --- a/.changeset/improve-apply-diff-prompt.md +++ b/.changeset/improve-apply-diff-prompt.md @@ -2,4 +2,4 @@ "zoo-code": patch --- -Enhance the `apply_diff` tool description and parameter instructions to enforce strict `:start_line:` formatting and copy-paste exact matching requirements, improving success rates for Gemini Flash and other smaller/faster models. +Enhance the `apply_diff` tool description and parameter instructions to recommend `:start_line:` with exact syntax and emphasize copy-paste exact matching requirements, improving success rates for Gemini Flash and other smaller/faster models. diff --git a/plans/improve-apply-diff-prompt.pr.md b/plans/improve-apply-diff-prompt.pr.md deleted file mode 100644 index 47c63365e8..0000000000 --- a/plans/improve-apply-diff-prompt.pr.md +++ /dev/null @@ -1,35 +0,0 @@ -### Related GitHub Issue - -Closes: #611 - -### Description - -This PR enhances the documentation and instructions for the `apply_diff` tool to improve its success rate, particularly for Gemini models. It addresses issues with malformed `:start_line:` syntax and imprecise diff matching by enforcing stricter, clearer requirements in the tool's system instructions. - -Note: While the issue notes that adding these guidelines to `AGENTS.md` resolved the issue locally, we have integrated them directly into the core prompts (`src/core/prompts/tools/native-tools/apply_diff.ts`) and have purposely omitted modifying `AGENTS.md` to adhere to repository PR hygiene guidelines. - -### Test Procedure - -- Verify existing `apply_diff` behavior with `apps/vscode-e2e/src/suite/tools/apply-diff.test.ts`. -- Prompt instructions updated in `src/core/prompts/tools/native-tools/apply_diff.ts`. - -### Pre-Submission Checklist - -- [x] **Issue Linked**: This PR is linked to an approved GitHub Issue. -- [x] **Scope**: My changes are focused on the linked issue (one major feature/fix per PR). -- [x] **Self-Review**: I have performed a thorough self-review of my code. -- [x] **Testing**: Existing tests cover the functionality; no new functionality requiring tests was added. -- [x] **Documentation Impact**: I have considered if my changes require documentation updates. -- [x] **Contribution Guidelines**: I have read and agree to the [Contributor Guidelines](/CONTRIBUTING.md). - -### Documentation Updates - -- [ ] No documentation updates are required. (Updates are purely internal prompt instruction refinements). - -### Additional Notes - -None. - -### Get in Touch - -Zoo AI Assistant diff --git a/src/core/prompts/tools/native-tools/apply_diff.ts b/src/core/prompts/tools/native-tools/apply_diff.ts index ec3da94d4f..cdbd99df33 100644 --- a/src/core/prompts/tools/native-tools/apply_diff.ts +++ b/src/core/prompts/tools/native-tools/apply_diff.ts @@ -2,7 +2,7 @@ import type OpenAI from "openai" const APPLY_DIFF_DESCRIPTION = `Apply precise, targeted modifications to an existing file using one or more search/replace blocks. This tool is for surgical edits only; the 'SEARCH' block must exactly match the existing content, including whitespace and indentation. To make multiple targeted changes, provide multiple SEARCH/REPLACE blocks in the 'diff' parameter. Use the 'read_file' tool first if you are not confident in the exact content to search for.` -const DIFF_PARAMETER_DESCRIPTION = `A string containing one or more search/replace blocks defining the changes. The ':start_line:' is required and indicates the starting line number of the original content. You must not add a start line for the replacement content. Each block must follow this format: +const DIFF_PARAMETER_DESCRIPTION = `A string containing one or more search/replace blocks defining the changes. The ':start_line:' is strongly recommended and indicates the starting line number of the original content. You must not add a start line for the replacement content. Each block must follow this format: <<<<<<< SEARCH :start_line:[line_number] ------- @@ -12,7 +12,7 @@ const DIFF_PARAMETER_DESCRIPTION = `A string containing one or more search/repla >>>>>>> REPLACE CRITICAL: -- The ':start_line:[line_number]' header is strictly required. It must follow the exact syntax ':start_line:[integer]' (for example: ':start_line:220'). Do not write headers with shorthand forms like ':220' or variations like ':start_line=220'. +- The ':start_line:[line_number]' header is strongly recommended for accurate matching. When provided, it must follow the exact syntax ':start_line:[integer]' (for example: ':start_line:220'). Do not write headers with shorthand forms like ':220' or variations like ':start_line=220'. - Copy the exact lines from the source file for a 100% string match including all whitespace, indentation, and newlines. - Ensure the separator '-------' is on its own line immediately following ':start_line:[line_number]' with a newline.`