journal

Journal Entry & Ledger Management

A skill that imports data from CSV, receipts, and invoices, and registers journal entries after user confirmation. Ledger initialization, and searching, modifying, and deleting journal entries are also handled by this skill.

CLI script

This skill uses the following CLI scripts:

• Ledger Management: shinkoku ledger <subcommand> [args]
• Data Import: shinkoku import <subcommand> [args]

All commands output JSON to stdout. Input is passed via command-line arguments or --input <json_file> .

Loading settings (execute first)

1. shinkoku.config.yaml Read with the Read tool
2. If the file does not exist, /setup guide the user to run the skill and exit
3. Understand the setting values and convert relative paths to absolute paths based on the CWD:
   • db_path: CLI script --db-path used for the argument
   • output_dir: base directory for output such as progress files
   • Each directory: used when referencing files

Path resolution example (db_path)

config の db_path が ./shinkoku.db で CWD が /home/user/tax-2025/ in the case of, pass the absolute path /home/user/tax-2025/shinkoku.db を --db-path to the CLI script.init, journal-add, journal-batch-add, search, journal-update, journal-delete Use the same absolute path for all.

Loading progress information

After loading the settings, load the handover file to understand the results of the previous step.

1. .shinkoku/progress/progress-summary.md Read with the Read tool (if it exists)
2. Read the following handover files with the Read tool (if they exist):
   • .shinkoku/progress/01-setup.md
3. Use the loaded information in subsequent steps (avoid re-asking the user)
4. If the file does not exist, skip it and confirm the necessary information directly with the user

Basic Policy

• The basic flow is three steps: CSV import → user confirmation → journal entry registration
• Accounts comply with the master data in references/account-master.md
• Always confirm the contents with the user before registering journal entries (do not register automatically)
• Accurately set the consumption tax category (taxable/non-taxable/out of scope/exempt)
• Verify the consistency of dates, amounts, and accounts before calling the tool
• When an error occurs, communicate the error contents in clear Japanese and propose a correction method

Checking Prerequisites

Before starting journal entry input, confirm the following:

1. Whether the ledger has been initialized: if not initialized, init guide initialization with the command
2. Fiscal year: confirm the target fiscal year (e.g., 2025)
3. Blue return or white return: the bookkeeping method changes depending on whether it is double-entry bookkeeping (blue return ¥650,000 deduction) or simplified bookkeeping

Step 1: Ledger Initialization

Initialize the books on first use or when starting a new fiscal year.

init command

shinkoku ledger init \
  --db-path /path/to/shinkoku.db \
  --fiscal-year 2025

• Confirm the fiscal year and save destination path with the user before executing
• If an existing database is present, display an overwrite warning
• After initialization is complete, confirm that the chart of accounts master has been registered

Step 2: Data Import

Select the appropriate import tool according to the format of the transaction data the user has.

2-1. CSV Import (csv command)

Import credit card statements, bank transaction statements, accounting software export data, etc.

shinkoku import csv \
  --file-path /path/to/transactions.csv

Return value (JSON):

• headers: List of detected column headers
• rows: Data for each parsed row
• encoding: Automatically detected encoding
• row_count: Number of rows

Post-import processing steps:

1. Display a preview of the imported data (first 5–10 rows)
2. Identify the date, amount, and description columns and confirm with the user
3. Estimate the account for each row and present candidates
4. State the basis for the estimate (e.g., keyword match in the description)
5. Once the user confirms or corrects the account, convert to journal entry data

Account estimation rules:

• If the description contains "train," "bus," "taxi," or "JR" → Travel and Transportation Expenses (5130)
• If the description contains "Amazon" or "Yodobashi" → Supplies Expense (5190) or Office Supplies Expense (5360)
• If the description contains "Docomo," "au," or "SoftBank" → Communication Expenses (5140)
• If the description contains "Tokyo Electric Power," "gas," or "water" → Utilities Expenses (5120)
• If the description contains "rent" or "lease" → Rent and Land Lease (5250)
• If it cannot be estimated, present a list of candidates as "Unknown" and ask the user to select

2-2. Receipt Import (receipt command)

Extract data via OCR from image files of paper receipts and invoices.

shinkoku import receipt \
  --file-path /path/to/receipt.jpg

Important: Delegate image reading to the corresponding reading- skill.*

For a single receipt

1. receipt command to check that the file exists

2. To read the image file, use the /reading-receipt skill. Follow the skill's instructions and perform dual verification (cross-checking two independent reading results) to obtain the result.

   Result cross-check: From both reading results, total_amount, date, vendor compare

   If they match: Adopt as is. Report "The results matched in two independent readings"

   If they do not match: Present the original image path and both results to the user and have them select the correct one:

   • Clearly indicate the fields with discrepancies
   • Present the three choices—Adopt A / Adopt B / Manual input—using AskUserQuestion

3. Reading result's ---RECEIPT_DATA--- Analyze the contents of the block

4. Display the date, amount, and store name to the user and confirm they are correct

5. Estimate the account category from the items

6. Confirm whether household expense allocation is necessary (e.g., for a home office)

7. After confirmation, convert to journal entry data

Batch processing of multiple receipts

1. Get the list of receipt images with the Glob tool (e.g., receipts/*.jpg, receipts/*.png）

2. receipt command to verify the existence of each file

3. For reading image files, use the /reading-receipt skill. Follow the skill's instructions and perform dual verification (cross-checking two independent reading results) to obtain the results.

   Result verification: For each file, the total_amount, date, vendor of both reading results is compared

   If they match: Adopt as is. Report "The results matched in two independent readings"

   If they do not match: Present the original image path and both results to the user for the mismatched files, and have them choose the correct one:

   • Clearly indicate the fields with discrepancies
   • Present the three choices—Adopt A / Adopt B / Manual input—using AskUserQuestion

4. Present the results for each receipt together to the user

5. Estimate the account category for each receipt and have the user confirm them in a list

6. After confirmation, register them all at once with thejournal-batch-add command

2-3. Invoice import (invoice command)

Extract text from a PDF invoice.

shinkoku import invoice \
  --file-path /path/to/invoice.pdf

Return value (JSON):

• vendor: Billing party
• date: Invoice date
• due_date: Payment due date
• amount: Invoice amount
• tax_amount: Consumption tax amount
• items: Line items
• raw_text: Extracted raw text

For image files: OCR reading

extracted_text If is empty (image file or scanned PDF), for reading the image use the /reading-invoice skill. Follow the skill's instructions and perform dual verification (cross-checking two independent reading results) to obtain the results.

Result verification: From both reading results, total_amount, tax_amount, date, vendor is compared

If they match: Adopt as is. Report "The results matched in two independent readings"

If they do not match: Present the original image path and both results to the user, and have them choose the correct one:

• Clearly indicate the fields with discrepancies
• Present the three choices—Adopt A / Adopt B / Manual input—using AskUserQuestion

Post-import procedure:

1. Display the extraction results and confirm that the amount, date, and vendor are correct
2. Check whether an invoice number (T + 13 digits) is present
3. Check the consumption tax rate category (10% / 8% reduced rate)
4. Confirm whether to record accounts payable on an accrual basis or handle it on a cash basis
5. After confirmation, convert to journal entry data

Step 2.5: Duplicate check (during CSV import)

Incorporate a duplicate check into the CSV import flow:

1. File duplicate check: check-imported Check the file hash with the command

   shinkoku import check-imported \
     --db-path DB --file-path /path/to/file.csv
   

   • If it has already been imported, warn the user and confirm whether they want to re-import
2. Automatic check at journal entry registration: journal-batch-add automatically detects duplicates
   • exact (exact match): Block registration and display the existing journal ID
   • similar (similar): Display a warning and ask the user for confirmation
   • If the user answers "register", --force and re-run with
3. Import record: After successful registration,record-source record the import history with the command

   shinkoku import record-source \
     --db-path DB --file-path /path/to/file.csv --source-type csv
   

Duplicate check before filing

Before closing the books, check-duplicates run the command to list pairs of journal entries suspected of being duplicates.

shinkoku ledger check-duplicates \
  --db-path DB --fiscal-year 2025

After confirming with the user, delete unnecessary duplicates with the journal-delete command.

Step 3: Registering journal entries

Register the data confirmed by the user in the ledger.

3-1. Registering a single journal entry (journal-add）

# journal.json に JournalEntry を JSON で記述
shinkoku ledger journal-add \
  --db-path DB --fiscal-year 2025 --input journal.json

journal.json format:

{
  "date": "2025-01-15",
  "description": "摘要テキスト",
  "lines": [
    {"side": "debit", "account_code": "5200", "amount": 1000},
    {"side": "credit", "account_code": "1100", "amount": 1000}
  ]
}

3-2. Batch journal entry registration (journal-batch-add）

Used when registering multiple journal entries at once, such as via CSV import.

# entries.json に JournalEntry の配列を記述
shinkoku ledger journal-batch-add \
  --db-path DB --fiscal-year 2025 --input entries.json [--force]

Items to confirm before registration:

• Present the number of entries and total amount as a summary
• Confirm with "The following N journal entries will be registered. Is that OK?"
• After obtaining the user's explicit approval, journal-batch-add run

Validation rules at registration

Validate the following and warn before registration if there are any deficiencies:

1. Date validity: Whether it is within the fiscal year range (e.g., 2025-01-01 to 2025-12-31)
2. Existence of account: Whether the debit and credit account codes exist in the master
3. Positive amount: Whether the amount is a positive integer
4. Debit-credit balance: For compound journal entries, whether total debits = total credits
5. Consistency of consumption tax category: Whether the combination of the account's tax_category and tax rate is valid

Step 4: Searching journal entries

Search registered journal entries.

search command

# search_params.json に JournalSearchParams を記述
shinkoku ledger search \
  --db-path DB --input search_params.json

search_params.json format:

{
  "fiscal_year": 2025,
  "date_from": "2025-01-01",
  "date_to": "2025-03-31",
  "account_code": "5200",
  "description_contains": "Amazon"
}

Displaying search results:

• Display the search results as a list ordered by date
• Display journal_id for each journal entry (used for modification/deletion)
• Display the total amount at the end

Step 5: Modifying/deleting journal entries

5-1. Modifying a journal entry (journal-update）

shinkoku ledger journal-update \
  --db-path DB --fiscal-year 2025 --journal-id 42 --input updated.json

• Display the difference before and after modification, then confirm
• Recommend adding the reason for correction to the summary

5-2. Deleting a journal entry (journal-delete）

shinkoku ledger journal-delete \
  --db-path DB --journal-id 42

• Display and confirm the journal entry contents to be deleted
• Perform a final confirmation: "This journal entry will be deleted. Are you sure?"
• Alert the user that deletion cannot be undone

Common journal entry patterns

Recording sales

借方: 売掛金(1010) / 貸方: 売上(4001)   金額: 110,000円  税率: 10%
摘要: ○○社 Webサイト制作費 請求書No.2025-001

Paying expenses (from a business account)

借方: 消耗品費(5190) / 貸方: 普通預金(1002)  金額: 5,500円  税率: 10%
摘要: Amazon ワイヤレスキーボード

When business expenses are paid from a personal wallet

借方: 旅費交通費(5130) / 貸方: 事業主借(3010)  金額: 1,200円  税率: 10%
摘要: JR 新宿→渋谷 打ち合わせ往復

When business funds are used for personal purposes

借方: 事業主貸(1200) / 貸方: 普通預金(1002)  金額: 50,000円
摘要: 生活費引き出し

Guidance for the next step

Once journal entry input is complete, provide the following guidance:

• settlement Perform closing adjustments and create financial statements with the skill
• trial-balance Verify the trial balance with the command to check for missing journal entries:

  shinkoku ledger trial-balance \
    --db-path DB --fiscal-year 2025
  

• Proceed to closing processing after confirming that all transactions have been registered

Output of the handover document

After presenting the summary, output the following files with the Write tool. This allows results to be carried over to the next step even if the session is interrupted or Compact occurs.

Output of files by step

.shinkoku/progress/04-journal.md Output in the following format:

---
step: 4
skill: journal
status: completed
completed_at: "{当日日付 YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# 仕訳入力・帳簿管理の結果

## インポート済みソース

| ソース名 | 件数 | インポート日 |
|---------|------|------------|
| {CSV名やレシート等} | {件数} | {日付} |

## 登録済み仕訳

- 総仕訳件数: {件数}件

## 主要勘定科目の残高（試算表スナップショット）

| 勘定科目 | コード | 残高 |
|---------|--------|------|
| {科目名} | {コード} | {残高}円 |
（売上、主要経費、現預金、売掛金、買掛金など主要科目を記載）

## 重複チェック結果

- チェック実施: {済み/未実施}
- 重複の疑い: {なし/あり（件数）}

## 未処理の項目

- {あれば記載、なければ「なし」}

## 次のステップ

/settlement で決算整理・決算書作成を行う

Updating the progress summary

.shinkoku/progress/progress-summary.md Update (create new if it does not exist):

• YAML frontmatter: fiscal_year, last_updated (current date), current_step: journal
• Table: Update the status of all steps (set journal to completed)
• Describe guidance for the next step

Guidance after output

After outputting the files, tell the user the following:

• "The handover document has been saved to .shinkoku/progress/ . Even if the session is interrupted, the results can be carried over to the next skill."
• Guidance for the next step