# Edit Journals > Edit hledger journal files following best practices and conventions. Includes prelude includes, balance assertions, tagging, formatting, and validation procedures with anti-patterns to avoid. - Skill: `polyipseity/edit-journals` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add polyipseity/edit-journals` - Raw SKILL.md: https://api.skillmd.com/api/skills/polyipseity/edit-journals/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/edit-journals --- # Edit Journals Skill **Note:** Use full path `ledger/[year]/[year]-[month]/[name].journal` (e.g., `ledger/2024/2024-01/self.journal`). This skill provides comprehensive guidance for editing hledger journal files while maintaining consistency, validity, and adherence to project conventions. ## When to Use This Skill - Adding, modifying, or removing transactions - Creating new monthly journals - Editing prelude definitions - Maintaining opening/closing balances - Correcting historical entries - Updating confidential mappings ## Best Practices — At a Glance - Include the appropriate prelude at the top of every monthly journal (`include ../../../preludes/self.journal` or `self.alternatives.journal`). - Use balance assertions (`= balance CURRENCY`) for bank reconciliations, transfers, and loans where applicable. - Always include required tags (`timezone: UTC+08:00`, `activity`, `time`); use `duration`, `food_or_drink`, `item`, `location` when relevant. - Format and validate using canonical scripts: `bun run format` then `bun run check` (see `.agents/instructions/developer-workflows.instructions.md`). Fix all errors before committing. - Preserve monthly opening/closing patterns for reconciliation and migration. - If you correct a previous month's closing balances after the next month's journal already exists, update the next month’s opening balances to match the corrected closing balances. - When troubleshooting with temporary journals, create the temp file in the same month directory or run hledger from that directory so relative `include` paths resolve. - The formatter sorts comment properties; keep transaction comment keys ordered and concise. For detailed examples and edge cases, see `.agents/instructions/transaction-format.instructions.md` and `.agents/instructions/editing-guidelines.instructions.md`. ### 8. Document Complex Transactions For non-obvious transactions, add explanatory comments: ```hledger 2025-01-19 Insurance Adjustment ; reason: coverage review liabilities:accrued expenses:insurances:life: -100.00 HKD equity:unaccounted 100.00 HKD ``` Helps future understanding of why transactions were recorded. ## Anti-Patterns to Avoid **For a comprehensive list of anti-patterns across all skills, see `.agents/instructions/continuous-learning.instructions.md`** (consolidated guide to pitfalls discovered through repeated use). Below are the most critical patterns specific to journal editing: ### ❌ Do Not Edit Year-Level Journals Manually The year-level `ledger/YYYY/self.journal` files should **only** contain include directives: ```hledger include 2025-01/self.journal include 2025-02/self.journal include 2025-03/self.journal ... ``` **Never add transactions here.** Transactions belong in monthly journals. **Why?** Year-level files are for organization only. Adding transactions here breaks the hierarchical structure. ### ❌ Do Not Commit Without Validation Always run `bun run format` then `bun run check` before committing. Invalid journals cause downstream problems. ### ❌ Do Not Use Inconsistent Formatting Maintain consistent decimal and spacing: ```hledger # ❌ Inconsistent 2025-01-19 Payment expenses:food 50 HKD # Missing decimal assets:cash -50.0 HKD # Only 1 decimal place # ✅ Consistent (after python -m format) 2025-01-19 Payment expenses:food 50.00 HKD assets:cash -50.00 HKD ``` Always run `python -m format` to normalize. ### ❌ Do Not Create Transactions Without Timezone Tags Every transaction must include timezone information: ```hledger # ❌ Missing timezone 2025-01-19 Cafe ; activity: eating, time: 12:30 # ✅ Includes timezone 2025-01-19 Cafe ; activity: eating, time: 12:30, timezone: UTC+08:00 ``` Timezone tags are essential for proper time tracking. ### ❌ Do Not Modify Prelude Definitions Lightly Changes to [preludes/self.journal](../../../preludes/self.journal) affect **all** monthly journals: ```hledger # Changes here impact all journals! account assets:cash commodity HKD payee Example Payee tag activity ``` **Before modifying prelude definitions:** 1. Understand the global impact 2. Check how many journals reference the definition 3. Test validation across all journals 4. Document the change in commit message ### ❌ Do Not Leave Unencrypted Confidential Files Never commit unencrypted `private.yaml`. See `security.instructions.md`. ### ❌ Do Not Remove Existing Accounts or Payees Once an account or payee is used, removing it breaks historical references: ```hledger # ❌ Bad: Removes existing definition # (delete from preludes/self.journal) account assets:cash # ✅ Good: Keep definitions even if unused # Let check script find any unused definitions separately ``` Payees and accounts are part of ledger history. ### ❌ Do Not Use Spaces in Account Names Account paths must use colons, not spaces: ```hledger # ❌ Invalid account assets:cash on hand:HKD # ✅ Valid account assets:cash:HKD ``` Spaces break account parsing. ## Editing Workflow ```powershell # 1. Make edits to journal files # 2. Format bun run format # 3. Validate bun run check # 4. If edited private.yaml: bun run encrypt # 5. Review and commit git status && git diff git add . && git commit -S -m "ledger(self.journal): add N transaction(s)" ``` ## Common Editing Tasks ### Adding a New Transaction 1. Find recent similar transaction as template 2. Copy template and adjust values 3. Add comprehensive tags 4. Run `python -m format` 5. Verify with `python -m check` 6. Commit ### Adding a New Merchant/Payee 1. Add payee to `preludes/self.journal` in alphabetical order 2. If confidential, add to `private.yaml` and encrypt 3. Run `python -m format` and `python -m check` 4. Commit ### Correcting Historical Transaction 1. Find the transaction in appropriate monthly journal 2. Edit values and/or tags 3. If correction affects balances, update subsequent balance assertions 4. Run `python -m format` and `python -m check` 5. Commit with explanatory message ## Related Documentation - [Transaction Format Conventions](../../instructions/transaction-format.instructions.md) - Transaction structure and formatting - [Account Hierarchy & Meanings](../../instructions/account-hierarchy.instructions.md) - All available accounts - [Security Practices](../../instructions/security.instructions.md) - Handling confidential data - [Common Workflows](../../instructions/common-workflows.instructions.md) - Other practical procedures - [Continuous Learning & Common Pitfalls](../../instructions/continuous-learning.instructions.md) - Lessons learned and anti-patterns to avoid ## Lessons Learned See `./lessons.md` for active learnings and integration pointers. For consolidated insights across all skills (replaces scattered lessons.md), see `.agents/instructions/continuous-learning.instructions.md`: - **Most critical:** Running scripts from wrong directory (working directory is the #1 error) - **Payee/account ordering:** Must stay in strict lexicographical order; proactively correct during edits - **Balance assertions:** Use on sensitive postings; closing transactions must assert all accounts to zero - **Format-before-check:** Always run `bun run format` before `bun run check` to reduce noise When adding entries to `./lessons.md`, keep them brief and integrate into `SKILL.md` main sections, theme files, or `examples.md` after resolving the issue.