# A periodic review **Goal:** on a regular cadence -- weekly works well -- make zfin agree with your brokerages, see what changed since last time, and commit the reconciled state so the *next* review has a clean baseline to compare against. This is the loop that ties the other guides together. Each step has its own guide for the details; this one is the routine you actually run. It settles into well under an hour once it's habit. ``` reconcile ──► what changed? ──► (projections) ──► commit (audit) (compare) (optional) (baseline) ▲ │ └──────────────── next review ◄────────────────────────┘ ``` ## 1. Reconcile against your brokerages Pull a fresh export from each brokerage that offers one and drop it in your `audit/` folder (or wherever you've pointed `$ZFIN_AUDIT_FILES` -- see [Audit against your brokerage](audit-against-brokerage.md) for the export steps and auto-discovery rules). Then: ```bash zfin audit ``` Fix any flagged share or cash discrepancy in `portfolio.srf` and re-run until it reconciles. A tight edit loop helps: if you have [`watchexec`](https://github.com/watchexec/watchexec) installed, ```bash watchexec -- zfin audit ``` re-runs the audit on every save, so the remaining-discrepancy list shrinks live as you fix lots -- much faster than alt-tab, rerun, read, alt-tab, edit. **Reconcile first, for a reason.** Step 2 splits your change in value into **contributions vs. market gains**, and that split is only as honest as your share counts. Reconcile before you read the headline or the attribution will lie to you. ### Blind spots the audit can't see - **Accounts with no export** (some insurers, some 401(k) recordkeepers) -- check the latest statement and update `portfolio.srf` by hand. - **Payroll-driven cash** -- e.g. ESPP contributions that haven't purchased yet won't appear in a positions export until the purchase posts. Reconcile those against a paystub. - **A small, expected standing discrepancy** -- some accounts just sit a few dollars off every week. Note it and move on rather than chasing it each time. - **Lagging transaction views.** A brokerage's *positions* view can update overnight before its *transaction* view posts the dividend, interest, or option assignment that caused the change. Trust the positions numbers and reconcile the totals; the cause-side record catches up later and isn't needed to get today's counts right. ## 2. The headline -- what changed since last time One command gives you the whole "since last review" picture: ```bash zfin compare 1W --projections ``` - **`1W`** is the point of comparison -- the snapshot from one week ago. Any [relative shortcut](#relative-dates) or an explicit `YYYY-MM-DD` works. - **`--projections`** folds in projected-return and safe-withdrawal (SWR@99%) deltas, then vs. now. (Costs ~1-2s per endpoint for the Monte Carlo search; add `--no-events` to exclude life events.) - **No `--commit-before` needed.** Attribution now anchors itself on the commit that *recorded* the comparison snapshot. See [Attribution and commit timing](#attribution-and-commit-timing). Read off the liquid-total delta, the contributions-vs-gains split, the per-symbol winners and losers, and the projection deltas. For most weeks, this single command *is* the review. See [Snapshots and history](snapshots-and-history.md) for a full walk through `compare` output. ## 3. (Optional) Full projections `compare --projections` gives you the deltas but not the full benchmark table or every scenario row. When you want the complete picture: ```bash zfin projections # default: with life events (SS, college, ...) zfin projections --no-events # baseline: life events excluded zfin projections --as-of 1W # the same table as of last review zfin projections --vs 1W # both ends of the window in one run ``` See [Plan for retirement](plan-retirement.md) for what these rows mean. ## 4. Commit -- the baseline for next time ```bash git add portfolio.srf metadata.srf history/ git commit -m "review 2026-06-20" ``` Committing does double duty: - It snapshots the reconciled `portfolio.srf`, and the day's snapshot file in `history/` rides along, so future `--as-of` runs can read it. - zfin walks the git history of `portfolio.srf` for [contributions](track-contributions.md) analysis, treating each commit as a reconciliation point. **Commit timing sets next review's baseline** -- a same-day commit keeps a weekly cadence clean. If you keep your portfolio directory in git (recommended), this is also your backup and your audit trail. ## Attribution and commit timing `compare` and `contributions` work out "contributions vs. gains" by walking the git history of `portfolio.srf`. The positional date (`1W`) picks the *snapshot* whose prices you compare against; the attribution needs a *commit* to anchor on. If those two describe different periods, the split is wrong -- and it is wrong silently, because gains are derived as a residual (`delta - contributions`), so anything the attribution window misses is reported as market performance. **This is now handled for you.** The default anchor is the commit that ADDED `history/-portfolio.srf` for the snapshot being compared against. Because a review commits its snapshots together with the reconciled `portfolio.srf`, that commit *is* that week's reconciliation -- no naming convention, no dependence on how many times you committed, and unaffected by later edits to the file. **Do not pass `--commit-before HEAD`.** It used to be the recommended workaround for reconciling on Saturday and committing on Monday, and it worked only while `HEAD` happened to be the *previous* week's reconciliation commit. Commit anything during a review -- a data fix, a metadata tweak -- and the attribution window collapses to "uncommitted edits only" while the value window still spans the week. One observed case reported ~$23k of vested shares as market gains. The flag remains for pinning a window deliberately; it is no longer a habit worth having. ### Re-snapshot after reconciling One ordering detail matters more than it looks. If a scheduled job writes daily snapshots, the one for the last market day is captured *before* you reconcile -- so it holds pre-reconcile share counts while `portfolio.srf` ends up holding post-reconcile ones. The two then disagree at the same commit, permanently, by one reconciliation: ``` history/2026-08-21-portfolio.srf AMZN 1569 (pre-reconcile) portfolio.srf @ that same commit AMZN 1656 (post-reconcile) ``` `compare` reads the snapshot for "then" and the live portfolio for "now", so those 87 shares appear in the value delta. Attribution walks `portfolio.srf` across commits, where they were already present -- so no contribution is found and the residual absorbs them. Fix: run `zfin snapshot --force` after reconciling and before committing. On a non-trading day it rewrites the last trading day's file, so it never invents a weekend snapshot. ## Relative dates Every date-accepting command takes the same shorthand, so you rarely type a full date: | Shortcut | Means | |----------|-----------------| | `1W` | one week ago | | `3W` | three weeks ago | | `1M` | one month ago | | `1Q` | one quarter ago | | `1Y` | one year ago | `compare`, `contributions --since/--until`, `projections --as-of/--vs`, `snapshot --as-of`, and `history --since/--until` all accept it (plus an explicit `YYYY-MM-DD`). ## If there's no snapshot yet The comparison needs a snapshot to compare against. If your daily snapshot didn't run, or you're reviewing off your normal cadence, make one first: ```bash zfin portfolio --refresh # fresh close prices for tracked symbols zfin snapshot # writes history/-portfolio.srf ``` See [Snapshots and history](snapshots-and-history.md) for the cron setup that automates daily snapshots. ## Next steps - [Audit against your brokerage](audit-against-brokerage.md) -- step 1 in depth. - [Snapshots and history](snapshots-and-history.md) -- `compare`, snapshots, and the timeline. - [Track contributions](track-contributions.md) -- the contributions / gains attribution. - [Plan for retirement](plan-retirement.md) -- the projection rows. - [`compare`](../reference/cli/compare.md) and [`projections`](../reference/cli/projections.md) reference -- every flag. --- [Previous: Audit against your brokerage](audit-against-brokerage.md) | [Next: Customize the TUI](customize-the-tui.md) | [Documentation home](../README.md)