add changeset for write_to_file prompt guidance

.changeset/write-to-file-skeleton-guidance.md

@@ -0,0 +1,5 @@
+---
+"claude-dev": patch
+---
+
+Add proactive guidance to write_to_file tool description advising models to write a skeleton first and use replace_in_file incrementally when file content is too large for a single response

src/core/prompts/system-prompt/__tests__/__snapshots__/anthropic_claude_sonnet_4-basic.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/anthropic_claude_sonnet_4-no-browser.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/anthropic_claude_sonnet_4-no-focus-chain.snap

@@ -45,7 +45,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/anthropic_claude_sonnet_4-no-mcp.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_devstral-basic.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_devstral-no-browser.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_devstral-no-focus-chain.snap

@@ -45,7 +45,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_devstral-no-mcp.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_native_next_gen.tools.snap

@@ -84,7 +84,7 @@
     "type": "function",
     "function": {
       "name": "write_to_file",
-      "description": "[IMPORTANT: Always output the absolutePath first] Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.",
+      "description": "[IMPORTANT: Always output the absolutePath first] Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.",
       "strict": false,
       "parameters": {
         "type": "object",

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_3-basic.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_3-no-browser.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_3-no-focus-chain.snap

@@ -45,7 +45,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_3-no-mcp.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5-basic.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5-no-browser.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5-no-focus-chain.snap

@@ -45,7 +45,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5-no-mcp.snap

@@ -50,7 +50,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openrouter_arcee_ai_trinity_large_preview-basic.snap

@@ -59,7 +59,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openrouter_arcee_ai_trinity_large_preview-no-browser.snap

@@ -59,7 +59,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openrouter_arcee_ai_trinity_large_preview-no-focus-chain.snap

@@ -54,7 +54,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/openrouter_arcee_ai_trinity_large_preview-no-mcp.snap

@@ -59,7 +59,7 @@ Usage:
 </read_file>
 
 ## write_to_file
-Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.
+Description: Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.
 Parameters:
 - path: (required) The path of the file to write to (relative to the current working directory /test/project)
 - content: (required) The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified.

src/core/prompts/system-prompt/__tests__/__snapshots__/vertex_gemini3.tools.snap

@@ -38,7 +38,7 @@
   },
   {
     "name": "write_to_file",
-    "description": "Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.",
+    "description": "Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.",
     "parameters": {
       "type": "OBJECT",
       "properties": {

src/core/prompts/system-prompt/tools/write_to_file.ts

@@ -29,7 +29,7 @@ const GENERIC: ClineToolSpec = {
 	id,
 	name: "write_to_file",
 	description:
-		"Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.",
+		"Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.",
 	parameters: [
 		{
 			name: "path",
@@ -53,7 +53,7 @@ const NATIVE_NEXT_GEN: ClineToolSpec = {
 	id,
 	name: "write_to_file",
 	description:
-		"[IMPORTANT: Always output the absolutePath first] Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file.",
+		"[IMPORTANT: Always output the absolutePath first] Request to write content to a file at the specified path. If the file exists, it will be overwritten with the provided content. If the file doesn't exist, it will be created. This tool will automatically create any directories needed to write the file. If the file content is too large to generate in a single response, write a skeleton first (just imports, class/function signatures, no implementations), then use replace_in_file to fill in each section incrementally.",
 	parameters: [
 		{
 			name: "absolutePath",