79 lines
4.5 KiB
Markdown
79 lines
4.5 KiB
Markdown
# `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)
|