edit-journals

name	edit-journals
description	Edit hledger journal files following best practices and conventions. Includes prelude includes, balance assertions, tagging, formatting, and validation procedures with anti-patterns to avoid.

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:

2025-01-19 Insurance Adjustment  ; reason: coverage review
    liabilities:accrued expenses:insurances:life:<uuid>   -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:

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:

# ❌ 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:

# ❌ 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 affect all monthly journals:

# 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:

# ❌ 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:

# ❌ Invalid
account assets:cash on hand:HKD

# ✅ Valid
account assets:cash:HKD

Spaces break account parsing.

Editing Workflow

# 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 - Transaction structure and formatting
• Account Hierarchy & Meanings - All available accounts
• Security Practices - Handling confidential data
• Common Workflows - Other practical procedures
• Continuous Learning & Common Pitfalls - 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.