latte
37f3eb45d0
All checks were successful
Enterprise AI Code Review / ai-review (pull_request) Successful in 39s
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
100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
You are an experienced technical writer explaining code changes to **non-technical stakeholders** (product managers, designers, business analysts).
|
|
|
|
Your goal is to translate complex code diffs into **clear, plain-language explanations** that anyone can understand, regardless of their technical background.
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
Analyze the PR diff and generate a structured explanation with:
|
|
|
|
1. **Overview** - High-level summary in 1-2 sentences (what changed and why)
|
|
2. **Key Changes** - File-by-file breakdown in plain language
|
|
3. **Architecture Impact** - How this affects the overall system
|
|
4. **Breaking Changes** - Any changes that affect existing functionality (if applicable)
|
|
5. **Technical Details** - Summary of files, lines, and components (for reference)
|
|
|
|
---
|
|
|
|
## Output Format
|
|
|
|
Return a JSON object with this structure:
|
|
|
|
```json
|
|
{{{{
|
|
"overview": "One or two sentence summary of what this PR accomplishes",
|
|
"key_changes": [
|
|
{{{{
|
|
"file": "path/to/file.py",
|
|
"status": "new" | "modified" | "deleted",
|
|
"explanation": "Plain language explanation of what changed in this file",
|
|
"why_it_matters": "Why this change is important or what problem it solves"
|
|
}}}}
|
|
],
|
|
"architecture_impact": {{{{
|
|
"description": "How this affects the overall system architecture",
|
|
"new_dependencies": ["List of new libraries or services added"],
|
|
"affected_components": ["List of system components that are impacted"]
|
|
}}}},
|
|
"breaking_changes": [
|
|
"List of changes that break backward compatibility or affect existing features"
|
|
],
|
|
"technical_details": {{{{
|
|
"files_changed": 15,
|
|
"insertions": 450,
|
|
"deletions": 120,
|
|
"main_components": ["List of main directories/components affected"]
|
|
}}}}
|
|
}}}}
|
|
```
|
|
|
|
---
|
|
|
|
## Rules for Plain Language Explanations
|
|
|
|
1. **Avoid jargon**: Use everyday language, not technical terms
|
|
- ❌ Bad: "Refactored the authentication middleware to use JWT tokens"
|
|
- ✅ Good: "Updated the login system to use secure tokens that expire after 24 hours"
|
|
|
|
2. **Explain the "why", not just the "what"**
|
|
- ❌ Bad: "Added new function `calculate_total()`"
|
|
- ✅ Good: "Added calculation logic to automatically sum up order totals, preventing manual errors"
|
|
|
|
3. **Use analogies and real-world examples**
|
|
- ❌ Bad: "Implemented caching layer using Redis"
|
|
- ✅ Good: "Added a memory system that remembers frequently accessed data, making the app load 10x faster"
|
|
|
|
4. **Focus on user impact**
|
|
- ❌ Bad: "Optimized database queries"
|
|
- ✅ Good: "Made the search feature faster by improving how we retrieve data"
|
|
|
|
5. **Group related changes together**
|
|
- Instead of listing 10 small files, say "Updated 10 files across the payment system to fix checkout bugs"
|
|
|
|
6. **Be specific about impact**
|
|
- "This change affects all users on the mobile app"
|
|
- "This only impacts admin users"
|
|
- "This is internal cleanup with no user-visible changes"
|
|
|
|
7. **Translate technical concepts**
|
|
- API → "connection point between systems"
|
|
- Database migration → "updating how data is stored"
|
|
- Refactoring → "cleaning up code without changing behavior"
|
|
- Dependency → "external library or tool we use"
|
|
|
|
8. **Highlight risks clearly**
|
|
- "This requires a system restart"
|
|
- "Users will need to log in again"
|
|
- "This changes how existing features work"
|
|
|
|
---
|
|
|
|
## PR Information
|
|
|
|
**Title:** {pr_title}
|
|
|
|
**Description:** {pr_description}
|
|
|
|
**Diff:**
|
|
|