Weekly Risk Briefing

Overview

Engineering leaders typically have limited bandwidth to review individual PR risk scores, coverage reports, and incident logs each week. Important risk signals go unnoticed until they surface as incidents. By then, the cost of mitigation is higher and the timeline to resolution is longer.

The Weekly Risk Briefing solves this by aggregating the most significant risk signals from the past seven days — high-risk PRs, coverage declines, new incidents, and reviewer expertise gaps — and asking Claude to synthesize them into a concise, plain-English narrative. The briefing surfaces what is trending, what warrants attention this week, and concrete suggestions for where to focus.

Briefings are emailed to all ADMIN users in your organization every Monday at 8 AM UTC and are also accessible on a dedicated dashboard at /risk-briefing.

What the briefing contains

Each briefing is organized into four sections:

1. High-risk pull requests

All PRs merged in the past 7 days with a deploy risk score above 70. For each PR, the briefing notes:

• The PR title, repository, and author
• The risk score and the top 2–3 contributing signals (e.g., "schema migration + low patch coverage")
• Whether the PR was reviewed by the required CODEOWNERS

This section highlights PRs that were merged despite elevated risk — useful both for immediate follow-up (are those deploys stable?) and for process reflection (are teams consistently bypassing risk warnings?).

2. Coverage declines

Repositories where test coverage dropped by 2 percentage points or more in the past 7 days. For each:

• Repository name and the coverage delta (e.g., payments-service: 84.2% → 79.1%)
• Whether the repository has a known coverage vs incident correlation score (if strong positive, the briefing flags it as higher priority)

3. Recent incidents

All incidents opened in the past 7 days, grouped by severity. For P1/P2 incidents, the briefing includes the incident title, affected service, duration (MTTR), and — if a PR Autopsy was run — a reference to the most likely culprit PR.

4. Reviewer expertise gaps

Engineers who were the sole approver on one or more high-risk PRs in the past 7 days but have low familiarity scores for the changed files (based on the Reviewer Familiarity signal). This section highlights review coverage patterns that may need process adjustment — for example, teams where reviews are being approved by engineers without context in the changed area.

How the AI narrative is generated

After collecting the four data sections, Koalr sends a structured prompt to Claude (using the fast inference model) with the aggregated data. The prompt instructs Claude to:

• Identify the 2–3 most important risk themes from the week
• Write in plain English suitable for an engineering director or VP — no jargon, no raw numbers dumps
• Provide concrete, actionable suggestions (not generic advice)
• Flag anything that warrants urgent attention before the next briefing

The result is stored as an AiInsight record with type weekly_risk_narrative and is then included in the email and dashboard.

Claude does not receive any source code or PR diffs. The input is limited to PR titles, file paths, risk signal names, coverage percentages, incident titles, and reviewer GitHub logins. See Privacy note below.

Delivery

Email

Briefings are emailed every Monday at 8 AM UTC to all users with the ADMIN role in your organization. The email includes:

• A severity badge for the week (see Severity badges below)
• The full AI narrative
• A summary table of high-risk PRs
• A direct link to the briefing on the dashboard

To change which users receive the weekly email, adjust their roles in Settings → Team & Members.

Dashboard

The /risk-briefing dashboard shows the last 8 briefings in reverse chronological order. Each briefing displays:

• The generation date and severity badge
• The full AI narrative
• Expandable sections for each of the four data categories with the underlying data

This provides a rolling 8-week history of risk trends — useful for identifying systemic patterns (e.g., the same repository appearing in coverage declines week after week).

Severity badge system

Each briefing is automatically classified with a severity badge based on the data collected:

Badge	Criteria
Critical	Any P1 incident in the past 7 days, OR 3 or more HIGH-risk PRs merged (score ≥ 80), OR a coverage decline of ≥ 5pp in a repository with strong incident correlation
Warning	Any P2 incident, OR 1–2 HIGH-risk PRs (score ≥ 70), OR a coverage decline of 2–4.9pp
Info	No incidents, no HIGH-risk PRs, no significant coverage declines — routine summary week

The severity badge appears in the email subject line and as a colored indicator on the dashboard card.

On-demand generation

ADMIN users can trigger an immediate briefing at any time rather than waiting for the Monday schedule:

1. Navigate to /risk-briefing.
2. Click Generate Now in the top-right corner.
3. Koalr collects data for the past 7 days and generates a new briefing within 15–30 seconds.

On-demand briefings are stored alongside the scheduled briefings in the dashboard history. They do not replace the next scheduled Monday briefing.

Enabling the feature

The Weekly Risk Briefing is controlled by the proactive_insights feature flag. To enable it:

1. Go to Settings → AI Features.
2. Toggle Weekly Risk Briefing to enabled.
3. Click Save.

The feature flag is off by default for new organizations. Once enabled, the first briefing will be generated on the next Monday at 8 AM UTC. You can generate one immediately using Generate Now after enabling.

To disable the feature, toggle it off in the same settings panel. Existing briefings remain visible on the dashboard; no new briefings will be generated.

Privacy note

The Weekly Risk Briefing sends the following data to Anthropic's API (Claude) to generate the narrative:

• PR titles and repository names
• File paths of changed files (not file contents or diffs)
• Risk signal names and scores
• Coverage percentages and deltas
• Incident titles and severities
• Reviewer GitHub logins

No source code, PR diffs, or commit messages are sent to the AI. The AI sees the same metadata that a human engineering leader would read in a weekly summary email. This is consistent with Koalr's data handling principles for all AI features.

For organizations with strict data residency requirements, contact support before enabling this feature.

Relationship to other features

• Deploy Risk: The high-risk PR section of the briefing draws directly from deploy risk scores. Teams that use deploy risk gates proactively will see fewer PRs appear in this section over time.
• Coverage vs Incident Correlation: Coverage declines in repositories with strong correlation scores are flagged with higher urgency in the briefing narrative.
• PR Autopsy: When an incident in the past 7 days has an autopsy result, the briefing references the most likely culprit PR, connecting the incident section to the high-risk PR section.
• Insights: The Weekly Risk Briefing is one of several AI-generated insights in Koalr. The Insights page provides on-demand analysis at any time, while the briefing provides a scheduled weekly synthesis designed for leadership consumption.