8000
Improve/describe tool documentation and make add_diagram feature opt-in by default by ssunbear · Pull Request #1824 · qodo-ai/pr-agent · GitHub
More Web Proxy on the site http://driver.im/
You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This PR addresses qodo-ai/pr-agent#1754.
It improves the /describe tool documentation and modifies the add_diagram behavior to be opt-in (disabled by default), aligning with feature-based PR conventions and ensuring non-disruptive integration into existing workflows.
Changes
Reordered the documentation for the /describe tool:
Moved the core functionality description to the top for better clarity and readability.
Placed optional features and flags (e.g., add_diagram) below the main description.
Changed the default value of the add_diagram option to false in configuration.toml, requiring explicit activation.
Cleaned up string quoting style for consistency across the codebase.
Design Considerations
Why the documentation was reordered
The main purpose of the /describe tool should be immediately clear to users. Placing the primary functionality explanation at the top helps users understand its intent before diving into optional features.
Why add_diagram defaults to false
Since this PR introduces a new feature, we intentionally disabled it by default to prevent unexpected side effects in existing workflows. This aligns with cautious rollout practices and avoids breaking changes for existing users.
We believe users should first be informed about new features through documentation and enable them explicitly. Once the feature matures and gains confidence through maintainer feedback, its default value can be reconsidered.
PR Type
Enhancement, Documentation
Description
Add add_diagram config flag for sequence diagrams
Read add_diagram in pr_agent/tools/pr_description.py
Document Mermaid diagram support in describe.md
Update prompts to conditionally include diagram output
Changes diagram
sequenceDiagram
participant U as User
participant P as PRAgent
U->>P: /describe command
P->>P: load config (`add_diagram`)
alt add_diagram = true
P->>P: append Mermaid sequence diagram
else
P->>U: return text summary only
end
• Add a Sequence Diagram feature to PR summaries
• Generate diagrams in Mermaid format based on detected function calls
• Make it available as an optional section in PR descriptions
Requires further human verification:
• Help reviewers visualize the flow of changes between components
• Reduce cognitive load for reviewers by visualizing interactions
• Support complex backend changes, asynchronous logic, and microservice architectures
The diagram implementation relies on the LLM to generate the sequence diagram without specific guidance on how to analyze the code to identify actual function calls and component interactions. This may result in generic or inaccurate diagrams that don't reflect the actual code changes.
diagram: |sequenceDiagramparticipant A as ComponentAparticipant B as ComponentBA->>B: functionCall()B-->>A: response{%- endif %}
✅ Missing schema fieldSuggestion Impact:The commit implemented a similar solution by adding a 'changes_diagram' field to the PRDescription model, but with a different approach. Instead of using the conditional 'add_diagram', it uses 'enable_pr_diagram' and renamed the field to 'changes_diagram' rather than 'diagram'.
code diff:
+{%- endif %}+{%- if enable_pr_diagram %}+ changes_diagram: str = Field(description="a horizontal diagram that represents the main PR changes, in the format of a mermaid flowchart. The diagram should be concise and easy to read. Leave empty if no diagram is relevant.")
{%- endif %}
The prompt template adds diagram instructions but the output schema doesn't include a field for the diagram. Add a dedicated diagram field to the PRDescription model to properly capture the Mermaid diagram when add_diagram is true.
description: str = Field(description="summarize the PR changes in up to four bullet points, each up to 8 words. For large PRs, add sub-bullets if needed. Order bullets by importance, with each bullet highlighting a key change group. {% if add_diagram %} Also, generate a Mermaid sequence diagram that focuses on the main function call flow between classes or components. {% endif %}")
+{% if add_diagram %}diagram: str = Field(description="a Mermaid sequence diagram that visualizes the main function call flow between classes or components"){% endif %}
[Suggestion processed]
Suggestion importance[1-10]: 8
__
Why: The suggestion correctly identifies that while the prompt asks for a Mermaid diagram when add_diagram is true, the output schema lacks a corresponding diagram field. Adding this field is important for capturing the diagram output, ensuring consistency between the prompt and the expected model output.
Medium
Update
Author self-review: I have reviewed the PR code suggestions, and addressed the relevant ones.
@mrT23
Thank you for your response!
Out team made the changes as you suggested, but if it's not what you intended, please let me know and I'll roll it back immediately!
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User description
Summary
This PR addresses qodo-ai/pr-agent#1754.
It improves the
/describetool documentation and modifies theadd_diagrambehavior to be opt-in (disabled by default), aligning with feature-based PR conventions and ensuring non-disruptive integration into existing workflows.Changes
/describetool:add_diagram) below the main description.add_diagramoption tofalseinconfiguration.toml, requiring explicit activation.Design Considerations
Why the documentation was reordered
The main purpose of the
/describetool should be immediately clear to users. Placing the primary functionality explanation at the top helps users understand its intent before diving into optional features.Why
add_diagramdefaults to falseSince this PR introduces a new feature, we intentionally disabled it by default to prevent unexpected side effects in existing workflows. This aligns with cautious rollout practices and avoids breaking changes for existing users.
We believe users should first be informed about new features through documentation and enable them explicitly. Once the feature matures and gains confidence through maintainer feedback, its default value can be reconsidered.
Enhancement, Documentation
Description
Add
add_diagramconfig flag for sequence diagramsRead
add_diagraminpr_agent/tools/pr_description.pyDocument Mermaid diagram support in
describe.mdUpdate prompts to conditionally include diagram output
Changes diagram
sequenceDiagram participant U as User participant P as PRAgent U->>P: /describe command P->>P: load config (`add_diagram`) alt add_diagram = true P->>P: append Mermaid sequence diagram else P->>U: return text summary only endChanges walkthrough 📝
pr_description.py
Read `add_diagram` flag in PR descriptionpr_agent/tools/pr_description.py
add_diagramfrom settings config"add_diagram"key to prompt argumentsconfiguration.toml
Add `add_diagram` default configurationpr_agent/settings/configuration.toml
add_diagram = falsedefault[pr_description]sectiondescribe.md
Document Mermaid sequence diagram optiondocs/docs/tools/describe.md
add_diagrampr_description_prompts.toml
Enhance prompts for optional sequence diagrampr_agent/settings/pr_description_prompts.toml
sequenceDiagramtemplate block