doc-analysis-risk-hotspots

Packet · {{ repo }} · analysis/risk-hotspots.md

1. Objective

Produce {{ docs_root }}/analysis/risk-hotspots.md: a ranked table of the top 12 files in {{ repo }} by combined risk score (30-day trend slope + current finding severity), followed by a ## Per-file drill-down section with one H3 per top-5 hotspot covering what's there, recent activity, owners, and open findings.

2. Scope

• Create: {{ docs_root }}/analysis/risk-hotspots.md
• Do not touch: {{ docs_root }}/analysis/ownership.md, {{ docs_root }}/analysis/dead-code.md, any other file under {{ docs_root }}/, any source file in the repo, .context.md, .prefetch.md, or any .packets/*.md other than this one.

3. Input specification

Source	Read how	Cache state
Shared context	Read {{ context_path }}	always first
Prefetch ledger	Read {{ prefetch_path }}	always first
Owners summary	{{ context_path }} § Owners summary	cached
Risk trends	mcp__codehub__risk_trends({repo: "{{ repo }}", window_days: 30})	mid-run
Current findings	mcp__codehub__list_findings({repo: "{{ repo }}", severity: ">=warn"})	mid-run
Owners per hotspot	mcp__codehub__owners({path: <file>}) or {{ prefetch_path }} § owners	cached when present
Verdict context (optional)	mcp__codehub__verdict({repo: "{{ repo }}"})	mid-run, optional

4. Process

1. Read {{ context_path }} and Read {{ prefetch_path }}. Confirm the Owners summary and any cached findings/trend digests.
2. Call mcp__codehub__risk_trends({repo: "{{ repo }}", window_days: 30}). Record the per-community / per-file trend slope (↑ rising, → flat, ↓ falling).
3. Call mcp__codehub__list_findings({repo: "{{ repo }}", severity: ">=warn"}). Group findings by file_path; compute N warn, M error counts per file.
4. Combine trend slope + severity into a risk score and rank files. Pick the top 12 for the ranking table; the top 5 feed the drill-down.
5. For each top-12 file: resolve the top owner from {{ prefetch_path }} § owners when present, else mcp__codehub__owners({path: <file>}). Capture percentage share.
6. Draft the ranked table with columns File | Trend | Open findings | Top owner | Citation. Every row cites the file as a backtick path with an optional (N LOC) suffix; every Open findings cell derives from list_findings output only.
7. Draft the intro (2 paragraphs): what "risk" means here, how the scoring is composed, the window. If risk_trends returned status: "insufficient_history", note the limitation in the intro and drop the Trend column.
8. Draft the ## Per-file drill-down section. One H3 per top-5 hotspot. Each H3 covers: What's there (2-sentence summary from context/Read), Recent activity (from risk_trends), Owners (top 1-2 with percentage share), Findings (counts by severity, each cited to list_findings).
9. Write {{ docs_root }}/analysis/risk-hotspots.md with H1 = {{ repo }} · Risk hotspots.