Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs(examples): add change-risk CLI walkthrough (#1177)

Felix-Ayush7683e21df220
diff --git a/examples/README.md b/examples/README.md
index 991160310..c67adc14c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -11,6 +11,7 @@ self-contained README under `examples/<name>/`.
| [distill/](distill/) | `distill` / `expand` / `saved` — compress command output (no LLM key) |
| [health-coverage/](health-coverage/) | Code health, coverage ingest, and impacted-tests (no LLM key) |
| [opencode/](opencode/) | OpenCode as the LLM provider for wiki generation |
+| [risk/](risk/) | `repowise risk` change / PR defect scoring (no LLM key) |
| [security-scan/](security-scan/) | Working-tree security signals + OSS `security scan --history` (no LLM key) |
| [structurizr-export/](structurizr-export/) | `export --format structurizr` fragment vs standalone (no LLM key) |
@@ -28,6 +29,7 @@ self-contained README under `examples/<name>/`.
- [Codex integration](../docs/agent/CODEX.md)
- [OpenCode integration](../docs/agent/OPENCODE.md)
- [Code health](../docs/layers/CODE_HEALTH.md)
+- [Change risk](../docs/layers/CHANGE_RISK.md)
- [Test intelligence](../docs/layers/TEST_INTELLIGENCE.md)
- [Distill](../docs/agent/DISTILL.md)
- [Structurizr export](../docs/architecture/structurizr-export.md)
diff --git a/examples/risk/README.md b/examples/risk/README.md
new file mode 100644
index 000000000..3b796e5e9
--- /dev/null
+++ b/examples/risk/README.md
@@ -0,0 +1,58 @@
+# Change-Risk Example
+
+Score the defect risk of a commit or `base..head` range with
+`repowise risk`. No LLM key required — pure git + calibrated signals.
+Works without `repowise init` (index is optional).
+
+## Prerequisites
+
+1. A git repository with at least one commit.
+2. `repowise` on `PATH` (`uv tool install repowise` or from this repo:
+ `uv sync --all-packages`).
+
+```bash
+cd /path/to/your-repo
+```
+
+## 1. Score HEAD or a range
+
+```bash
+repowise risk # score HEAD
+repowise risk main..HEAD # whole branch / PR as one change
+repowise risk HEAD~5..HEAD # recent local work
+```
+
+The headline is **repo-relative**: percentile and review priority
+(`Below typical` / `Typical` / `Elevated`) among recent commits. The raw
+0–10 model score is secondary context.
+
+## 2. Narrow what counts
+
+```bash
+# Only certain suffixes
+repowise risk --ext .py
+repowise risk main..HEAD --ext .ts,.tsx
+
+# Omit paths (repeatable); root .riskignore also applies
+repowise risk main..HEAD -x 'tests/' -x '*.spec.ts'
+```
+
+## 3. Machine-readable output
+
+```bash
+repowise risk main..HEAD --format json
+```
+
+## Smoke checklist
+
+| Step | Expected |
+|------|----------|
+| `repowise risk` | Table with score / percentile / review priority for HEAD |
+| `repowise risk main..HEAD` | Same shape for the range (or a clear revspec error) |
+| `repowise risk --format json` | JSON object; no API key needed |
+
+## Related docs
+
+- [Change risk](../../docs/layers/CHANGE_RISK.md)
+- [CLI: `repowise risk`](../../docs/reference/CLI_REFERENCE.md)
+- [Quickstart](../../docs/start/QUICKSTART.md)