// Validate hledger journal files using check/format scripts. Includes validation procedures and local hook (Husky + lint-staged) verification.
Edit hledger journal files following best practices and conventions. Includes prelude includes, balance assertions, tagging, formatting, and validation procedures with anti-patterns to avoid.
Transcribe transactions from source documents into the hledger ledger. Handles raw data (receipts, invoices, bank statements, OCR text) with proper status markers, tagging, and account registration. For multiple entries, uses a separate subagent for each transaction to enable parallelization and focused scope.
Strict, step-by-step workflow for upserting Octopus card transactions to the ledger. Requires explicit user clarification for any ambiguity. Enforces contextual matching, mapping, and privacy rules. No guessing or inference allowed.
Add a new payee (merchant, person, organization, or UUID) to the correct preludes journal file, maintaining strict lexicographical order.
Match Octopus Wallet statement rows to journal transactions and update transaction datetimes. Runs only when explicitly requested.
Perform monthly journal migration using hledger close --migrate to close the previous month and open the new month with proper balance assertions and account initialization.
| name | validate-journals |
| description | Validate hledger journal files using check/format scripts. Includes validation procedures and local hook (Husky + lint-staged) verification. |
Note: Use full path ledger/[year]/[year]-[month]/[name].journal (e.g., ledger/2024/2024-01/self.journal).
Validate journals to catch errors and ensure consistency before committing.
Note: Use canonical scripts: bun run format then bun run check (or python -m ... with cwd=scripts/ when required). See .agents/instructions/developer-workflows.instructions.md and .agents/instructions/agent-quickstart.instructions.md for details and quick commands.
Examples: See ./examples.md for quick validation command examples and common fixes.
Tip (integrated): Run bun run format first to reduce noisy validation failures — advice reflected in lessons.md.
The python -m check script runs hledger --strict mode checking:
| Error | Fix |
|---|---|
| Account not defined | Add to preludes/self.journal |
| Balance mismatch | Fix transaction or prior balances |
| Transaction not balanced | Add missing postings |
| Payee not defined | Add to preludes/self.journal |
| Tag not defined | Add to preludes/self.journal |
| Date out of order | Correct date or reorder |
| Small closing/opening mismatch | Compare the affected account running balance and adjust the matched opening/closing equity posting |
The formatter normalizes:
50.00 HKD16 966.42 HKDactivity:, eating:, time:, timezone:assets:banks:<bank-uuid>Note: See .agents/instructions/common-workflows.instructions.md for the canonical Pre-Commit Checklist (Husky + lint-staged) and setup instructions, including running bun run format, python -m check, and bun run test. Also see .agents/instructions/developer-workflows.instructions.md for scripts/ working directory guidance.
# Check single month instead of all
hledger -f ledger/2025/2025-01/self.journal --strict bal
# Verify specific account
hledger -f ledger/index.journal accounts | grep "your-search"
hledger -f ledger/index.journal register "assets:cash"
python -m check before committing