sam-financial

name	sam-financial
description	Analyze multi-currency personal or small-business finances from bank, wallet, and card statements, producing reconciled monthly reports with explicit uncertainty and privacy protection.

Sam Financial

Use this skill when the task is to understand where money went, reconcile statements, compare months, or produce a monthly financial report from user-provided records. It is not a license to access accounts, publish financial data, make speculative database changes, or give regulated tax or investment advice.

Non-negotiable privacy boundary

Treat every statement, invoice, spreadsheet, PDF, export, and annotation as confidential input. A public artifact may contain only generalized rules, synthetic examples, and semantic labels such as PERSONAL, WORK, BUSINESS, and ACCOUNT_A.

Before writing to a public repository or sharing an output, remove or avoid:

• names, e-mail addresses, usernames, phone numbers, addresses, employer/client names, and family details;
• bank, wallet, card, invoice, order, tax, account, routing, transaction, and document identifiers, including masked fragments;
• exact balances, salary values, transaction values, statement dates, merchant strings, filenames, local paths, URLs with tokens, and document metadata when they could identify a person;
• credentials, cookies, API keys, access tokens, private keys, and copied raw source content.

Do not upload private source files to the skill repository. Do not put sensitive material in commit messages, examples, fixtures, screenshots, generated HTML, or Git history. If a requested result requires a sensitive fact, keep it in the private working context and report only the minimum redacted conclusion. Read references/privacy-checklist.md before any public export.

Operating model

Keep these distinctions visible throughout the analysis:

• Currency: maintain one ledger per currency. Do not add currencies without an explicit exchange rate and a stated conversion date or method.
• Flow versus transfer: income and spending are economic flows; transfers between the user's own accounts are movements of cash, not income or spending.
• Calendar cash versus card consumption: a card payment is a cash event; the card's line items are the consumption event. Never count both as new spending.
• Personal versus work versus business versus investment: classify each material item once. Business inflows are not the individual's income; work tools and payroll are not personal discretionary spending; investments are not living costs.
• Fixed versus discretionary versus one-off: do not call payroll, insurance, housing, healthcare, debt installments, or a multi-period purchase an easy cut. Show one-off items separately and amortize them only when the user wants a planning view.
• Evidence versus inference: a plausible category or code path is a hypothesis until the relevant record is observed. A timeout, missing export, or inaccessible database is not evidence that the record is empty or correct.

For formulas and a neutral input shape, read references/ledger-model.md.

Monthly workflow

1. Read the user's classification notes and reporting requirements before applying merchant heuristics. Those notes are the source of truth for ambiguous counterparties.
2. Freeze the target calendar month M and comparison month M-1. Mark the result partial when the export, income cycle, card cycle, or account period is incomplete.
3. Inventory available sources by type: bank ledger, wallet ledger, card statement, invoices, and prior-month reference. Preserve originals; normalize copies into a reviewable table or markdown without changing source facts.
4. Reconcile before interpreting. Check opening balance plus signed movements against closing balance; check statement subtotals against printed totals; check card totals including fees/taxes; and match card payments to the corresponding statement.
5. Classify material movements into PERSONAL, WORK, BUSINESS, INVESTMENT, TRANSFER, or UNKNOWN. Keep UNKNOWN visible until evidence resolves it.
6. Calculate, separately for each currency: opening balance, inflows, outflows, transfers, closing balance, result, and the largest positive and negative drivers. Record the exchange-rate method only for an explicitly converted view.
7. Compare every important metric with M-1. Explain the change using named drivers and signed deltas; do not merely say that spending increased.
8. If there is an operating business, calculate whether its designated inflows covered its ads and other designated operating charges. State covered, not covered, or inconclusive, and do not silently treat business cash left in a shared account as personal income.
9. Produce the requested artifact only after the checks pass. For an offline HTML report, keep CSS and JavaScript embedded, avoid external CDNs, expose the partial-data warning, and include source labels that do not reveal private identifiers.
10. Finish with a compact evidence report: what was reconciled, what remains missing, what is inferred, and what was not changed.

Decision rules that prevent common errors

• If a source is missing, say exactly which source and metric are unavailable. Do not fill the gap with a prior-month number.
• If a statement is partial, do not compare incomplete percentages with complete months without labeling the limitation.
• If a transfer converts currency, show the debit in the source currency and the credit in the destination currency; do not call it income.
• If a business charge may be on more than one card, inspect every relevant statement in the cycle before declaring coverage.
• If a purchase is installment-based, report the observed installment number, remaining count, and last expected month only when the source provides them.
• If a database correction or fiscal mutation is requested, observe the real record first. Without access to the real record, remain read-only and mark the correction blocked.
• If a command, test, pipeline, or runtime check did not run to completion, label it unverified or blocked. Never convert a timeout into a pass.
• Recommendations must distinguish easy, medium, hard, and do not cut / verify first; do not present protected essentials as casual discretionary items.

Report shape

Unless the user requests another format, organize a monthly report into:

• executive verdict: savings or spending target, main drivers, and data completeness;
• currency ledgers: opening, inflows, outflows, transfers, closing, and reconciliation status;
• category views: personal life, work, business, and investment without mixing them;
• card view: cycle paid, consumption by category, fees/taxes, installments, and the no-double-count explanation;
• month-over-month explanation with signed deltas in plain language;
• prioritized actions grouped by difficulty and protected essentials;
• limitations and provenance.

Use direct language. Numbers should always carry a currency and a period. A conclusion should be traceable to a source row, checksum, or clearly labeled assumption.

Public-repository hygiene

When this skill itself is being packaged or published:

1. Keep only generalized instructions and synthetic data in the repository.
2. Run the privacy checklist and a secret scan over tracked files.
3. Inspect the final file list and Git diff; confirm no raw finance source, generated report, local path, personal identifier, or credential is present.
4. Use a technical, non-personal commit identity when the repository is public.
5. Verify the remote repository visibility and final commit after publishing. A successful git push alone is not proof that the intended public repository contains the intended sanitized content.