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 every figure comes from a query run against the ledger, the query is shown with the answer, and the ledger is never modified.
Prefer bea
Read beancount-init's references/bea-cli.md (from this skill's folder, ../beancount-init/references/bea-cli.md; a copy at references/bea-cli.md when this skill was installed alone) before running ledger commands: it binds the root ledger, lists the read recipes, explains valuation and missing prices, and records version notes. Without bea, use beancount-init's references/compatibility.md. Run the queries yourself: bea ask hands the question to another model, and its figures are not queries you can show.
Scope
Does: run read-only BQL against local ledger files, interpret the results, and show the query with every figure.
Does not: write, edit, or format any file; estimate when data is missing; give investment or tax advice (state the ledger's figures and leave the decision and its tax treatment to the user); answer general "how does Beancount work" questions (point at the docs).
Workflow
1. Discover
Local ledger files only. For a ledger hosted on Beancount.io, stop this skill and offer a separately requested hosted workflow or local clone (beancount-init's references/bea-cli.md, Hosted ledgers).
Find the root ledger with the suite's discovery convention (fd -e beancount -e bean .; the root has option/include directives) and confirm it when ambiguous. Bind it as ledger for the shared read recipes:
bea --file "$ledger" --json --no-input query "$query"
bea --file "$ledger" --json --no-input balance
bea --file "$ledger" --json --no-input report income-statement --time "$month"
- Spending comes from the
weight recipes. balance and most report kinds value at market, and a commodity without a price makes them exit 1 with result.missing_prices (a valuation gap, not an engine failure); pass -x at_cost for book value and disclose the missing prices. report cash-flow is the exception: it always runs at cost and takes no --conversion.
- Entry searches use root-scoped
list transaction --search/--tag/--link, read to completion (beancount-init's references/bea-cli.md, Version notes, on list pages).
- Market values come from the ledger's price directives and managed price includes, which resolve during a
bea load; bea --file "$ledger" price status reports their freshness. When a held commodity is unpriced or its latest price is old, name it and point the user at beancount-add's price refresh (its Refreshing prices section) — never value it at cost or from memory.
- Realized gains for a period (per closed lot, with holding period, tied to the booked gain postings) start with
bea report capital-gains --from-date/--to-date, then the booked tie-out in beancount-trade's references/realized-gains.md (from this skill's folder, ../beancount-trade/references/realized-gains.md); recording a trade itself is beancount-trade.
- Cash movement ("why did my balance change") starts with
bea report cash-flow --time "$month": operating/investing/financing flows that net to the cash change, each row an account's inverted movement. Use the command's figures, not a hand-written equivalent.
2. Translate the question
Map the question to a recipe in references/bql-recipes.md — read it first; every query there is tested. For the human-readable starting point, the BQL cookbook runs the same recipe families against fixture ledgers with verified shapes. Resolve the period against today's date ("last month") and state the resolved range in the answer. For "why did this change" questions use the variance recipe (section 9): thresholds are the user's stated policy, every claimed driver cites its postings, and an explanation the postings don't support is labelled unresolved — never an invented cause. When the question is ambiguous ("how much do I spend?" — which period, which categories, total or average?), ask which one the user means: a precise answer to the wrong question reads as authoritative.
3. Run, then answer
Run the query and answer:
- Lead with the figure(s), in a sentence or small table, each one from the query output.
- Show the query underneath (collapsed or quoted) 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 or
bea report for statement-shaped answers rather than rebuilding them in BQL.
- Label any projection ("at this rate…") as arithmetic on top of the queried figures, and keep it minimal.
- "Should I buy/sell…?" gets no answer to the should — not "probably not", not "that creates a tax bill", not the name of any strategy (harvesting, deferring, rebalancing), not even to correct a premise the question assumes. Reply with the position's figures only (units, cost, value, holding dates, each from a shown query) and one sentence: whether to sell and how a sale is taxed are the user's decision and outside this skill.
Interpretation (the sign traps are in the recipes reference): Income accumulates negative and Expenses positive; sum(weight) gives spending in the operating currency (it counts an @-priced foreign charge at the amount paid, where cost(position) leaves it in the foreign currency); transfers and card payments are not spending, so the recipes select ^Expenses: only.
4. When the data can't answer
A missing period, no such account or payee, or something the ledger doesn't track (market values without prices): say exactly what is missing and what would make it answerable. Never estimate. When the answer needs a write — adding prices, opening an account, refreshing a price include — name the skill or workflow that does it and stop; this skill only reads.