Enhance risk analysis features and documentation (#14)

- Updated the risk scoring system to include detailed per-file risk tiers (SAFE, REVIEW, TEST, CRITICAL) and narratives.
- Introduced new slash commands `/pr-risk` and `/pr-fix` for AI-assisted PR reviews, providing actionable insights based on risk assessments.
- Enhanced documentation to reflect changes in risk triage, scoring formulas, and command usage.
- Added tests for risk triage formatting and evidence gating logic to ensure accurate risk reporting.

This update improves the clarity and usability of the risk analysis tools within the project.

Author: kehoej

CLAUDE.md

@@ -59,7 +59,7 @@ make help       # List all targets
 cmd/contextception/    CLI entrypoint
 cmd/gen-schema/        JSON schema generator
 internal/
-  analyzer/            Core analysis engine (scoring, categorization, cycles)
+  analyzer/            Core analysis engine (scoring, categorization, risk triage, cycles)
   change/              PR/branch diff analysis
   classify/            File role classification
   cli/                 Command handlers (cobra subcommands)

CONTRIBUTING.md

@@ -31,16 +31,30 @@ make lint     # Run golangci-lint
 
 ```
 cmd/contextception/    CLI entrypoint
+cmd/gen-schema/        JSON schema generator
 internal/
-  analyzer/            Core analysis engine
+  analyzer/            Core analysis engine (scoring, categorization, risk triage)
   change/              PR/branch diff analysis
-  cli/                 Command handlers
-  config/              Configuration parsing
-  db/                  SQLite database layer
+  classify/            File role classification
+  cli/                 Command handlers (cobra subcommands)
+  config/              Configuration parsing (per-repo + global)
+  db/                  SQLite database layer (migrations, store, search)
   extractor/           Language-specific extractors (python, typescript, golang, java, rust)
-  git/                 Git history signals
-  indexer/             Incremental indexing
+  git/                 Git history signal extraction
+  grader/              Internal quality evaluation framework
+  history/             Historical analysis, usage tracking, and feedback storage
+  indexer/             Incremental indexing pipeline
+  mcpserver/           MCP server (tools, stdio transport)
+  model/               Shared data types
   resolver/            Module resolution (per-language)
+  session/             Claude Code session parser (discover, adoption)
+  update/              Version check, self-update, install method detection
+  validation/          Fixture-based validation framework
+  version/             Version injection (set via ldflags)
+protocol/              JSON Schema specifications
+schema/                Go types for schema generation
+integrations/          MCP config examples and slash commands
+testdata/              Test fixtures (synthetic repos + expected outputs)
 ```
 
 ## Adding a New Language

README.md

@@ -172,13 +172,47 @@ $ contextception analyze-change origin/main
 
 Returns a PR-level impact report with:
 
+- **Per-file risk scoring:** every changed file gets a risk score (0–100) and tier (SAFE/REVIEW/TEST/CRITICAL)
+- **Risk triage:** files grouped by tier with human-readable risk narratives explaining why each file is flagged
 - **Test gaps:** changed files with no test coverage, flagged before merge
+- **Test suggestions:** auto-generated recommendations for high-risk untested files (which test file to create, what to test)
 - **Coupling detection:** pairs of changed files that depend on each other
 - **Hidden coupling:** co-change partners *not in your diff* that may need updating
-- **Per-file blast radius:** which specific changes carry the most risk
+- **Aggregate risk:** overall PR risk score with percentile ranking against historical baselines (after 10+ analyses)
 - **Aggregated must_read:** merged context across all changed files
 
-Use `--ci --fail-on high` to gate PRs automatically. Results are stored in a local history database, enabling trend tracking with `contextception history`:
+### Risk Tiers
+
+| Tier | Score | Meaning |
+|------|-------|---------|
+| **SAFE** | 0–20 | New files, well-tested utilities, low coupling |
+| **REVIEW** | 21–50 | Moderate risk, standard code review sufficient |
+| **TEST** | 51–75 | High risk, targeted testing recommended |
+| **CRITICAL** | 76–100 | Maximum risk, regressions likely without careful review |
+
+Risk scores combine change status, structural factors (importer count, co-change frequency, fragility, mutual dependencies), and test coverage adjustments.
+
+### Token-optimized output
+
+Use `--compact` for a text summary optimized for LLM consumption (~60–75% fewer tokens than JSON):
+
+```bash
+$ contextception analyze-change --compact
+```
+
+### CI integration
+
+Use `--ci --fail-on` to gate PRs automatically. A risk badge is printed to stderr:
+
+```bash
+# Fail on high blast radius
+contextception analyze-change --ci --fail-on high
+
+# Fail only if risk triage has CRITICAL files
+contextception analyze-change --ci --fail-on critical
+```
+
+Results are stored in a local history database, enabling trend tracking with `contextception history`:
 
 ```bash
 $ contextception history hotspots     # Files that repeatedly appear as hotspots
@@ -249,7 +283,20 @@ Contextception averages ~1,000 tokens per analysis vs. Repomix's full-repo outpu
 
 ## MCP Setup (30 seconds)
 
-Make your AI agent smarter. Add to your `~/.claude.json` (Claude Code) or equivalent MCP config:
+Make your AI agent smarter. The `setup` command auto-detects your editor and configures everything:
+
+```bash
+# Claude Code (MCP server + hooks + slash commands)
+contextception setup
+
+# Cursor or Windsurf
+contextception setup --editor cursor
+contextception setup --editor windsurf
+```
+
+Use `--dry-run` to preview changes, or `--uninstall` to reverse.
+
+Or configure manually — add to your `~/.claude.json` (Claude Code) or equivalent MCP config:
 
 ```json
 {
@@ -273,11 +320,22 @@ This exposes nine tools to the AI agent:
 | `get_entrypoints` | Return entrypoint and foundation files for project orientation |
 | `get_structure` | Return directory structure with file counts and language distribution |
 | `get_archetypes` | Detect representative files across architectural layers |
-| `analyze_change` | Analyze the impact of a git diff / PR (blast radius, test gaps, coupling) |
+| `analyze_change` | Analyze the impact of a git diff / PR (risk scoring, triage, test gaps, coupling) |
 | `rate_context` | Rate how useful a previous `get_context` result was (feedback for accuracy tracking) |
 
 Works with **Claude Code**, **Cursor**, **Windsurf**, and any MCP-compatible tool.
 
+### Slash Commands
+
+Two built-in slash commands for AI-assisted PR review (installed automatically by `contextception setup`):
+
+| Command | Description |
+|---------|-------------|
+| `/pr-risk` | Run risk analysis on the current branch and present an actionable, human-friendly review |
+| `/pr-fix` | Analyze risk, then build an ordered plan to fix every issue found (test gaps, coupling, fragility) |
+
+These work by combining contextception's deterministic risk analysis with the LLM's ability to explain and translate — contextception computes the scores, the LLM presents them in plain language. See [`integrations/`](integrations/) for setup details.
+
 ---
 
 ## Language Support
@@ -320,7 +378,7 @@ contextception session                  Show contextception adoption across Clau
 | `--mode plan\|implement\|review` | Shape output for AI workflow stage |
 | `--token-budget N` | Cap output to fit token limits |
 | `--compact` | Token-optimized text summary (~60-75% fewer tokens than JSON) |
-| `--ci --fail-on high\|medium` | Exit codes for CI pipelines |
+| `--ci --fail-on high\|medium\|critical` | Exit codes for CI pipelines |
 | `--cap N` | Limit must_read entries (overflow to related) |
 | `--no-external` | Exclude external dependencies |
 | `--no-update-check` | Disable automatic update version check |

docs/ARCHITECTURE.md

@@ -119,11 +119,23 @@ The historical cap prevents co-change signals from overwhelming structural evide
 Analyzes the impact of a git diff (PR or branch):
 
 1. Diffs `base..head` to find changed files
-2. Analyzes each changed file independently
-3. Detects coupling between changed files (structural edges)
-4. Identifies test gaps (changed files with no test coverage)
-5. Surfaces hidden coupling (co-change partners not in the diff)
-6. Aggregates blast radius across all changed files
+2. Analyzes each changed file independently (full per-file AnalysisOutput)
+3. Computes per-file risk scores (0--100) with tier classification (SAFE/REVIEW/TEST/CRITICAL)
+4. Detects coupling between changed files (structural edges)
+5. Identifies test gaps (changed files with no test coverage)
+6. Surfaces hidden coupling (co-change partners not in the diff)
+7. Aggregates blast radius and risk triage across all changed files
+8. Generates test suggestions for high-risk untested files
+
+### Risk Scoring Engine (`internal/analyzer/risk.go`)
+
+Per-file risk scoring for change analysis. Formula: `base_score + structural_risk * coverage_multiplier`, clamped to [0, 100].
+
+- **Base score**: added=10 (20 with exports), modified=30, deleted=5, renamed=5
+- **Structural risk**: normalized importer count, co-change frequency, fragility (Ce/(Ca+Ce)), mutual deps, cycles
+- **Coverage adjustment**: direct tests ×0.7, dependency tests ×0.85, no tests ×1.2
+- **Evidence gating**: same-package siblings filtered unless they have import edges, co-change ≥2, or prefix match
+- **Percentile ranking**: stored in `history.sqlite` `risk_scores` table, computed after 10+ records
 
 ### Database Layer (`internal/db/`)
 

docs/features.md

@@ -98,6 +98,57 @@ Where Ce = files the subject imports (outdegree), Ca = files that import the sub
 
 ---
 
+## Risk Triage
+
+The `analyze-change` command assigns a per-file **risk score** (0--100) and groups files into tiers:
+
+| Tier | Score Range | Meaning |
+|------|-------------|---------|
+| `SAFE` | 0--20 | New files, well-tested utilities, low coupling |
+| `REVIEW` | 21--50 | Moderate risk, standard code review sufficient |
+| `TEST` | 51--75 | High risk, targeted testing recommended |
+| `CRITICAL` | 76--100 | Maximum risk, regressions likely without careful review |
+
+### Risk Score Formula
+
+The score combines four components:
+
+1. **Base score** by change status: added=10 (20 with exports), modified=30, deleted=5, renamed=5
+2. **Structural risk** (modified files only): normalized importer count, co-change frequency, fragility, mutual dependencies, circular dependencies
+3. **Coverage adjustment**: direct tests ×0.7, dependency tests ×0.85, no tests ×1.2
+4. **Clamp** to [0, 100]
+
+### Per-file fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `risk_score` | int | Computed risk score (0--100) |
+| `risk_tier` | string | `SAFE`, `REVIEW`, `TEST`, or `CRITICAL` |
+| `risk_factors` | []string | Factors contributing to the score |
+| `risk_narrative` | string | Human-readable risk explanation |
+
+### Report-level fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `risk_triage` | object | Files grouped by tier (critical, test, review, safe) |
+| `aggregate_risk.score` | int | Max per-file score across the PR |
+| `aggregate_risk.percentile` | int | Percentile vs. historical scores (after 10+ analyses) |
+| `aggregate_risk.regression_risk` | string | Summary of regression risk from critical files |
+| `aggregate_risk.test_coverage_ratio` | float | Ratio of changed files with direct tests |
+| `test_suggestions` | []object | Suggested tests for high-risk untested files |
+
+### Evidence-Gated Same-Package Filtering
+
+Same-package siblings (Go, Java, Rust) are only included in `must_read` if they have structural evidence:
+- Direct import/call edge
+- Co-change frequency >= 2
+- Filename prefix match
+
+This reduces noise in large packages where most siblings are irrelevant.
+
+---
+
 ## Hotspot Detection
 
 Identifies files that are both high-churn AND structural bottlenecks:
@@ -370,19 +421,24 @@ contextception session                  Show adoption across Claude Code session
 | `--signatures` | false | Include code signatures for must_read symbols |
 | `--stable-threshold` | adaptive | Indegree threshold for the stable flag |
 | `--ci` | false | CI mode: suppress output, exit code reflects blast radius |
-| `--fail-on` | high | Blast radius level that triggers non-zero exit (`high` or `medium`) |
+| `--fail-on` | high | Trigger non-zero exit: `high`, `medium`, or `critical` (risk triage) |
 | `--mode` | (none) | Workflow mode: `plan`, `implement`, or `review` |
 | `--token-budget` | 0 | Target token budget (auto-adjusts caps) |
 | `--compact` | false | Token-optimized text summary (~60-75% fewer tokens than JSON) |
 
 ### CI mode
 
-When `--ci` is set, output is suppressed and the exit code reflects blast radius:
+When `--ci` is set, output is suppressed and the exit code reflects blast radius. A risk badge is also printed to stderr:
+
+```
+contextception: main..HEAD blast_radius=high files=27
+RISK: 72/100 | 1 CRITICAL | 2 TEST | 5 REVIEW | 19 SAFE
+```
 
 | Exit code | Meaning |
 |-----------|---------|
 | 0 | Blast radius below threshold |
-| 1 | Medium blast radius (with `--fail-on medium`) |
+| 1 | Medium blast radius (with `--fail-on medium`) or CRITICAL files (with `--fail-on critical`) |
 | 2 | High blast radius |
 
 ```bash
@@ -391,6 +447,9 @@ contextception analyze-change --ci --fail-on high
 
 # Fail on medium or high
 contextception analyze-change --ci --fail-on medium
+
+# Fail only if risk triage has CRITICAL files
+contextception analyze-change --ci --fail-on critical
 ```
 
 ### Workflow modes

integrations/README.md

@@ -38,7 +38,10 @@ contextception setup --editor cursor
 contextception setup --editor windsurf
 ```
 
-Use `--dry-run` to preview changes, or `--uninstall` to reverse. For Claude Code, this also installs hooks that remind the AI to call `get_context` before editing files.
+Use `--dry-run` to preview changes, or `--uninstall` to reverse. For Claude Code, this installs:
+- MCP server configuration
+- PreToolUse hooks that remind the AI to call `get_context` before editing files
+- `/pr-risk` and `/pr-fix` slash commands for AI-assisted PR review
 
 ## Manual Configuration
 
@@ -151,6 +154,17 @@ All integrations expose the same nine tools:
 
 Contextception supports repositories using: Python, TypeScript/JavaScript, Go, Java, Rust.
 
+## Slash Commands
+
+Two slash commands are included for AI-assisted PR review. These are installed automatically by `contextception setup` for Claude Code.
+
+| Command | File | Description |
+|---------|------|-------------|
+| `/pr-risk` | [`claude-code/pr-risk.md`](claude-code/pr-risk.md) | Run risk analysis and present a human-friendly review with verdicts, test coverage, and next steps |
+| `/pr-fix` | [`claude-code/pr-fix.md`](claude-code/pr-fix.md) | Analyze risk, then build an ordered fix plan for every issue (test gaps, coupling, fragility) |
+
+For Cursor/Windsurf, place the command files in `.cursor/rules/` or `.windsurf/rules/` respectively. For other agents, see [`pr-risk-review.md`](pr-risk-review.md) for the full prompt template.
+
 ## Further Reading
 
 - [MCP Tutorial](../docs/mcp-tutorial.md) — step-by-step guide to adding context intelligence to any AI agent