Document Gathering Guide

Loading Settings (Execute First)

1. Load

   shinkoku.config.yaml

   using the Read tool
2. If the file does not exist, guide the user to run the

   /setup

   skill and exit
3. Understand the configuration values, and convert relative paths to absolute paths based on the CWD:

   • db_path

     : Used for the

     --db-path

     argument in the CLI script

   • output_dir

     : Base directory for outputting progress files, etc.
   • Each directory: Used when referencing files

Loading Progress Information

1. Load

   .shinkoku/progress/progress-summary.md

   using the Read tool (if it exists)
2. Load the following handover files using the Read tool (if they exist):

   • .shinkoku/progress/02-assess.md

3. Utilize the loaded information in subsequent steps (to avoid re-asking the user)
4. If the files do not exist, skip this step and directly confirm the necessary information with the user

Basic Guidelines

• Start after confirming the assessment results from the assess skill (whether income tax, consumption tax, and resident tax filings are required)
• If there are no assessment results, guide the user with: "First, let's determine the type of filing using the assess skill"
• Classify documents into "Mandatory", "Only for applicable users", and "Optional (convenient to have)" when presenting them
• Clearly indicate where to obtain each document and the estimated time required to obtain it
• Prioritize guiding users to obtain documents that are available as electronic data (e-Tax, My Number Portal)

Step 1: Confirm Filing Type

• Whether income tax final filing is required and its type (normal/refund filing)
• Whether consumption tax filing is required and the method (20% special measure/simplified taxation/standard taxation)
• Whether blue return is applicable
• Types of deductions applicable

Step 2: Present Document Checklist

2-1. Common for all filers (Mandatory documents)

2-2. If you have salary income

2-3. If you have business income (side jobs, freelancing)

import_data.py csv

import_data.py payment-statement

Collecting Payment Slips

• Source: Business partner (corporation) that paid the remuneration
• Issuance period: By the end of January of the following year
• Items to confirm:
  • Payment amount (total annual remuneration)
  • Withholding tax amount
  • Category (remuneration/fee/contract fee, etc.)
• Importing with shinkoku:
  1. Extract data from PDF/images using

     import_data.py payment-statement --file-path PATH

  2. Register by business partner with

     ledger.py add-business-withholding --db-path DB --input FILE

  3. The total withholding tax amount will be deducted in the final tax return
• Note: There is no legal obligation to issue payment slips (but there is an obligation to submit them to the tax office). If you do not receive it, contact the business partner or aggregate from your own invoice copies, etc.

2-4. If you need to file consumption tax

2-5. Documents required for various deductions

Medical Expense Deduction

Hometown Tax Donation (Donation Deduction)

Housing Loan Deduction (First Year)

Social Insurance Premium Deduction

Life Insurance Premium / Earthquake Insurance Premium Deduction

iDeCo / Small Business Mutual Aid

Self-Medication Tax System (Only for applicable users)

2-6. If you have stock, FX, or virtual currency transactions

Stock Transactions

FX Transactions

Virtual Currency (Cryptocurrency)

2-7. If you paid fees to a tax accountant, etc.

Step 3: Timeline for Document Collection

Schedule for Final Tax Return for Reiwa 7 (2025)

【October - November】Period for receiving various deduction certificates
  □ Life Insurance Premium Deduction Certificate
  □ Earthquake Insurance Premium Deduction Certificate
  □ National Pension Premium Deduction Certificate
  □ iDeCo/Small Business Mutual Aid Contribution Payment Certificate
  □ Certificate of year-end balance of housing loan

【December - January】Year-end adjustment and withholding slips
  □ Receive withholding slip (from employer)
  □ Receive Hometown Tax donation receipt

【January - February】Filing preparation
  □ Receive medical expense notice (from health insurance association)
  □ Download annual credit card statement CSV
  □ Organize expense receipts and payment slips
  □ Obtain registered matters certificate (first year of housing loan deduction)
  □ Receive Annual Transaction Report for Specific Account (from securities company, only applicable users)
  □ Receive FX Annual Profit and Loss Report (from FX broker, only applicable users)
  □ Receive Cryptocurrency Annual Transaction Report (from exchange, only applicable users)
  □ Aggregate self-medication OTC purchase receipts (only applicable users)

【February 16 - March 15】Final Tax Return Period
  * Refund filings can be submitted from January 1
  * Consumption tax filing deadline is March 31

Step 4: Guidance on Obtaining Electronic Data

Information available via My Number Portal linkage

• Medical expense notice information
• Consolidated certificate for Hometown Tax donation deduction
• Life Insurance Premium Deduction Certificate (only for compatible insurance companies)
• Certificate of year-end balance of housing loan (only for compatible financial institutions)
• Withholding slips for public pensions, etc.

Documents that can be directly created and submitted via e-Tax

• Final Tax Return (Form 1, Form 2, Form 3, Form 4)
• Blue Return Financial Statements
• Consumption Tax Return
• Medical expense deduction details
• Calculation details for special deduction on housing loans

Step 5: Handling Missing Documents

• Lost withholding slip: Request reissuance from your employer (companies have an obligation to issue it)
• Lost deduction certificate: Request reissuance from the issuer (insurance company, etc.)
• Lost receipt: Bank withdrawal slips may be used as a substitute (subject to tax office judgment)
• Registered matters certificate: Can be obtained at any time from the Legal Affairs Bureau (fee of 600 yen)

Step 6: Confirming Collection Completion and Next Steps

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Document Collection Checklist - Collection Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[✓] My Number Card
[✓] Withholding slip
[✓] Credit card statement CSV
[✓] Expense receipts and payment slips
[✓] Hometown Tax donation receipt
[✓] Housing loan year-end balance certificate
[✓] Registered matters certificate
[ ] Medical expense notice (to be added upon arrival in February)
[✓] Annual Transaction Report for Specific Account (only applicable users)
[✓] FX Annual Profit and Loss Report (only applicable users)
[✓] Cryptocurrency Annual Transaction Report (only applicable users)
[✓] Self-medication purchase receipts (only applicable users)

■ Next Steps:
  → Start journal entry using the journal skill
  → Consult about deductions using the tax-advisor skill
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Outputting Handover Documents

Outputting Step-specific Files

.shinkoku/progress/03-gather.md

---
step: 3
skill: gather
status: completed
completed_at: "{current date YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# Document Collection Results

## Required Document Checklist

- [x] {Name of collected document}
- [ ] {Name of uncollected document}
(List all documents according to filing type with their statuses)

## List of Collected Files

- {Document name}: {File path}
(Record the file path of each collected document)

## Response Policy for Uncollected Documents

- {Name of uncollected document}: {Response policy (e.g., to be added upon arrival in February, requesting reissuance from employer)}

## Next Steps

Start journal entry with /journal

Updating Progress Summary

.shinkoku/progress/progress-summary.md

• YAML frontmatter: fiscal_year, last_updated (current date), current_step: gather
• Table: Update the status of all steps (set gather to completed)
• Include guidance on the next steps

Guidance After Output

• "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 on the next steps

Disclaimer

• The necessity of documents may vary depending on individual circumstances
• If you have any questions, we recommend confirming with the tax office
• Reference: skills/tax-advisor/reference/disclaimer.md