Skip to content

Latest commit

 

History

History

finances

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

type folder
description Cash-flow tracking: append-only ledger.csv, redacted statements, receipts; via /finance + /financial-summary
product shared
tags
finance
cashflow
ledger

finances/

Cash-flow tracking for the project. Where money went, how much, when — captured from a quick verbal note, a receipt screenshot, or a bank statement, so nothing is scattered and nothing is missed.

This folder breaks the usual one-file-per-entry KB pattern on purpose: transactions are tabular structured data, not prose. The source of truth is a single CSV, and human-readable views are generated from it (same philosophy as auto-generated INDEX.md). One markdown file per transaction would blow past every growth rule within a month.

Scope: single-entry cash-flow tracking, not bookkeeping. No double-entry, no accrual, no P&L, no tax prep. If real books are ever needed, that's QuickBooks and this becomes the feeder, not the replacement. See ../LIMITS.md § "Out of scope" for what stays out (cap tables, contracts, comp detail).


Layout

finances/
  README.md          # this file — the contract: schema, vocab, dedup + redaction rules
  ledger.csv         # SOURCE OF TRUTH — append-only, one row per transaction
  receipts/          # stored receipt images, <id>-<slug>.<ext> (small images only)
  statements/        # REDACTED parsed statement snapshots (.csv) — safe to re-reconcile
  summaries/         # generated by /financial-summary, persisted (type: finance-summary)
  INDEX.md           # auto-generated (note: ledger.csv is documented here, not in INDEX)

Skills

  • /finance — ingest a transaction. Three modes: verbal ("$40 to Example SaaS today"), receipt image, or bank statement (local file path). Parses → categorizes → dedup/reconciles → confirms with you before writing → appends/enriches the ledger → commits + pushes.
  • /financial-summary <period> [format] — on-demand formatted summary for a month/quarter/range, persisted to summaries/. One-off questions ("how much on SaaS in May?") need no skill — just ask; the ledger gets read live.

ledger.csv schema

One row per transaction. Columns, in order:

Column Meaning Notes
id Internal unique id YYYY-MM-DD-NN — NN = sequential within that date. Always distinct, even for legit duplicates.
date Transaction date ISO YYYY-MM-DD. For statements, the posting date.
direction in / out / transfer transfer = between our own accounts (net-zero; excluded from in/out totals).
amount Positive decimal Always positive; direction carries the sign. e.g. 420.00.
currency ISO code USD default. Column exists for future multi-currency; we do not auto-convert FX.
category Controlled vocab See "Categories" below. Drives summary breakdowns.
counterparty Who Merchant / payer / payee. e.g. Example SaaS, Example Cloud, Customer payout.
account Which account Last-4 or nickname only — never a full number. e.g. Bank ••1234, Card ••0007.
owner Whose money founder-a / founder-b / company. Who fronted the transaction, frozen at write time. Auto-filled from the account→owner map below; drives per-founder contribution / reimbursement reporting. A bank ext_id does NOT carry this — account/owner is the only thing that says whose.
ext_id External reference Bank transaction ref / receipt invoice or order no. Nullable. Dedup key, scoped to the account — bank refs are only unique within an account, so dedup keys on (account, ext_id), never ext_id alone.
source Provenance verbal / receipt:<file> / statement:<file>.
status pending / cleared pending = our capture (verbal and receipts start here); cleared = confirmed by a bank statement. A paid receipt is still pending — it proves the merchant charged us, not that the bank statement has matched it. Rule 4 flips it to cleared when the statement line lands.
note Free text Disambiguator for look-alikes ("2nd seat", "Q2 retainer"), or any context.

CSV rules: quote any field containing a comma; one header row; append-only (never rewrite history — corrections are a new row or an edit-with-note, and git log is authoritative).


Categories (controlled vocabulary)

Keep categories to this list so summary breakdowns stay aggregatable. If a real new bucket is needed, add it here in the same commit that first uses it.

Outflow (direction: out): payroll · contractors · saas · cloud · legal · accounting · marketing · travel · meals · hardware · office · fees · taxes · refund-out · misc-out

Inflow (direction: in): revenue · fundraise · grant · reimbursement · refund-in · interest · misc-in

Neutral (direction: transfer): transfer — moving our own money between accounts; excluded from spend/income totals.


Merchant → category map

Default category per recurring counterparty, so categorization is consistent (not saas one month, software the next) and confirmations are fast. The /finance skill pre-fills from this table, then you confirm; new mappings get appended here. Seed entries — extend as you log:

Counterparty Default category
Example SaaS saas
Example Cloud cloud
Example IDE saas
Example Hosting cloud
(bank) fee fees

Account → owner map

Who each account belongs to, so owner auto-fills consistently and per-founder contributions stay attributable. Before there's a dedicated company account, founders often front costs on personal cards — this map is the only thing that tells us whose (the bank's ext_id can't). Extend as accounts appear:

Account Owner
Card ••0007 founder-a

company is reserved for a shared/company account. When a card isn't in this map, the /finance skill asks whose it is and appends the mapping in the same commit.


Deduplication & reconciliation rules

You can't auto-decide duplicates — two identical real transactions are legal. The rule is detect suspects, then confirm, tiered by whether the source carries an ID. Confirm everything before writing (current policy).

  1. ext_id present and (account, ext_id) already in ledger → deterministically already recorded. Skip; report it. Key on (account, ext_id), not ext_id alone — bank refs are only unique within an account, so two different banks could collide on the same ref string and trigger a false skip.
  2. ext_id present but differs, even if fields look identical → genuinely a separate transaction (the bank gave it a distinct ref). Append.
  3. No ext_id, fingerprint (date, amount, counterparty, account) matches an existing row → suspected duplicate. Show the existing row and ask: same transaction (skip) or separate (append a second row, prompt for a distinguishing note)?
  4. Cross-source confirmation — an incoming statement row matches an existing pending entry by (amount, counterparty, date ±2 days) → it's the bank confirming your capture, not a new charge. Enrich the existing row (attach ext_id, set status: cleared); do not append. This is exactly the path a receipt logged as pending takes when its bank line lands — match on account too, since you know which account's statement you're importing.

A statement import reports three buckets back to you: confirmed (enriched), new (you never logged it → appended), in-ledger-but-not-in-statement (you logged it but the bank doesn't show it → flagged for review).


Privacy & redaction rules

This is real financial data in a private repo. Keep it private, and keep identifiers out.

  • Accounts: last-4 or nickname only. Never store full account, routing, or card numbers anywhere — ledger, statements, or notes.
  • Bank statements: never commit the raw file. Raw statements contain full account numbers and are large. /finance ingests a statement from a local path you point it at, parses + redacts in memory, and writes only a redacted snapshot CSV to statements/ (last-4 kept, full numbers stripped). The raw never touches the repo.
  • Receipts: stored as-is (they're designed to show only last-4). If a receipt ever exposes a full card number, flag it rather than committing — redact or skip the image and keep only the row.
  • Keep receipt images small. No multi-MB binaries (see ../LIMITS.md).

Rules: ../CONVENTIONS.md. Routing: ../AGENT-GUIDE.md. Entries: INDEX.md — auto-generated.