monthly-migration

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