---

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

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

Prerequisites

• All transactions for previous month finalized
• Both self.journal and self.alternatives.journal need migration
• Ran python -m check successfully

Process

1. Run Migration Commands

Close both journal types:

Copy# Example: Close December 2025, prepare for January 2026
hledger close -f ledger/2025/2025-12/self.journal --migrate
hledger close -f ledger/2025/2025-12/self.alternatives.journal --migrate

Run separately—one per journal file.

2. Understand Output

hledger close --migrate generates two transactions:

1. Closing balances: Zeroes all accounts at month-end

   Copy2025-12-31 closing balances  ; time: 23:59:59
       assets:banks:<uuid>:HKD     -5000.00 HKD = 0.00 HKD
       ...
       equity:opening/closing balances
   

2. Opening balances: Re-establishes for new month

   Copy2026-01-01 opening balances  ; time: 00:00:00
       assets:banks:<uuid>:HKD      5000.00 HKD = 5000.00 HKD
       ...
       equity:opening/closing balances
   

3. Add Closing to Old Month

Copy closing balances to end of previous month journal.

4. Create New Monthly Journal

If new month directory doesn't exist:

Copymkdir ledger/2026/2026-01
New-Item ledger/2026/2026-01/self.journal

Include prelude:

Copyinclude ../../../preludes/self.journal

5. Add Opening to New Month

Copy opening balances to start of new month (after prelude).

6. Adjust Times if Needed

Verify dates/times are correct:

• Closing: last day of month at 23:59:59
• Opening: first day of month at 00:00:00

7. Validate

Copypython -m check
python -m format

8. Commit

Copygit commit -S -m "chore(migration): migrate journals to 2026-01"

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

Copycat ledger/2025/2025-12/self.journal | tail -50  # View closing
cat ledger/2026/2026-01/self.journal | head -50  # View opening

Related Documentation

• Architecture - Journal structure
• Common Workflows - Other workflows
• Editing Guidelines - Best practices