# set_finding_status

set_finding_status records a durable disposition on one refactoring plan, so a finding you already judged is never re-proposed. The write half of triage.

`get_health(include=["refactoring"])` hands an agent refactoring plans
read-only, and the generated task prompts ask it to flag the plans that
are wrong. There was nowhere to flag them to. `set_finding_status` is
that place: it writes a status onto the plan row, and the analyzer's
finalizer never re-emits a plan marked `false_positive`, so a judgment
made once survives every later run.

This is the same triage vocabulary the dashboard's REST `PATCH` path
writes, so a verdict recorded from an agent and one recorded from the
web UI are the same row. How triage works across every finding family is on
[Findings and triage](https://docs.repowise.dev/intelligence/findings), and the plans themselves
on [Refactoring intelligence](https://docs.repowise.dev/intelligence/refactoring). The other tools
are on [MCP tools](https://docs.repowise.dev/mcp/overview).

## Off by default

Registered but not part of the default tool surface in any mode. Turn
it on per repo:

```yaml
# .repowise/config.yaml
mcp:
  tools: ["+set_finding_status"]
```

or per launch with `repowise mcp --tools "+set_finding_status"`. See
[Configuring the tool surface](https://docs.repowise.dev/cli/server#repowise-mcp) for the
full `+`/`-` delta syntax.

It is the only mutating tool on the MCP surface. Every other tool
reads.

## When to call

- After reviewing a plan from `get_health(include=["refactoring"])` and
  concluding it is wrong for this repository.
- When the team has seen a real finding and is deliberately not acting
  on it yet, and you want it to stop reading as unheard.
- After the change landed, or the code moved on and the plan does not
  describe anything.

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `suggestion_id` | string |  | Required. The plan's id or public_id from get_health(include=["refactoring"]). A rendered display id ("<alias> <file>:<symbol>") also resolves. |
| `status` | string |  | Required. One of open, acknowledged, resolved, false_positive. Anything else raises. |
| `repo` | string |  | Repository alias. Usually omitted. |
| `reason` | string | `agent` | Free-text audit note stored on the row. |

## The four statuses

| Status | Meaning |
|---|---|
| `false_positive` | The plan is wrong for this repository. The finalizer suppresses its kernel, so it is never re-emitted on a future run |
| `acknowledged` | Real, but the team is consciously not acting now. Stays visible, stops counting as unheard |
| `resolved` | The change landed, or the code moved on. A plan a person resolved stays resolved even if the detector still fires |
| `open` | Reset a prior decision |

## Returns

| Field | Meaning |
|---|---|
| `id` | Storage id of the plan that was updated |
| `public_id` | Content-derived id, stable across re-analysis |
| `status` | The status now recorded |
| `status_reason` | The `reason` that was stored |
| `status_changed_at` | ISO timestamp, or `null` if none was recorded |
| `note` | One sentence confirming the write. On `false_positive` it states that future runs will not re-emit the plan |
| `_meta` | The standard envelope |

## Example

```python
set_finding_status(
    suggestion_id="a1b2c3d4",
    status="false_positive",
    reason="false alarm: the class is a DTO, the field count is the point",
)
```

## Things worth knowing

- An unknown status raises instead of being silently dropped. So does
  an id that does not belong to this repository.
- Only `false_positive` changes what future runs produce. The other
  three record a judgment without suppressing the detector.
- `public_id` is derived from the plan's content, so quote that one
  when you want an id that survives a re-index.

> **Note**
>
> The read half of this loop is
> [`get_health`](https://docs.repowise.dev/mcp/get-health) with `include=["refactoring"]`.
> To turn a plan you accept into actual code, see
> [`generate_refactoring_code`](https://docs.repowise.dev/mcp/generate-refactoring-code),
> which is opt-in too and has a second gate of its own.