teamtinvio/jaz-ai / .agents/skills/transaction-recipes
jaz-recipes
VerifiedUse this skill when modeling complex multi-step accounting transactions: anything that spans multiple periods, involves changing amounts, or requires linked entries. Covers 16 IFRS-compliant recipes (prepaid amortization, deferred revenue, loans, IFRS 16 leases, hire purchase, fixed deposits, asset disposal, FX revaluation, ECL, IAS 37 provisions, dividends, intercompany, capital WIP) and 13 financial calculators that return the schedule and the journal lines to post. Also use when the user mentions depreciation, amortization, lease accounting, loan schedules, or any IFRS calculation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 25.7 KB |
| references/accrued-expenses.md | markdown | 10.2 KB |
| references/asset-disposal.md | markdown | 16.2 KB |
| references/bad-debt-provision.md | markdown | 12.1 KB |
| references/bank-loan.md | markdown | 12.9 KB |
| references/building-blocks.md | markdown | 25.4 KB |
| references/capital-wip.md | markdown | 15.1 KB |
| references/declining-balance.md | markdown | 12.0 KB |
| references/deferred-revenue.md | markdown | 11.7 KB |
| references/dividend.md | markdown | 12.3 KB |
| references/employee-accruals.md | markdown | 11.4 KB |
| references/fixed-deposit.md | markdown | 12.1 KB |
| references/fx-revaluation.md | markdown | 10.1 KB |
| references/hire-purchase.md | markdown | 8.1 KB |
| references/ifrs16-lease.md | markdown | 14.1 KB |
| references/intercompany.md | markdown | 11.3 KB |
| references/prepaid-amortization.md | markdown | 10.5 KB |
| references/provisions.md | markdown | 12.7 KB |
references/fx-revaluation.md
View on GitHub# Recipe: FX Revaluation, verification-only (calculator type: `fx-reval`)
> **Jaz auto-handles FX revaluation for ALL foreign-currency monetary balances.** AR, AP, cash, bank accounts, intercompany journals, term deposits, FX-denominated provisions, all of it. Period-end translation per IAS 21.23 happens inside the platform with no manual journal required.
>
> **DO NOT post the `fx-reval` calculator's result.** Its output includes a revaluation journal and a reversal; posting either would double-count against Jaz's auto-emitted FX gain/loss journals. The calculator exists for one purpose: **independent cross-check** of what Jaz auto-posted. No capsule is created and nothing is posted in this recipe.
## What this recipe is for now
- **Verification:** confirm Jaz's auto-posted FX gain/loss for the period matches your independent calculation
- **Audit support:** produce a worked schedule the auditor can tie back to (closing rate, book rate, foreign amount, computed gain/loss)
- **Variance investigation:** when `generate_trial_balance` shows an unexpected FX Unrealized Gain/Loss balance, recompute what it *should* be and surface the delta
## What this recipe is NOT for anymore
- Posting FX reval journals: Jaz already did it
- Posting Day 1 reversals: Jaz already did it
- Hand-building FX schedules: the calculator does it offline
- Setting up scheduled FX reval: Jaz handles it on the reporting date
## Tools and calculator this recipe uses
### Calculator (offline, posts nothing)
- **MCP: `calculate(type: 'fx-reval', amount, bookRate, closingRate, rateDirection, position, currency, baseCurrency)`**: independent gain/loss computation. `rateDirection` is REQUIRED. `position` defaults to `ASSET`; pass `LIABILITY` for a payable or provision, where a rising base value is a **loss** rather than a gain.
- **CLI: `clio calc fx-reval --amount <foreign> --book-rate <historical> --closing-rate <period-end> --rate-direction <FUNCTIONAL_TO_SOURCE|SOURCE_TO_FUNCTIONAL> --currency <code> --base-currency <base currency> --json`**: the same result (`--position` for the balance-sheet side).
Both return `{ bookValue, closingValue, gainOrLoss, isGain, journal, reversalJournal, blueprint }`. Use the numbers to verify what Jaz auto-posted. The `journal`, `reversalJournal` and blueprint steps show what the entry would be; they are for comparison, never for posting.
### Tools (jaz-api / direct): verification only
- **`generate_general_ledger(startDate: <period-start>, endDate: <date>, accountResourceIds: [<FX Unrealized Gain | Loss>])`**: pull what Jaz auto-posted to the FX accounts during the period.
- **`generate_general_ledger(startDate: <FY-start>, endDate: <date>)`**: discover all foreign-currency monetary balances at period end.
- **`list_currency_rates(currencyCode: 'USD')`**: confirm the closing rate Jaz used (take the rate effective on or before period-end; the tool has no date filter). Per `jaz-api/SKILL.md` rule 49, the API stores rates `functionalToSource` (1 base unit = N foreign). The calculator **requires** a rate direction (`rateDirection`, CLI `--rate-direction`), so there is no implicit convention to get wrong: pass a `list_currency_rates` value with `FUNCTIONAL_TO_SOURCE`, or an everyday "1 USD = 1.35 SGD" quote with `SOURCE_TO_FUNCTIONAL`. Both describe the same position and produce the same valuation.
- **`generate_trial_balance(endDate: <date>)`**: confirm foreign-currency monetary balances translated correctly at the closing rate.
- **`generate_balance_sheet(snapshotDate: <date>)`**: IAS 21.23 verification (all monetary items at closing rate).
### Cross-references
- Operational context: invoked during month-end close only as a VERIFICATION step (cross-check Jaz's auto-posted reval against an independent calculation; surface any variance). Same during the GST/VAT filing cycle and year-end close.
- IFRS / accounting context: IAS 21.23 (closing-rate translation of monetary items); IAS 21.16 (non-monetary items stay at historical rate). Jaz implements IAS 21.23 automatically.
---
## Verification flow (what to actually do)
### Step 1: Pull what Jaz auto-posted
```
search_accounts(filter: {name: {in: ['FX Unrealized Gain', 'FX Unrealized Loss', 'FX Bank Revaluation', 'FX Realized Gain', 'FX Realized Loss']}})
```
Get the resourceIds for every FX account in the org. Bank/cash FX is always "FX Bank Revaluation" (not "Realized"). AR/AP FX uses "Realized" (settlement-time) and "Unrealized" (period-end translation). All emitted automatically.
```
generate_general_ledger(
startDate: '2025-12-01',
endDate: '2025-12-31',
accountResourceIds: [<FX Unrealized Gain id>, <FX Unrealized Loss id>, <FX Bank Revaluation id>],
groupBy: 'ACCOUNT'
)
```
This is the FX activity Jaz posted during the period. Each row carries the source transaction (the underlying foreign-currency journal / cash entry / invoice / bill) and the rate Jaz applied.
### Step 2: Discover the eligible foreign-currency balances at period-end
```
generate_general_ledger(startDate: '2025-01-01', endDate: '2025-12-31')
```
Filter to accounts with non-zero balances whose underlying transactions carry a non-base-currency `currency.sourceCurrency`. These are the balances Jaz translated. For each, capture: `{accountName, foreignAmount, sourceCurrency, baseAmountPerJaz}`.
### Step 3: Independent calculation
For each foreign balance from step 2:
```
list_currency_rates(currencyCode: 'USD') // pick the rate effective on or before 2025-12-31
```
Then run the calculator:
```
calculate(
type: 'fx-reval',
amount: 50000,
bookRate: <rate the balance was booked at, same direction>,
closingRate: <rateFunctionalToSource from list_currency_rates, as-is>,
rateDirection: 'FUNCTIONAL_TO_SOURCE',
currency: 'USD',
baseCurrency: 'SGD'
)
```
```
clio calc fx-reval \
--amount 50000 \
--book-rate <pull from earliest unposted-against rate> \
--closing-rate <rateFunctionalToSource from list_currency_rates, as-is> \
--rate-direction FUNCTIONAL_TO_SOURCE \
--currency USD \
--base-currency SGD \
--json
```
Read `gainOrLoss` (signed; `isGain` says which) and `closingValue` (the balance in base currency at the closing rate). This is what the FX gain/loss for that balance *should* be in isolation.
### Step 4: Reconcile expected vs actual
Sum your independent gain/loss across all foreign balances. Compare against the FX gain/loss totals from step 1. They should agree within the entity's materiality threshold.
If they don't agree:
- **Likely cause 1:** Jaz used a different `book rate` than your independent calc assumed. Settlement-realized FX (when an FX invoice/bill was actually paid in the period) shifts the book rate forward.
- **Likely cause 2:** A new foreign-currency transaction posted with an explicit `currency.exchangeRate` override (per `jaz-api/SKILL.md` rule 25), which overrides the platform-resolved rate.
- **Likely cause 3:** Multi-leg FX (e.g., USD invoice paid from SGD bank with bank-side FX spread): Jaz splits the FX impact between AR and bank-side.
Surface the variance to practitioner with both numbers and the breakdown by account.
### Step 5: Document and move on
Save the verification to `recurring/<period>/fx-reval-verification.{json,csv}`:
- Per-balance: foreign amount, book rate, closing rate, expected gain/loss, actual gain/loss (per Jaz GL), variance.
- Total: expected vs actual.
- Variance commentary for any line beyond materiality.
This file feeds `audit-prep.md` step 8 supporting schedules. Auditors love independent FX cross-checks.
---
## When this recipe DOESN'T apply
- Pure SGD-only org (no foreign currencies): skip entirely.
- Org with multi-currency disabled: `list_currency_rates` returns nothing useful; skip and document.
- An auto-posted FX journal that an auditor questions (post-hoc): use this verification flow to demonstrate the calculation; do NOT correct it by posting the calculator's journal. If a real correction is needed, post a manual journal targeting `FX Unrealized Gain` / `Loss` directly and document why.
---
## Common error classes and recovery
| Source | Error | Recovery |
|--------|-------|----------|
| Independent calc disagrees with Jaz | Variance > the entity's materiality threshold | Investigate per "Likely causes" in step 4. Common false positive: book rate drift after a settlement event mid-period. Re-run with the post-settlement book rate. |
| `list_currency_rates` returns no rate for the period end | No closing rate set | Practitioner must `add_currency_rate(...)` for the period-end. Without it, Jaz can't translate either; this is also why your variance is suspect (Jaz may have used the most recent rate before period-end as a fallback, not the actual closing rate). |
| Practitioner asks to post a manual reval anyway | (process error) | Halt and explain: Jaz already posted. Manual posting will double-count. If they insist there's a real correction needed, route through a manual journal against `FX Unrealized Gain/Loss` with a clear narrative that says what is being corrected and why. |
---
## Orgs without automatic FX revaluation (rare, legacy)
**This section applies ONLY to an org where automatic FX revaluation is confirmed off. Everywhere else this recipe is verification only and nothing is posted.** Some orgs may still run on a configuration where automatic FX revaluation is disabled. Never assume it: confirm with the practitioner, and check that the period's general ledger carries no auto-posted FX revaluation entries, before treating an org as one of them. Only for such an org: take the period-end `journal` and the `reversalJournal` from the calculator and post them as two manual journals with `create_journal`, the reversal dated the first day of the next period. DO NOT do this in any org where Jaz revalues automatically, which is the default and the typical case.
---
## Cross-references
- Month-end close: VERIFICATION ONLY. Confirm Jaz's auto-posted FX gain/loss matches independent calc; surface variance only.
- GST/VAT filing cycle: same.
- Year-end close: FY-end FX verification feeds audit-prep step 8 supporting schedules; auditors want the independent recomputation alongside Jaz's auto-posted journals.
- `audit-prep.md` step 8: receives the verification file as a supporting schedule.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |