zfin/docs/reference/config/acknowledgments-srf.md

acknowledgments.srf reference

acknowledgments.srf is an optional sibling of portfolio.srf that records which review 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 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):

#!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 -- acknowledging findings in the TUI.
• zfin review -- the findings dashboard (read-only for acks).

---

Documentation home