# Monthly Migration

> 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.

- Skill: `polyipseity/monthly-migration` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add polyipseity/monthly-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/polyipseity/monthly-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: polyipseity (https://skillmd.com/u/polyipseity)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/polyipseity/monthly-migration

---




# 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

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