radar summary

The summary feature generates a concise 2-3 sentence executive summary of scan results using Claude. It highlights the most dangerous finding, explains real-world impact, and recommends what to fix first.

Plan requirement: AI summaries require Solo plan or above. Cost: ~$0.005 per scan (1 credit).

How It Works

Summaries are generated automatically when running radar scan with an ANTHROPIC_API_KEY set. The AI receives the full violation list, debt score, gate result, and category breakdown, then produces a human-readable summary.

Setup

export ANTHROPIC_API_KEY=sk-ant-api03-...

When the API key is set, every radar scan call includes an AI summary in the output. No additional flags needed.

Disabling Summaries

To skip AI analysis and summaries (for faster, cost-free scans):

radar scan src/ --no-ai

Example Summaries

Failing Scan (Blocking Violations)

The most critical issue is an unbounded query on the events table (XL, 1M+
rows) in EventService.findAll() that will cause timeouts in production. There
are also 3 missing null guards in article.service.ts that will crash with 500
errors on invalid slugs. Fix the unbounded query first — it affects every user.

Passing Scan with Warnings

5 minor warnings: 3 missing null guards in user.service.ts and 2 functions
over complexity threshold. None are blocking, but the null guards should be
fixed before they reach production — they'll crash on edge cases.

Clean Scan

No violations found. Code meets all architecture, runtime, performance, and
reliability standards.

Architecture Violations

Two direct imports from the billing domain into infrastructure bypass the
application layer, violating DDD boundaries. A circular dependency between
orders and billing modules will cause startup failures if either module grows.
Fix the circular dependency first — it blocks both modules from independent
deployment.

Runtime Risk

readFileSync in OrderHandler.create() blocks the event loop on every order
submission — at 50 req/s this will stall the entire server for 200ms per call.
The unhandled promise in PaymentService.charge() will crash the process on any
Stripe timeout. Replace readFileSync with async readFile immediately.

Output Formats

The AI summary appears in all scan output formats:

Text Format

$ radar scan src/

  🤖 AI Summary
  ──────────────
  The most critical issue is an unbounded query on the events table
  (XL, 1M+ rows) in EventService.findAll() that will cause timeouts
  in production. Fix the unbounded query first.

JSON Format

{
  "aiSummary": "The most critical issue is an unbounded query on the events table...",
  "filesScanned": 47,
  "violations": [ ... ]
}

AI Prompt Format

TECHNICAL DEBT RADAR — Scan Report

EXECUTIVE SUMMARY: The most critical issue is an unbounded query on the events
table (XL, 1M+ rows) in EventService.findAll()...

Fix the following issues in order of severity:
...

AI JSON Format

{
  "report": "TECHNICAL DEBT RADAR — Scan Report",
  "aiSummary": "The most critical issue is...",
  "instruction": "Fix the following issues in order of severity",
  "violations": [ ... ]
}

PR Comment Format

The summary appears at the top of the generated PR comment markdown, providing reviewers with immediate context.

Summary Generation Rules

The AI follows specific guidelines to produce useful summaries:

1. Lead with the most dangerous finding -- the violation most likely to cause production incidents
2. Be specific -- reference file names, table names, and variable names
3. Explain real-world impact -- not just the rule name, but what will break
4. Emphasize blocking violations -- if the gate fails, say why
5. End with a clear recommendation -- what to fix first and why
6. Keep it to 2-3 sentences -- no bullet points, no headers, plain language

Cost

Each summary generation costs approximately $0.005 in Anthropic API usage (1 credit on Solo plan). The summary uses Claude Sonnet with a 300-token response limit, keeping costs minimal even across many scans.

For a team running 100 scans per day, the daily summary cost is approximately $0.50.

Graceful Degradation

If the AI call fails (network error, rate limit, invalid key), the scan continues normally without a summary. The summary is never required for the scan to complete or for the gate to evaluate.