Beancount Ask

beancount-ask

Answer ledger questions with shown, re-runnable BQL — never with model arithmetic.

This skill exists because a fluent-but-unverifiable answer about money is worse than no answer: the entire credibility of plain-text accounting is that every number is reproducible. So the contract is: every figure cited comes from a shown query execution, the query is shown with the answer, and the ledger is never modified. Prefer bea for reads when installed, fall back to bean-* only when bea is absent — stated once here, not repeated below.

Scope

Does: run read-only BQL against local ledger files; interpret results; show the query with every figure.

Does not: write, edit, or format any file; guess or estimate when data is missing; answer general "how does beancount work" questions (point at docs); compute figures in-model (the query engine computes, the skill interprets).

Workflow

1. Discover

Find the main ledger file (same procedure as the sibling skills: fd -e beancount -e bean ., main = the file with option/include directives). Confirm which file when ambiguous.

Tooling, in order of preference:

1. bea --file <ledger> --json query "<BQL>" — when bea is installed (managed engine runs Beanquery). Drop --json when reading the table yourself. bea --file <ledger> --json balance gives the pruned trial-balance subtree, and bea list transaction --search/--tag/--link finds entries without BQL. Do not pip install beanquery or configure private engine paths while bea is present; if the engine fails, repair/retry provisioning rather than switching to a global bean-query.
2. Without bea: bean-query <ledger> "<BQL>" if a developer environment already provides it; otherwise suggest installing bea.
3. For polished statements (income statement, balance sheet trees), bea --file <ledger> report income-statement beats raw BQL — say so rather than rebuilding them in BQL.
4. Optional quotes: bea price … needs bea engine enable beanprice first; recording a known quote uses bea add price without that feature.

2. Translate the question

Map the question to a recipe in references/bql-recipes.md — read it first; every query there is tested. Establish the period explicitly: "last month" etc. resolves against today's date; state the resolved date range in the answer. If the question is ambiguous ("how much do I spend?" — period? category? average or total?), ask, don't assume — a precise answer to the wrong question reads as authoritative and misleads.

3. Run, then answer

Run the query. Answer format:

• Lead with the figure(s), in a sentence or small table.
• Show the query underneath (collapsed/quoted is fine) so the user can re-run or refine it.
• Say what the data can't show when relevant (e.g. "transfers excluded; card payments are not spending").
• Point at the matching Fava view for browsing (Income Statement / Balance Sheet / Journal with a filter) when one exists.

Interpretation rules (the classic sign traps are in the recipes reference): Income accounts accumulate negative; Expenses positive; cost(position) for USD totals; transfers and credit-card payments are not spending — recipes exclude them by selecting ^Expenses: only.

4. When the data can't answer

Missing period, no such account/payee, ledger doesn't track it (e.g. market values without price directives): say exactly what's missing and what would make it answerable. Never estimate. If the answer needs a write (adding price directives, opening accounts), that's another skill's job — name it and stop.

What NOT to do

• Don't state any figure that didn't come out of the query you show.
• Don't modify, format, or "fix" any file — read-only, no exceptions.
• Don't answer an ambiguous question by picking an interpretation silently.
• Don't rebuild Fava's statements in BQL when pointing at Fava/bea report serves better.
• Don't extrapolate ("at this rate you'll…") without labeling it as arithmetic on top of queried figures — and keep even that minimal.