Clarify and refine edit format instructions for consistency and accessibility needs

Author: robertpiosik

packages/vscode/src/constants/edit-format-instructions.ts

@@ -1,6 +1,6 @@
-const intro = `Whenever showing a new, updated, renamed or deleted file, provide a brief explanation, then print path in a markdown heading (e.g. ### New file: \`src/examples/hello.py\`, ### Updated file: \`src/examples/hello.py\`, ### Renamed file: \`src/examples/hello.py\` (old) \`src/welcome.py\` (new), ### Deleted file: \`src/examples/hello.py\`)`
+const intro = `Whenever showing a new, updated, renamed or deleted file, provide a brief explanation, then print the path in a markdown heading (e.g. ### New file: \`src/examples/hello.py\`, ### Updated file: \`src/examples/hello.py\`, ### Renamed file: \`src/examples/hello.py\` (old) \`src/welcome.py\` (new), ### Deleted file: \`src/examples/hello.py\`), followed by a file within a markdown code block, when necessary.`
 
-export const EDIT_FORMAT_INSTRUCTIONS_WHOLE = `${intro}, followed by a markdown code block with full contents—as I have a disability which means I can't type and need to be able to just copy and paste. Example:
+export const EDIT_FORMAT_INSTRUCTIONS_WHOLE = `${intro} You must show file contents in full—as I have a disability which means I can't type and need to be able to just copy and paste. Example:
 Updated the greeting text.
 
 ### Updated file: \`src/examples/hello.py\`
@@ -12,19 +12,23 @@ def show_greeting():
   print(GREETING)
 \`\`\``
 
-export const EDIT_FORMAT_INSTRUCTIONS_TRUNCATED = `${intro}, followed by a markdown code block with truncated contents—as a space saving measure unchanged parts should be hidden behind ellipsis comments, e.g. "# ... ". Example:
+export const EDIT_FORMAT_INSTRUCTIONS_TRUNCATED = `${intro} As a space saving measure, replace unchanged function bodies with ellipsis comments, e.g. "# ...". Example:
 Updated the greeting text.
 
 ### Updated file: \`src/examples/hello.py\`
 
 \`\`\`python
+DURATION = 5
 GREETING = "Hello, World!"
 
+def get_duration():
+  # ...
+
 def show_greeting():
-  # ... the function remains unchanged
+  # ...
 \`\`\``
 
-export const EDIT_FORMAT_INSTRUCTIONS_DIFF = `${intro}, followed by a unified diff within a markdown code block. Example:
+export const EDIT_FORMAT_INSTRUCTIONS_DIFF = `${intro} Whenever showing changes to the original files, use the Unified Diff format. Example:
 Updated the greeting text.
 
 ### Updated file: \`src/examples/hello.py\`
@@ -40,7 +44,7 @@ Updated the greeting text.
    print(GREETING)
 \`\`\``
 
-export const EDIT_FORMAT_INSTRUCTIONS_BEFORE_AFTER = `${intro}, followed by a markdown code block showing the original and updated code snippets with Git-style merge conflict markers. Example:
+export const EDIT_FORMAT_INSTRUCTIONS_BEFORE_AFTER = `${intro} Whenever showing changes to the original files, use Git-style merge conflict markers. Example:
 Updated the greeting text.
 
 ### Updated file: \`src/examples/hello.py\`