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 decisions CLI walkthrough (#1385)

Felix-Ayushecde654399eb
diff --git a/examples/README.md b/examples/README.md
index b9bf26788..413b306f2 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -8,6 +8,7 @@ self-contained README under `examples/<name>/`.
| Example | What it shows |
|---------|----------------|
| [codex/](codex/) | Codex CLI setup: `repowise init --codex`, smoke checks, local plugin install |
+| [decisions/](decisions/) | `repowise decision` list/health/confirm — architectural records (no LLM key) |
| [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) |
| [hooks-sync/](hooks-sync/) | `hook install` + `watch` — keep the index fresh (no LLM key) |
@@ -32,6 +33,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)
+- [Decisions](../docs/layers/DECISIONS.md)
- [Change risk](../docs/layers/CHANGE_RISK.md)
- [Test intelligence](../docs/layers/TEST_INTELLIGENCE.md)
- [Distill](../docs/agent/DISTILL.md)
diff --git a/examples/decisions/README.md b/examples/decisions/README.md
new file mode 100644
index 000000000..4c0fcbbde
--- /dev/null
+++ b/examples/decisions/README.md
@@ -0,0 +1,60 @@
+# Decisions Example
+
+Walk through `repowise decision` — list architectural decisions, review
+proposals, and read the health dashboard. No LLM key required for list/health.
+
+## Prerequisites
+
+1. A git repository with an index (`repowise init`, index-only is enough).
+2. `repowise` on `PATH` (`uv tool install repowise` or from this repo:
+ `uv sync --all-packages`).
+
+```bash
+cd /path/to/your-repo
+repowise init --index-only --yes
+```
+
+Decisions are mined during indexing from inline markers, commits, and other
+sources documented in [DECISIONS.md](../../docs/layers/DECISIONS.md).
+
+## 1. List and filter
+
+```bash
+repowise decision list
+repowise decision list --proposed # proposals needing review
+repowise decision list --status active
+repowise decision list --stale-only
+repowise decision show <id> # full record for one id
+```
+
+## 2. Health dashboard
+
+```bash
+repowise decision health
+```
+
+Shows active vs proposed counts, stale decisions, and hotspots that lack
+governing decisions.
+
+## 3. Curate records (interactive)
+
+```bash
+repowise decision add # interactive add
+repowise decision confirm <id> # accept a proposal
+repowise decision dismiss <id> # reject; won't be re-proposed
+repowise decision deprecate <id> # mark superseded
+```
+
+## Smoke checklist
+
+| Step | Expected |
+|------|----------|
+| `repowise decision list` | Table of decisions (or "No decisions found") |
+| `repowise decision list --proposed` | Proposed rows only, or empty |
+| `repowise decision health` | Counts + ungoverned hotspot paths |
+
+## Related docs
+
+- [Decisions layer](../../docs/layers/DECISIONS.md)
+- [CLI: `repowise decision`](../../docs/reference/CLI_REFERENCE.md)
+- [MCP `get_why`](../../docs/agent/MCP_TOOLS.md)