# `acknowledgments.srf` reference

`acknowledgments.srf` is an optional sibling of `portfolio.srf` that
records which [`review`](../cli/review.md) **findings** you've
acknowledged -- and why. The observation engine re-derives findings
("Position concentration: NVDA at 18.2%") on every run; acknowledging
one suppresses it from the active list and saves your reasoning, so the
decision survives across runs instead of nagging you every time.

Missing file -> every finding is simply "active"; nothing is suppressed.

## Who writes it

The **interactive TUI's Review tab** writes this file when you
acknowledge (`a`) or un-acknowledge (`U`) a finding. The CLI
[`zfin review`](../cli/review.md) is **read-only**: it shows findings
and honors existing acknowledgments (`--show-acked` to include them in
the table) but never edits the file. It is plain SRF, so you *can* edit
it by hand, but it's normally managed for you.

## File format

Compact-form SRF with two record types. Each `type::note` attaches to
the most recent `type::acknowledgment` above it (a note before any ack
is a parse error):

```srf
#!srfv1
type::acknowledgment,observation::position_concentration,target::NVDA,acknowledged_at::2026-06-08,state::acknowledged
type::note,line::Holding through the earnings cycle.
type::note,line::Will trim by Q3.
type::acknowledgment,observation::sector_dominance,target::VTI,SCHD,acknowledged_at::2026-06-08,state::acknowledged
```

Each acknowledgment is uniquely keyed by `(observation, target)` --
there is never more than one record per pair; a state change mutates it
in place (git tracks the history of the file).

### `type::acknowledgment`

| Field               | Type   | Required | Description                                                                                                   |
|---------------------|--------|----------|---------------------------------------------------------------------------------------------------------------|
| `observation`       | string | Yes      | The check that fired, e.g. `position_concentration`, `sector_dominance`.                                      |
| `target`            | string | Yes      | What it's about: `NVDA` (single symbol), `sector:Technology` (sector), or `VTI,SCHD` (a pair, for dominance). |
| `acknowledged_at`   | date   | Yes      | Date first acknowledged (`YYYY-MM-DD`). Immutable after creation.                                             |
| `state`             | enum   | Yes      | `active`, `acknowledged`, or `resolved` (see below).                                                          |
| `unacknowledged_at` | date   | No       | Breadcrumb: when you last un-acked. Persists across re-acks.                                                  |
| `resolved_at`       | date   | No       | Breadcrumb: when the engine auto-resolved the finding.                                                        |

### `type::note`

| Field  | Type   | Required | Description                                                                                                         |
|--------|--------|----------|---------------------------------------------------------------------------------------------------------------------|
| `line` | string | Yes      | One line of your reasoning. Multi-line notes are several consecutive `note` records attached to the ack above them. |

## State lifecycle

| State          | Meaning                                                                               |
|----------------|---------------------------------------------------------------------------------------|
| `active`       | Live and shown in the active findings list (effectively un-acked).                    |
| `acknowledged` | You've acked it; hidden from the active list unless you pass `--show-acked`.          |
| `resolved`     | The underlying condition no longer holds (e.g. you trimmed the position); engine-set. |

Transitions -- driven from the TUI, except `resolved`, which the engine
sets on its own:

- **acknowledge** (`active -> acknowledged`) -- clears `unacknowledged_at`.
- **un-acknowledge** (`acknowledged -> active`) -- stamps `unacknowledged_at`.
- **auto-resolve** (`* -> resolved`) -- stamps `resolved_at`.
- **reappear** (`resolved -> active`) -- clears `resolved_at` when the condition returns.

## See also

- [Read your portfolio](../../guides/read-your-portfolio.md#review-per-holding-performance-and-risk) -- acknowledging findings in the TUI.
- [`zfin review`](../cli/review.md) -- the findings dashboard (read-only for acks).

---

[Documentation home](../../README.md#reference)