Claude-Code-Workflow/.claude/skills/code-reviewer/phases/04-report-generation.md

Phase 4: Report Generation

Objective

Consolidate security and best practices findings into a comprehensive, actionable code review report.

Input

• Security Findings: .code-review/security-findings.json
• Best Practices Findings: .code-review/best-practices-findings.json
• File Inventory: .code-review/inventory.json

Process

Step 1: Load All Findings

const securityFindings = JSON.parse(
  await Read({ file_path: '.code-review/security-findings.json' })
);
const bestPracticesFindings = JSON.parse(
  await Read({ file_path: '.code-review/best-practices-findings.json' })
);
const inventory = JSON.parse(
  await Read({ file_path: '.code-review/inventory.json' })
);

Step 2: Aggregate Statistics

const stats = {
  total_files_reviewed: inventory.total_files,
  total_findings: securityFindings.total_findings + bestPracticesFindings.total_findings,
  by_severity: {
    critical: securityFindings.by_severity.critical,
    high: securityFindings.by_severity.high + bestPracticesFindings.by_severity.high,
    medium: securityFindings.by_severity.medium + bestPracticesFindings.by_severity.medium,
    low: securityFindings.by_severity.low + bestPracticesFindings.by_severity.low,
  },
  by_category: {
    security: securityFindings.total_findings,
    code_quality: bestPracticesFindings.by_category.code_quality,
    performance: bestPracticesFindings.by_category.performance,
    maintainability: bestPracticesFindings.by_category.maintainability,
  }
};

Step 3: Generate Comprehensive Report

# Comprehensive Code Review Report

**Generated**: {timestamp}
**Scope**: {scope}
**Files Reviewed**: {total_files}
**Total Findings**: {total_findings}

## Executive Summary

{Provide high-level overview of code health}

### Risk Assessment

{Calculate risk score based on findings}

### Compliance Status

{Map findings to compliance requirements}

## Detailed Findings

{Merge and organize security + best practices findings}

## Action Plan

{Prioritized list of fixes with effort estimates}

## Appendix

{Technical details, references, configuration}

Step 4: Generate Fix Tracking Checklist

Create actionable checklist for developers:

# Code Review Fix Checklist

## Critical Issues (Fix Immediately)

- [ ] [SEC-001] SQL Injection in src/auth/user-service.ts:145
- [ ] [SEC-002] Hardcoded JWT Secret in src/auth/jwt.ts:23
- [ ] [SEC-003] XSS Vulnerability in src/api/comments.ts:89

## High Priority Issues (Fix This Week)

- [ ] [SEC-004] Missing Authorization Check in src/api/admin.ts:34
- [ ] [BP-001] N+1 Query Pattern in src/api/orders.ts:45
...

Step 5: Generate Metrics Dashboard

## Code Health Metrics

### Security Score: 68/100
- Critical Issues: 3 (-30 points)
- High Issues: 8 (-2 points each)

### Code Quality Score: 75/100
- High Complexity Functions: 2
- Code Duplication: 5%
- Dead Code: 3 instances

### Performance Score: 82/100
- N+1 Queries: 3
- Inefficient Algorithms: 2

### Maintainability Score: 70/100
- Documentation Coverage: 65%
- Test Coverage: 72%
- Missing Tests: 5 files

Output

Main Report

Save to .code-review/REPORT.md:

• Executive summary
• Detailed findings (security + best practices)
• Action plan with priorities
• Metrics and scores
• References and compliance mapping

Fix Checklist

Save to .code-review/FIX-CHECKLIST.md:

• Organized by severity
• Checkboxes for tracking
• File:line references
• Effort estimates

JSON Summary

Save to .code-review/summary.json:

{
  "report_date": "2024-01-15T12:00:00Z",
  "scope": "src/**/*",
  "statistics": {
    "total_files": 247,
    "total_findings": 69,
    "by_severity": { "critical": 3, "high": 13, "medium": 30, "low": 23 },
    "by_category": {
      "security": 24,
      "code_quality": 18,
      "performance": 12,
      "maintainability": 15
    }
  },
  "scores": {
    "security": 68,
    "code_quality": 75,
    "performance": 82,
    "maintainability": 70,
    "overall": 74
  },
  "risk_level": "MEDIUM",
  "action_required": true
}

Report Template

Full report includes:

1. Executive Summary

   • Overall code health
   • Risk assessment
   • Key recommendations

2. Security Findings (from Phase 2)

   • Critical/High/Medium/Low
   • OWASP/CWE mappings
   • Fix recommendations with code examples

3. Best Practices Findings (from Phase 3)

   • Code quality issues
   • Performance concerns
   • Maintainability gaps

4. Metrics Dashboard

   • Security score
   • Code quality score
   • Performance score
   • Maintainability score

5. Action Plan

   • Immediate actions (critical)
   • Short-term (1 week)
   • Medium-term (1 month)
   • Long-term (3 months)

6. Compliance Impact

   • PCI DSS findings
   • HIPAA findings
   • GDPR findings
   • SOC 2 findings

7. Appendix

   • Full findings list
   • Configuration used
   • Tools and versions
   • References

State Management

{
  "phase": "04-report-generation",
  "status": "completed",
  "timestamp": "2024-01-15T12:00:00Z",
  "input": {
    "security_findings": ".code-review/security-findings.json",
    "best_practices_findings": ".code-review/best-practices-findings.json"
  },
  "output": {
    "report": ".code-review/REPORT.md",
    "checklist": ".code-review/FIX-CHECKLIST.md",
    "summary": ".code-review/summary.json"
  }
}

Agent Instructions

You are in Phase 4 (FINAL) of the Code Review workflow. Generate comprehensive report.

**Instructions**:
1. Load security findings from Phase 2
2. Load best practices findings from Phase 3
3. Aggregate statistics and calculate scores
4. Generate comprehensive markdown report
5. Create fix tracking checklist
6. Generate JSON summary
7. Inform user of completion and output locations

**Tools Available**:
- Read (load findings)
- Write (save reports)

**Output Requirements**:
- REPORT.md (comprehensive markdown report)
- FIX-CHECKLIST.md (actionable checklist)
- summary.json (machine-readable summary)
- All files in .code-review/ directory

Validation

• ✅ All findings consolidated
• ✅ Scores calculated
• ✅ Action plan generated
• ✅ Reports saved to .code-review/
• ✅ User notified of completion

Completion

Code review complete! Outputs available in .code-review/ directory.