Hiddenden/openrabbit
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

feat: Add @codebot explain-diff command for plain-language PR explanations #26

Merged
Latte merged 1 commits from feature/code-diff-explainer into dev 2025-12-29 12:53:33 +00:00
Conversation 5 Commits 1 Files Changed 8 +680 -3
Latte commented 2025-12-29 12:47:49 +00:00
Owner
Copy Link

Implements code diff explainer that translates technical changes into
plain language for non-technical stakeholders (PMs, designers, new team members).

Features:

  • Plain-language explanations without jargon
  • File-by-file breakdown with 'what' and 'why' context
  • Architecture impact analysis
  • Breaking change detection
  • Perfect for onboarding and cross-functional reviews

Implementation:

  • Added explain_diff.md prompt template with plain-language guidelines
  • Implemented _handle_explain_diff_command() in PRAgent
  • Added _format_diff_explanation() for readable markdown
  • Updated PRAgent.can_handle() to route explain-diff commands
  • Added 'explain-diff' to config.yml commands list

Workflow Safety (prevents duplicate runs):

  • Added '@codebot explain-diff' to ai-comment-reply.yml conditions
  • Excluded from ai-chat.yml to prevent duplication
  • Only triggers on PR comments (not issues)
  • Manual command only (no automatic triggering)

Testing:

  • 9 comprehensive tests in TestDiffExplanation class
  • Tests command detection, formatting, plain-language output
  • Verifies prompt formatting and empty section handling

Documentation:

  • Updated README.md with explain-diff command and examples
  • Added detailed implementation guide in CLAUDE.md
  • Included plain-language rules and use cases

Related: Milestone 2 high-priority feature - code diff explainer

Implements code diff explainer that translates technical changes into plain language for non-technical stakeholders (PMs, designers, new team members). Features: - Plain-language explanations without jargon - File-by-file breakdown with 'what' and 'why' context - Architecture impact analysis - Breaking change detection - Perfect for onboarding and cross-functional reviews Implementation: - Added explain_diff.md prompt template with plain-language guidelines - Implemented _handle_explain_diff_command() in PRAgent - Added _format_diff_explanation() for readable markdown - Updated PRAgent.can_handle() to route explain-diff commands - Added 'explain-diff' to config.yml commands list Workflow Safety (prevents duplicate runs): - Added '@codebot explain-diff' to ai-comment-reply.yml conditions - Excluded from ai-chat.yml to prevent duplication - Only triggers on PR comments (not issues) - Manual command only (no automatic triggering) Testing: - 9 comprehensive tests in TestDiffExplanation class - Tests command detection, formatting, plain-language output - Verifies prompt formatting and empty section handling Documentation: - Updated README.md with explain-diff command and examples - Added detailed implementation guide in CLAUDE.md - Included plain-language rules and use cases Related: Milestone 2 high-priority feature - code diff explainer
Latte added 1 commit 2025-12-29 12:47:49 +00:00
feat: Add @codebot explain-diff command for plain-language PR explanations
All checks were successful
Enterprise AI Code Review / ai-review (pull_request) Successful in 39s
Details
37f3eb45d0 
Implements code diff explainer that translates technical changes into
plain language for non-technical stakeholders (PMs, designers, new team members).

Features:
- Plain-language explanations without jargon
- File-by-file breakdown with 'what' and 'why' context
- Architecture impact analysis
- Breaking change detection
- Perfect for onboarding and cross-functional reviews

Implementation:
- Added explain_diff.md prompt template with plain-language guidelines
- Implemented _handle_explain_diff_command() in PRAgent
- Added _format_diff_explanation() for readable markdown
- Updated PRAgent.can_handle() to route explain-diff commands
- Added 'explain-diff' to config.yml commands list

Workflow Safety (prevents duplicate runs):
- Added '@codebot explain-diff' to ai-comment-reply.yml conditions
- Excluded from ai-chat.yml to prevent duplication
- Only triggers on PR comments (not issues)
- Manual command only (no automatic triggering)

Testing:
- 9 comprehensive tests in TestDiffExplanation class
- Tests command detection, formatting, plain-language output
- Verifies prompt formatting and empty section handling

Documentation:
- Updated README.md with explain-diff command and examples
- Added detailed implementation guide in CLAUDE.md
- Included plain-language rules and use cases

Related: Milestone 2 high-priority feature - code diff explainer
Bartender commented 2025-12-29 12:48:10 +00:00
Owner
Copy Link

📋 Pull Request Summary

This PR introduces a new @codebot explain-diff command that provides plain-language explanations of code changes in pull requests, aimed at non-technical stakeholders. It includes the implementation of the command handler, prompt template, workflow integration, documentation updates, and comprehensive tests to ensure functionality and usability.

Type: ✨ Feature

Changes

✅ Added:

  • New @codebot explain-diff command for plain-language diff explanations
  • Prompt template explain_diff.md for generating structured explanations
  • Handler method _handle_explain_diff_command in pr_agent.py
  • Markdown formatting method _format_diff_explanation for output
  • Workflow integration in ai-comment-reply.yml and exclusion in ai-chat.yml
  • Documentation updates in README.md and CLAUDE.md describing the new command
  • Extensive tests in test_ai_review.py covering prompt, command handling, formatting, and config

📝 Modified:

  • Added explain-diff command to config.yml interaction commands
  • Updated workflows to route explain-diff commands correctly
  • Enhanced PRAgent.can_handle to recognize explain-diff command
  • Updated README and CLAUDE documentation to include explain-diff command

Files Affected

  • 📝 tools/ai-review/agents/pr_agent.py - Added handler and formatter for the new @codebot explain-diff command to generate plain-language explanations of PR diffs
  • ➕ tools/ai-review/prompts/explain_diff.md - New prompt template defining the structure and rules for generating plain-language diff explanations
  • 📝 tools/ai-review/config.yml - Added explain-diff to the list of recognized interaction commands
  • 📝 .gitea/workflows/ai-comment-reply.yml - Updated workflow to trigger on @codebot explain-diff command in PR comments
  • 📝 .gitea/workflows/ai-chat.yml - Excluded @codebot explain-diff from ai-chat workflow to prevent duplicate runs
  • 📝 README.md - Added documentation and usage instructions for the new @codebot explain-diff command
  • 📝 CLAUDE.md - Extensive documentation on the purpose, implementation, usage, and examples of the @codebot explain-diff command
  • 📝 tests/test_ai_review.py - Added comprehensive tests for the new diff explanation feature, including prompt existence, formatting, command handling, and config validation

Impact

🟡 Scope: Medium
This feature enhances the AI review system by enabling non-technical stakeholders to understand code changes easily, improving cross-team communication and onboarding. It introduces a new command with minimal risk to existing functionality, integrated cleanly into workflows and well-covered by tests.

## 📋 Pull Request Summary This PR introduces a new `@codebot explain-diff` command that provides plain-language explanations of code changes in pull requests, aimed at non-technical stakeholders. It includes the implementation of the command handler, prompt template, workflow integration, documentation updates, and comprehensive tests to ensure functionality and usability. **Type:** ✨ Feature ## Changes **✅ Added:** - New `@codebot explain-diff` command for plain-language diff explanations - Prompt template `explain_diff.md` for generating structured explanations - Handler method `_handle_explain_diff_command` in `pr_agent.py` - Markdown formatting method `_format_diff_explanation` for output - Workflow integration in `ai-comment-reply.yml` and exclusion in `ai-chat.yml` - Documentation updates in `README.md` and `CLAUDE.md` describing the new command - Extensive tests in `test_ai_review.py` covering prompt, command handling, formatting, and config **📝 Modified:** - Added `explain-diff` command to config.yml interaction commands - Updated workflows to route `explain-diff` commands correctly - Enhanced `PRAgent.can_handle` to recognize `explain-diff` command - Updated README and CLAUDE documentation to include `explain-diff` command ## Files Affected - 📝 `tools/ai-review/agents/pr_agent.py` - Added handler and formatter for the new `@codebot explain-diff` command to generate plain-language explanations of PR diffs - ➕ `tools/ai-review/prompts/explain_diff.md` - New prompt template defining the structure and rules for generating plain-language diff explanations - 📝 `tools/ai-review/config.yml` - Added `explain-diff` to the list of recognized interaction commands - 📝 `.gitea/workflows/ai-comment-reply.yml` - Updated workflow to trigger on `@codebot explain-diff` command in PR comments - 📝 `.gitea/workflows/ai-chat.yml` - Excluded `@codebot explain-diff` from ai-chat workflow to prevent duplicate runs - 📝 `README.md` - Added documentation and usage instructions for the new `@codebot explain-diff` command - 📝 `CLAUDE.md` - Extensive documentation on the purpose, implementation, usage, and examples of the `@codebot explain-diff` command - 📝 `tests/test_ai_review.py` - Added comprehensive tests for the new diff explanation feature, including prompt existence, formatting, command handling, and config validation ## Impact 🟡 **Scope:** Medium This feature enhances the AI review system by enabling non-technical stakeholders to understand code changes easily, improving cross-team communication and onboarding. It introduces a new command with minimal risk to existing functionality, integrated cleanly into workflows and well-covered by tests.
Bartender reviewed 2025-12-29 12:48:25 +00:00
Bartender left a comment
Owner
Copy Link

AI Code Review - Inline Comments

AI Code Review - Inline Comments
tests/test_ai_review.py
Bartender commented 2025-12-29 12:48:25 +00:00
Owner
Copy Link

[LOW] Testing

The new TestDiffExplanation class provides good coverage for the new explain-diff command, including prompt existence, formatting, command handling, and output formatting.

Recommendation: Consider adding tests for error scenarios such as empty diffs, malformed LLM responses, and large PRs to ensure robust error handling.

**[LOW] Testing** The new TestDiffExplanation class provides good coverage for the new explain-diff command, including prompt existence, formatting, command handling, and output formatting. **Recommendation:** Consider adding tests for error scenarios such as empty diffs, malformed LLM responses, and large PRs to ensure robust error handling.
tools/ai-review/agents/pr_agent.py
Bartender commented 2025-12-29 12:48:25 +00:00
Owner
Copy Link

[LOW] Maintainability

The _handle_explain_diff_command method is quite large and handles multiple responsibilities including fetching PR data, loading prompts, calling the LLM, formatting output, and posting comments.

Recommendation: Consider refactoring _handle_explain_diff_command into smaller helper methods to improve readability and maintainability, e.g., separate methods for fetching PR data, generating prompt, calling LLM, and posting results.

**[LOW] Maintainability** The _handle_explain_diff_command method is quite large and handles multiple responsibilities including fetching PR data, loading prompts, calling the LLM, formatting output, and posting comments. **Recommendation:** Consider refactoring _handle_explain_diff_command into smaller helper methods to improve readability and maintainability, e.g., separate methods for fetching PR data, generating prompt, calling LLM, and posting results.
Bartender commented 2025-12-29 12:48:25 +00:00
Owner
Copy Link

[LOW] Readability

The _format_diff_explanation method uses multiple nested if checks and appends lines conditionally, which could be simplified for clarity.

Recommendation: Add inline comments explaining each section and consider extracting repeated patterns (e.g., listing items) into helper functions to improve readability.

**[LOW] Readability** The _format_diff_explanation method uses multiple nested if checks and appends lines conditionally, which could be simplified for clarity. **Recommendation:** Add inline comments explaining each section and consider extracting repeated patterns (e.g., listing items) into helper functions to improve readability.
Bartender commented 2025-12-29 12:48:25 +00:00
Owner
Copy Link

[LOW] Correctness

The method _handle_explain_diff_command assumes the LLM returns valid JSON matching the expected schema but does not validate or handle malformed JSON or missing keys explicitly.

Recommendation: Add validation of the LLM JSON response to handle unexpected or malformed data gracefully, with fallback messages or error logging.

**[LOW] Correctness** The method _handle_explain_diff_command assumes the LLM returns valid JSON matching the expected schema but does not validate or handle malformed JSON or missing keys explicitly. **Recommendation:** Add validation of the LLM JSON response to handle unexpected or malformed data gracefully, with fallback messages or error logging.
tools/ai-review/prompts/explain_diff.md
Bartender commented 2025-12-29 12:48:25 +00:00
Owner
Copy Link

[LOW] Readability

The prompt template is comprehensive and well-written but could benefit from explicit instructions on maximum length or complexity to avoid overly verbose LLM responses.

Recommendation: Add guidance in the prompt to keep explanations concise and focused, e.g., limit overview to 2 sentences and key changes to brief bullet points.

**[LOW] Readability** The prompt template is comprehensive and well-written but could benefit from explicit instructions on maximum length or complexity to avoid overly verbose LLM responses. **Recommendation:** Add guidance in the prompt to keep explanations concise and focused, e.g., limit overview to 2 sentences and key changes to brief bullet points.
Bartender commented 2025-12-29 12:48:25 +00:00
Owner
Copy Link

AI Code Review

This PR adds a new '@codebot explain-diff' command to the AI review system, enabling plain-language explanations of PR diffs for non-technical stakeholders. The implementation includes workflow updates, prompt templates, command handling in the PR agent, markdown formatting of explanations, and comprehensive tests. The changes are well-integrated, maintainable, and include appropriate error handling and documentation.

Summary

Severity Count
HIGH 0
MEDIUM 0
LOW 5

Review Findings

  • [LOW] tools/ai-review/agents/pr_agent.py:1211 - The _handle_explain_diff_command method is quite large and handles multiple responsibilities including fetching PR data, loading prompts, calling the LLM, formatting output, and posting comments.
  • [LOW] tools/ai-review/agents/pr_agent.py:1247 - The _format_diff_explanation method uses multiple nested if checks and appends lines conditionally, which could be simplified for clarity.
  • [LOW] tools/ai-review/agents/pr_agent.py:1211 - The method _handle_explain_diff_command assumes the LLM returns valid JSON matching the expected schema but does not validate or handle malformed JSON or missing keys explicitly.
  • [LOW] tools/ai-review/prompts/explain_diff.md:1 - The prompt template is comprehensive and well-written but could benefit from explicit instructions on maximum length or complexity to avoid overly verbose LLM responses.
  • [LOW] tests/test_ai_review.py:1052 - The new TestDiffExplanation class provides good coverage for the new explain-diff command, including prompt existence, formatting, command handling, and output formatting.

Overall Severity: LOW
AI Recommendation: Approve

<!-- AI_PR_REVIEW --> ## AI Code Review This PR adds a new '@codebot explain-diff' command to the AI review system, enabling plain-language explanations of PR diffs for non-technical stakeholders. The implementation includes workflow updates, prompt templates, command handling in the PR agent, markdown formatting of explanations, and comprehensive tests. The changes are well-integrated, maintainable, and include appropriate error handling and documentation. ### Summary | Severity | Count | |----------|-------| | HIGH | 0 | | MEDIUM | 0 | | LOW | 5 | ### Review Findings - **[LOW]** `tools/ai-review/agents/pr_agent.py:1211` - The _handle_explain_diff_command method is quite large and handles multiple responsibilities including fetching PR data, loading prompts, calling the LLM, formatting output, and posting comments. - **[LOW]** `tools/ai-review/agents/pr_agent.py:1247` - The _format_diff_explanation method uses multiple nested if checks and appends lines conditionally, which could be simplified for clarity. - **[LOW]** `tools/ai-review/agents/pr_agent.py:1211` - The method _handle_explain_diff_command assumes the LLM returns valid JSON matching the expected schema but does not validate or handle malformed JSON or missing keys explicitly. - **[LOW]** `tools/ai-review/prompts/explain_diff.md:1` - The prompt template is comprehensive and well-written but could benefit from explicit instructions on maximum length or complexity to avoid overly verbose LLM responses. - **[LOW]** `tests/test_ai_review.py:1052` - The new TestDiffExplanation class provides good coverage for the new explain-diff command, including prompt existence, formatting, command handling, and output formatting. --- **Overall Severity:** `LOW` **AI Recommendation:** Approve
Bartender commented 2025-12-29 12:48:39 +00:00
Owner
Copy Link

@None

Explanation:
There is no content provided in the title or body of the issue. Without any information, it is not possible to determine what the user is asking for or reporting. Please provide the issue details to enable analysis.

@None **Explanation:** There is no content provided in the title or body of the issue. Without any information, it is not possible to determine what the user is asking for or reporting. Please provide the issue details to enable analysis.
Bartender commented 2025-12-29 12:48:52 +00:00
Owner
Copy Link

@None

Explanation:
There is no content provided in the title or body to analyze. Please provide the issue details so I can assist you effectively.

@None **Explanation:** There is no content provided in the title or body to analyze. Please provide the issue details so I can assist you effectively.
Latte merged commit c712fe670b into dev 2025-12-29 12:53:32 +00:00
Latte deleted branch feature/code-diff-explainer 2025-12-29 12:53:33 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Bartender
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Question
Further information is requested
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status/Ai Approved
AI review approved this PR
 Status/Ai Changes Required
AI review found issues requiring changes
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Bartender Latte
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Hiddenden/openrabbit#26
Delete Branch "feature/code-diff-explainer"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?