# Extracting decisions with your agent

Have your coding agent mine a repository's history and docs and propose architectural decisions to hosted Repowise over MCP, each with a verbatim quote and the commit that carries it.

Your coding agent can read a repository's commit history, ADRs and docs and
propose each architectural decision it finds to hosted Repowise through the
`propose_decision` MCP tool. Every proposal lands as a **candidate** on the
repository's decisions page, quoted from its source and tied to a commit, and
governs nothing until it is confirmed.

## How decisions arrive

| Way in | Source label | What it carries |
|---|---|---|
| Indexing | ADR, Pull request, Git history, Marker | Mined on every index from the sources set under **Settings → Decision capture** |
| Your coding agent | Agent | A verbatim quote and the commit, through `propose_decision` |
| PR review replies | PR review | A reviewer's reply explaining why the code is right, quoted word for word |

All three appear under **Candidates** on the decisions page. The **Active** tab
shows how many are waiting.

## 1. Turn on propose_decision

`propose_decision` writes, so it is opt-in. Open the repository's
**Settings → MCP tools** and switch it on. The setting applies to your own
connections.

## 2. Connect with a write-scoped key

The tool needs an API key with the `write` scope, and you need write access to
the repository on Repowise.

1. Open the repository's **Decisions** page.
2. Under **How decisions arrive**, choose **create a write key**.
3. Generate the key with **read** and **write** ticked, and copy the snippet for
   your editor.

You can also mint one under
[Settings → Coding agents (MCP)](https://www.repowise.dev/settings?tab=editor)
with the write scope ticked. The connection URL is the per-repository endpoint:

```text
https://api.repowise.dev/mcp/{owner}/{repo}
```

Workspace endpoints are read-only and do not offer write tools. See
[Connecting your IDE](https://docs.repowise.dev/hosted/connecting-ide).

## 3. Run the prompt

On the decisions page, **Copy prompt** under **Your coding agent** copies a
ready-made prompt. Paste it into an agent that has the repository checked out.
It tells the agent to:

- call `get_why` first, to skip decisions Repowise already holds
- read ADRs, READMEs, CONTRIBUTING, merge commits and commits that explain a choice
- keep only decisions whose source says what was chosen and why
- quote the source verbatim and cite the commit
- propose at most 25 per run, strongest evidence first

## propose_decision

| Parameter | Required | Notes |
|---|---|---|
| `title` | Yes | Short name, up to 200 characters |
| `decision` | Yes | What was chosen, in the quote's words |
| `source_quote` | Yes | The passage that states it, copied exactly from the commit message, doc or comment |
| `evidence_commits` | Yes | 1 to 20 commit shas (7 to 40 hex characters) |
| `rationale` | No | Why, in the quote's words. Dropped when the quote does not support it |
| `context` | No | What forced the choice |
| `alternatives` | No | Options the source says were rejected |
| `consequences` | No | What follows from it |
| `affected_files` | No | Repo-relative paths it governs |
| `kind` | No | `architectural` (default) or `agreement` for a working rule |

The server checks every proposal before storing it:

| Check | Result |
|---|---|
| `decision` is not supported by `source_quote` | Refused with the reason |
| Same title as a decision already recorded | Returned as that decision; nothing new is written |
| More than 30 proposals a minute, or 1,000 open on the repository | Refused until the limit clears |

A successful call answers with the decision's id and a note that it was
proposed.

## Review the candidates

Candidates show the quote they were drawn from and their source. **Accept**
records that your team stands behind the decision; **Dismiss** removes it and
keeps it from being proposed again. Agents can confirm decisions too, with their
identity recorded. Confirmed decisions reach `get_why`, editor hooks and the PR
bot's review.