Merge pull request #1465 from Codium-ai/tr/prompts

docs: improve diff format documentation and code review instructions

docs/docs/core-abilities/metadata.md

@@ -32,14 +32,14 @@ For example, when generating code suggestions for different files, Qodo Merge ca
 
 @@ ... @@ def func1():
 __new hunk__
-11  unchanged code line0 in the PR
-12  unchanged code line1 in the PR
-13 +new code line2 added in the PR
-14  unchanged code line3 in the PR
+11  unchanged code line0
+12  unchanged code line1
+13 +new code line2 added
+14  unchanged code line3
 __old hunk__
  unchanged code line0
  unchanged code line1
--old code line2 removed in the PR
+-old code line2 removed
  unchanged code line3
 
 @@ ... @@ def func2():

docs/docs/tools/improve.md

@@ -122,7 +122,7 @@ Use triple quotes to write multi-line instructions. Use bullet points or numbers
 
 >`Platforms supported: GitHub, GitLab, Bitbucket`
 
-Another option to give additional guidance to the AI model is by creating a dedicated [**wiki page**](https://github.com/Codium-ai/pr-agent/wiki) called `best_practices.md`.
+Another option to give additional guidance to the AI model is by creating a `best_practices.md` file, either in your repository's root directory or as a [**wiki page**](https://github.com/Codium-ai/pr-agent/wiki) (we recommend the wiki page, as editing and maintaining it over time is easier).
 This page can contain a list of best practices, coding standards, and guidelines that are specific to your repo/organization.
 
 The AI model will use this wiki page as a reference, and in case the PR code violates any of the guidelines, it will create additional suggestions, with a dedicated label: `Organization

docs/docs/usage-guide/enabling_a_wiki.md

@@ -0,0 +1,23 @@
+
+
+For optimal functionality of Qodo Merge, we recommend enabling a wiki for each repository where Qodo Merge is installed. The wiki serves several important purposes:
+
+**Key Wiki Features:**
+
+- Storing a [configuration file](https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/#wiki-configuration-file)
+- Defining a [`best_practices.md`](https://qodo-merge-docs.qodo.ai/tools/improve/#best-practices) file
+- Track [accepted suggestions](https://qodo-merge-docs.qodo.ai/tools/improve/#suggestion-tracking)
+- Facilitates learning over time by creating an [auto_best_practices.md]() file
+
+
+**Setup Instructions:**
+
+To enable a wiki for your repository:
+
+1. Navigate to your repository's main page on GitHub
+2. Select "Settings" from the top navigation bar
+3. Locate the "Features" section
+4. Enable the "Wikis" option by checking the corresponding box
+5. Return to your repository's main page
+6. Look for the newly added "Wiki" tab in the top navigation
+7. Initialize your wiki by clicking "Create the first page" (this step is important - without creating an initial page, the wiki will not be fully functional)

docs/docs/usage-guide/index.md

@@ -5,6 +5,7 @@ It includes information on how to adjust Qodo Merge configurations, define which
 
 
 - [Introduction](./introduction.md)
+- [Enabling a Wiki](./enabling_a_wiki)
 - [Configuration File](./configuration_options.md)
 - [Usage and Automation](./automations_and_usage.md)
     - [Local Repo (CLI)](./automations_and_usage.md#local-repo-cli)

docs/mkdocs.yml

@@ -18,6 +18,7 @@ nav:
   - Usage Guide:
     - 'usage-guide/index.md'
     - Introduction: 'usage-guide/introduction.md'
+    - Enabling a Wiki: 'usage-guide/enabling_a_wiki.md'
     - Configuration File: 'usage-guide/configuration_options.md'
     - Usage and Automation: 'usage-guide/automations_and_usage.md'
     - Managing Mail Notifications: 'usage-guide/mail_notifications.md'

pr_agent/settings/pr_code_suggestions_prompts.toml

@@ -17,30 +17,36 @@ The PR code diff will be in the following structured format:
 
 @@ ... @@ def func1():
 __new hunk__
- unchanged code line0 in the PR
- unchanged code line1 in the PR
-+new code line2 added in the PR
- unchanged code line3 in the PR
+ unchanged code line0
+ unchanged code line1
++new code line2 added
+ unchanged code line3
 __old hunk__
  unchanged code line0
  unchanged code line1
--old code line2 removed in the PR
+-old code line2 removed
  unchanged code line3
 
 @@ ... @@ def func2():
 __new hunk__
  unchanged code line4
-+new code line5 removed in the PR
++new code line5 removed
  unchanged code line6
 
 ## File: 'src/file2.py'
 ...
 ======
 
-- In the format above, the diff is organized into separate '__new hunk__' and '__old hunk__' sections for each code chunk. '__new hunk__' contains the updated code, while '__old hunk__' shows the removed code. If no code was removed in a specific chunk, the __old hunk__ section will be omitted.
-- Code lines are prefixed with symbols: '+' for new code added in the PR, '-' for code removed, and ' ' for unchanged code.
+Important notes about the structured diff format above:
+1. Each PR code chunk is decoupled into separate '__new hunk__' and '__old hunk__' sections:
+  - The '__new hunk__' section shows the code chunk AFTER the PR changes.
+  - The '__old hunk__' section shows the code chunk BEFORE the PR changes. If no code was removed from the chunk, the '__old hunk__' section will be omitted.
+2. The diff uses line prefixes to show changes:
+  '+' → new line code added (will appear only in '__new hunk__')
+  '-' → line code removed (will appear only in '__old hunk__')
+  ' ' → unchanged context lines (will appear in both sections)
 {%- if is_ai_metadata %}
-- When available, an AI-generated summary will precede each file's diff, with a high-level overview of the changes. Note that this summary may not be fully accurate or complete.
+3. When available, an AI-generated summary will precede each file's diff, with a high-level overview of the changes. Note that this summary may not be fully accurate or complete.
 {%- endif %}
 
 
@@ -50,16 +56,17 @@ Specific guidelines for generating code suggestions:
 {%- else %}
 - Provide up to {{ num_code_suggestions }} distinct and insightful code suggestions. Return less suggestions if no pertinent ones are applicable.
 {%- endif %}
-- Focus solely on enhancing new code introduced in the PR, identified by '+' prefixes in '__new hunk__' sections.
+- DO NOT suggest implementing changes that are already present in the '+' lines compared to the '-' lines.
+- Focus your suggestions ONLY on new code introduced in the PR ('+' lines in '__new hunk__' sections).
 {%- if not focus_only_on_problems %}
 - Prioritize suggestions that address potential issues, critical problems, and bugs in the PR code. Avoid repeating changes already implemented in the PR. If no pertinent suggestions are applicable, return an empty list.
 - Don't suggest to add docstring, type hints, or comments, to remove unused imports, or to use more specific exception types.
 {%- else %}
 - Only give suggestions that address critical problems and bugs in the PR code. If no relevant suggestions are applicable, return an empty list.
-- Do not suggest to change packages versions.
+- Do not suggest to change packages version, add missing import statement, or declare undefined variable.
 {%- endif %}
 - When mentioning code elements (variables, names, or files) in your response, surround them with backticks (`). For example: "verify that `user_id` is..."
-- Remember that Pull Request reviews show only changed code segments (diff hunks), not the entire codebase. Without full context, be cautious about suggesting modifications that could duplicate existing functionality (such as error handling) or questioning variable declarations that may exist elsewhere. Keep your review focused on the visible changes, acknowledging they're part of a larger codebase.
+- Note that you only see changed code segments (diff hunks in a PR), not the entire codebase. Avoid suggestions that might duplicate existing functionality or questioning code elements (like variables declerations or import statements) that may be defined elsewhere in the codebase.
 
 {%- if extra_instructions %}
 
@@ -79,7 +86,7 @@ class CodeSuggestion(BaseModel):
     suggestion_content: str = Field(description="An actionable suggestion to enhance, improve or fix the new code introduced in the PR. Don't present here actual code snippets, just the suggestion. Be short and concise")
     existing_code: str = Field(description="A short code snippet from a '__new hunk__' section that the suggestion aims to enhance or fix. Include only complete code lines. Use ellipsis (...) for brevity if needed. This snippet should represent the specific PR code targeted for improvement.")
     improved_code: str = Field(description="A refined code snippet that replaces the 'existing_code' snippet after implementing the suggestion.")
-    one_sentence_summary: str = Field(description="A concise, single-sentence overview of the suggested improvement. Focus on the 'what'. Be general, and avoid method or variable names.")
+    one_sentence_summary: str = Field(description="A concise, single-sentence overview (up to 6 words) of the suggested improvement. Focus on the 'what'. Be general, and avoid method or variable names.")
 {%- if not focus_only_on_problems %}
     label: str = Field(description="A single, descriptive label that best characterizes the suggestion type. Possible labels include 'security', 'possible bug', 'possible issue', 'performance', 'enhancement', 'best practice', 'maintainability', 'typo'. Other relevant labels are also acceptable.")
 {%- else %}

pr_agent/settings/pr_code_suggestions_reflect_prompts.toml

@@ -49,14 +49,14 @@ The PR code diff will be presented in the following structured format:
 
 @@ ... @@ def func1():
 __new hunk__
-11  unchanged code line0 in the PR
-12  unchanged code line1 in the PR
-13 +new code line2 added in the PR
-14  unchanged code line3 in the PR
+11  unchanged code line0
+12  unchanged code line1
+13 +new code line2 added
+14  unchanged code line3
 __old hunk__
  unchanged code line0
  unchanged code line1
--old code line2 removed in the PR
+-old code line2 removed
  unchanged code line3
 
 @@ ... @@ def func2():

pr_agent/settings/pr_reviewer_prompts.toml

@@ -16,20 +16,20 @@ The format we will use to present the PR code diff:
 
 @@ ... @@ def func1():
 __new hunk__
-11  unchanged code line0 in the PR
-12  unchanged code line1 in the PR
-13 +new code line2 added in the PR
-14  unchanged code line3 in the PR
+11  unchanged code line0
+12  unchanged code line1
+13 +new code line2 added
+14  unchanged code line3
 __old hunk__
  unchanged code line0
  unchanged code line1
--old code line2 removed in the PR
+-old code line2 removed
  unchanged code line3
 
 @@ ... @@ def func2():
 __new hunk__
  unchanged code line4
-+new code line5 removed in the PR
++new code line5 removed
  unchanged code line6
 
 ## File: 'src/file2.py'
@@ -43,7 +43,7 @@ __new hunk__
 {%- if is_ai_metadata %}
 - If available, an AI-generated summary will appear and provide a high-level overview of the file changes. Note that this summary may not be fully accurate or complete.
 {%- endif %}
-- When quoting variables or names from the code, use backticks (`) instead of single quote (').
+- When quoting variables, names or file paths from the code, use backticks (`) instead of single quote (').
 
 
 {%- if extra_instructions %}