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

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
This commit is contained in:
2025-12-29 12:44:54 +00:00
parent 1d468e360e
commit 37f3eb45d0
8 changed files with 680 additions and 3 deletions

View File

@@ -217,6 +217,7 @@ Prompts are stored in `tools/ai-review/prompts/` as Markdown files:
- `base.md` - Base instructions for all reviews
- `pr_summary.md` - PR summary generation template
- `changelog.md` - Keep a Changelog format generation template
- `explain_diff.md` - Plain-language diff explanation template
- `issue_triage.md` - Issue classification template
- `issue_response.md` - Issue response template
@@ -533,6 +534,79 @@ The `@codebot changelog` command generates Keep a Changelog format entries from
- Excluded from ai-chat.yml to prevent duplicate runs
- No automatic triggering - manual command only
### Code Diff Explainer
The `@codebot explain-diff` command translates technical code changes into plain language for non-technical stakeholders.
**Key Features:**
- Plain-language explanations without jargon
- File-by-file breakdown with "what" and "why" context
- Architecture impact analysis
- Breaking change detection
- Perfect for PMs, designers, and new team members
**Implementation Details:**
1. **Command Handler** - `PRAgent._handle_explain_diff_command()`:
- Triggered by `@codebot explain-diff` in PR comments
- Fetches PR title, description, and full diff
- Loads `prompts/explain_diff.md` template
- Formats prompt with PR context
2. **LLM Analysis** - Generates plain-language JSON:
```json
{
"overview": "High-level summary in everyday language",
"key_changes": [
{
"file": "path/to/file.py",
"status": "new|modified|deleted",
"explanation": "What changed (no jargon)",
"why_it_matters": "Business/user impact"
}
],
"architecture_impact": {
"description": "System-level effects explained simply",
"new_dependencies": ["External libraries added"],
"affected_components": ["System parts impacted"]
},
"breaking_changes": ["User-facing breaking changes"],
"technical_details": { /* Stats for reference */ }
}
```
3. **Formatting** - `_format_diff_explanation()`:
- Converts JSON to readable markdown
- Uses emojis for visual categorization ( new, 📝 modified, 🗑️ deleted)
- Highlights breaking changes prominently
- Includes technical summary for developers
- Omits empty sections for clean output
4. **Prompt Engineering** - `prompts/explain_diff.md`:
- **Avoids jargon**: "API" → "connection point between systems"
- **Explains why**: Not just what changed, but why it matters
- **Uses analogies**: "Caching" → "memory system for faster loading"
- **Focus on impact**: Who is affected and how
- **Groups changes**: Combines related files into themes
- **Translates concepts**: Technical terms → everyday language
**Plain Language Rules:**
- ❌ "Refactored authentication middleware" → ✅ "Updated login system for better security"
- ❌ "Implemented Redis caching" → ✅ "Added memory to make pages load 10x faster"
- ❌ "Database migration" → ✅ "Updated how data is stored"
**Common Use Cases:**
- New team members understanding large PRs
- Non-technical reviewers (PMs, designers) reviewing features
- Documenting architectural decisions
- Learning from other developers' code
**Workflow Safety:**
- Only triggers on PR comments (not issue comments)
- Included in ai-comment-reply.yml workflow conditions
- Excluded from ai-chat.yml to prevent duplicate runs
- No automatic triggering - manual command only
### Review-Again Command Implementation
The `@codebot review-again` command allows manual re-triggering of PR reviews without new commits.
@@ -591,6 +665,7 @@ Example commands:
- `@codebot suggest` - Suggest solutions
- `@codebot summarize` - Generate PR summary or issue summary (works on both)
- `@codebot changelog` - Generate Keep a Changelog format entries (PR comments only)
- `@codebot explain-diff` - Explain code changes in plain language (PR comments only)
- `@codebot setup-labels` - Automatic label setup (built-in, not in config)
- `@codebot review-again` - Re-run PR review without new commits (PR comments only)