Improve PR review summary with detailed breakdown

- Add category-based grouping of findings with descriptions
- Show severity breakdown (HIGH/MEDIUM/LOW counts)
- Provide clearer recommendations based on severity:
  - HIGH: "Action Required" - must fix before merge
  - MEDIUM: "Approved with Suggestions" - consider fixing
  - LOW only: "Approved" - minor suggestions
- Use markdown formatting for better readability

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: matej

scripts/comment-pr-findings.bun.test.js

@@ -157,8 +157,8 @@ describe('comment-pr-findings.js', () => {
 
       expect(reviewDataCaptured).toBeTruthy();
       expect(reviewDataCaptured.event).toBe('APPROVE');
-      expect(reviewDataCaptured.body).toContain('Summary: No findings were reported.');
-      expect(reviewDataCaptured.body).toContain('Assessment:');
+      expect(reviewDataCaptured.body).toContain('No issues were identified');
+      expect(reviewDataCaptured.body).toContain('Recommendation');
     });
 
     test('should process findings correctly', async () => {
@@ -231,8 +231,8 @@ describe('comment-pr-findings.js', () => {
       expect(reviewDataCaptured).toBeTruthy();
       expect(reviewDataCaptured.comments).toHaveLength(1);
       expect(reviewDataCaptured.event).toBe('REQUEST_CHANGES');
-      expect(reviewDataCaptured.body).toContain('Summary: 1 finding');
-      expect(reviewDataCaptured.body).toContain('Assessment:');
+      expect(reviewDataCaptured.body).toContain('Found **1 issue**');
+      expect(reviewDataCaptured.body).toContain('Recommendation');
     });
 
     test('should approve when findings are medium or low only', async () => {
@@ -299,8 +299,8 @@ describe('comment-pr-findings.js', () => {
 
       expect(reviewDataCaptured).toBeTruthy();
       expect(reviewDataCaptured.event).toBe('APPROVE');
-      expect(reviewDataCaptured.body).toContain('Summary: 2 findings');
-      expect(reviewDataCaptured.body).toContain('HIGH: 0');
+      expect(reviewDataCaptured.body).toContain('Found **2 issues**');
+      expect(reviewDataCaptured.body).toContain('Approved with Suggestions');
       expect(reviewDataCaptured.comments).toHaveLength(2);
     });
 
@@ -350,7 +350,7 @@ describe('comment-pr-findings.js', () => {
 
       expect(reviewDataCaptured).toBeTruthy();
       expect(reviewDataCaptured.event).toBe('REQUEST_CHANGES');
-      expect(reviewDataCaptured.body).toContain('Summary: 1 finding');
+      expect(reviewDataCaptured.body).toContain('Found **1 issue**');
       expect(reviewDataCaptured.comments).toBeUndefined();
     });
   });

scripts/comment-pr-findings.js

@@ -126,34 +126,84 @@ async function run() {
     function buildReviewSummary(findings) {
       const total = findings.length;
       const files = new Set();
+      const categories = {};
+
       for (const finding of findings) {
         const file = finding.file || finding.path;
         if (file) {
           files.add(file);
         }
+        // Group by category
+        const category = finding.category || 'other';
+        if (!categories[category]) {
+          categories[category] = [];
+        }
+        categories[category].push(finding);
       }
 
       const { high, medium, low } = countSeverities(findings);
-      let summaryLine;
+
+      // Build the summary
+      let summary = '## Code Review Summary\n\n';
 
       if (total === 0) {
-        summaryLine = 'Summary: No findings were reported.';
-      } else {
-        const fileCount = files.size;
-        const fileText = fileCount > 0 ? ` across ${fileCount} file${fileCount === 1 ? '' : 's'}` : '';
-        summaryLine = `Summary: ${total} finding${total === 1 ? '' : 's'}${fileText} (HIGH: ${high}, MEDIUM: ${medium}, LOW: ${low}).`;
+        summary += 'No issues were identified in this review.\n\n';
+        summary += '**Recommendation:** Approved - the changes look good.';
+        return summary;
+      }
+
+      // Overview line
+      const fileCount = files.size;
+      const fileText = fileCount > 0 ? ` across ${fileCount} file${fileCount === 1 ? '' : 's'}` : '';
+      summary += `Found **${total} issue${total === 1 ? '' : 's'}**${fileText}.\n\n`;
+
+      // Severity breakdown
+      summary += '### Severity Breakdown\n';
+      if (high > 0) summary += `- **HIGH:** ${high}\n`;
+      if (medium > 0) summary += `- **MEDIUM:** ${medium}\n`;
+      if (low > 0) summary += `- **LOW:** ${low}\n`;
+      summary += '\n';
+
+      // Category breakdown with descriptions
+      const categoryDescriptions = {
+        security: 'Security vulnerabilities that could be exploited',
+        correctness: 'Logic errors or bugs that may cause incorrect behavior',
+        performance: 'Inefficiencies that could impact performance',
+        reliability: 'Issues that may cause crashes or failures',
+        maintainability: 'Code quality issues affecting long-term maintenance',
+        testing: 'Missing or inadequate test coverage',
+        other: 'Other issues'
+      };
+
+      summary += '### Issues by Category\n';
+      for (const [category, categoryFindings] of Object.entries(categories)) {
+        const catHigh = categoryFindings.filter(f => normalizeSeverity(f.severity) === 'HIGH').length;
+        const catMedium = categoryFindings.filter(f => normalizeSeverity(f.severity) === 'MEDIUM').length;
+        const catLow = categoryFindings.filter(f => normalizeSeverity(f.severity) === 'LOW' || !f.severity).length;
+
+        const severityParts = [];
+        if (catHigh > 0) severityParts.push(`${catHigh} high`);
+        if (catMedium > 0) severityParts.push(`${catMedium} medium`);
+        if (catLow > 0) severityParts.push(`${catLow} low`);
+
+        const description = categoryDescriptions[category] || category;
+        summary += `- **${category.charAt(0).toUpperCase() + category.slice(1)}** (${severityParts.join(', ')}): ${description}\n`;
       }
+      summary += '\n';
 
-      let assessmentLine;
+      // Recommendation
+      summary += '### Recommendation\n';
       if (high > 0) {
-        assessmentLine = 'Assessment: High-severity issues were found that should be addressed before merge.';
-      } else if (total > 0) {
-        assessmentLine = 'Assessment: Changes look acceptable overall; consider addressing the findings.';
+        summary += `**Action Required:** ${high} high-severity issue${high === 1 ? '' : 's'} must be addressed before merging. `;
+        summary += 'Please review the inline comments and apply the suggested fixes.\n';
+      } else if (medium > 0) {
+        summary += `**Approved with Suggestions:** No blocking issues found, but ${medium} medium-severity issue${medium === 1 ? '' : 's'} should be considered. `;
+        summary += 'Review the inline comments for improvement opportunities.\n';
       } else {
-        assessmentLine = 'Assessment: Changes look good; no high-severity issues detected.';
+        summary += `**Approved:** Only minor issues found. Consider addressing the ${low} low-severity suggestion${low === 1 ? '' : 's'} when convenient.\n`;
       }
 
-      return `${summaryLine}\n${assessmentLine}`;
+      return summary;
     }
 
     const { high: highSeverityCount } = countSeverities(newFindings);