| name | monthly-migration |
| description | 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. |
Monthly Migration Skill
Note: Use full path ledger/[year]/[year]-[month]/[name].journal (e.g., ledger/2024/2024-01/self.journal).
Guide for migrating journals at the start of each month.
When to Use
- Start of each month (typically 1st-3rd) before adding new transactions
- Previous month is complete and validated
- Setting up opening/closing balances
Examples: See ./examples.md for canonical migration commands and verification steps.
Quick reference: See .agents/instructions/agent-glossary.instructions.md for short definitions.
Prerequisites
- All transactions for previous month finalized
- Both
self.journal and self.alternatives.journal need migration
- Ran
python -m check successfully
Process (condensed)
- Run
hledger close --migrate -f ledger/YYYY/YYYY-MM/self.journal for each journal to generate closing/opening transactions.
- Copy the generated closing balances into the previous-month journal and the opening balances into the new month (after the prelude include).
- If a previous month's closing balances are corrected after the next month has already been created, update the next month’s opening balances to match the corrected closing balances.
- Ensure the new month directory and
self.journal exist and include the correct prelude (include ../../../preludes/self.journal).
- Verify closing timestamps and opening timestamps are correct (closing at 23:59:59, opening at 00:00:00).
- Validate and format (prefer
bun run format and bun run check).
- Commit using a suitable
chore(migration): header and include migration context in the commit message.
For detailed examples and edge cases, see .agents/instructions/developer-workflows.instructions.md and ./examples.md. (Examples and a short checklist are in examples.md.)
Do's and Don'ts
Do:
- Run for both
self.journal and self.alternatives.journal
- Create new directory/file if needed
- Include prelude in new journal
- Verify closing balances show
= 0.00 CURRENCY
- Run check and format after
Don't:
- Edit hledger close output extensively
- Forget prelude include
- Skip validation before commit
- Perform migration multiple times for same month
Reference Recent Examples
cat ledger/2025/2025-12/self.journal | tail -50 # View closing
cat ledger/2026/2026-01/self.journal | head -50 # View opening
