Furusato Nozei Management

Load Settings (Run First)

1. Read the

   shinkoku.config.yaml

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

   • db_path

     : Used for the

     --db-path

     argument of the CLI script (convert to absolute path based on CWD)

   • tax_year

     : Target fiscal year

   • furusato_receipts_dir

     : Storage directory for donation receipts (optional)

Load Progress Information

1. Read

   .shinkoku/progress/progress-summary.md

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

   • .shinkoku/progress/01-setup.md

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

Step 1: Read Receipt Images

1-1. File Verification

import_data.py furusato-receipt --file-path PATH

1-2. Image Reading

For a Single Receipt

/reading-receipt

amount

date

municipality_name

• Clearly indicate fields with discrepancies
• Provide three options via AskUserQuestion: Adopt A / Adopt B / Manual Input

---FURUSATO_RECEIPT_DATA---

• Municipality Name: Name of the city/town/village where the donation was made
• Prefecture Name: Prefecture of the donation recipient
• Donation Amount: Integer in yen
• Donation Date: Format YYYY-MM-DD
• Receipt Number: If available

For Batch Processing of Multiple Receipts

1. Use the Glob tool to retrieve a list of receipt images (e.g.,

   furusato_receipts/*.jpg

   ,

   furusato_receipts/*.png

   )
2. Verify the existence of each file using

   shinkoku import furusato-receipt --file-path PATH

3. Use the

   /reading-receipt

   skill to read each image file. Follow the skill's instructions to perform dual verification (compare results from two independent readings) and obtain the results.
   Result Comparison: Compare

   amount

   ,

   date

   , and

   municipality_name

   from both reading results for each file
   If Matched: Adopt the result directly. Report "Results matched in two independent readings"
   If Not Matched: For the mismatched file, present the original image path and both results to the user, and ask them to select the correct one:
   • Clearly indicate fields with discrepancies
   • Provide three options via AskUserQuestion: Adopt A / Adopt B / Manual Input
4. Compile the results of all receipts and present them to the user

1-3. Confirm with User

Step 2: Register Donation Data

furusato.py add

shinkoku furusato add --db-path DB --input FILE

{
  "fiscal_year": 2025,
  "municipality_name": "Municipality Name",
  "amount": 30000,
  "date": "2025-06-15",
  "municipality_prefecture": "Prefecture",
  "receipt_number": "Receipt Number",
  "one_stop_applied": false
}

Confirm One-Stop Special Application

Step 3: Process Multiple Receipts Repeatedly

Step 4: Aggregation and Deduction Limit Check

furusato.py summary

shinkoku furusato summary --db-path DB --fiscal-year YEAR [--estimated-limit N]

• Number of recipient municipalities and total donation amount
• Income deduction amount (total - 2,000 yen)
• Number of one-stop special applications
• Estimated deduction limit (if income information is available)

Estimate Deduction Limit

tax_calc.py furusato-limit

shinkoku tax furusato-limit --input FILE

Step 5: Relationship with Final Tax Return

• If you file a final tax return for side income, you cannot use the one-stop special treatment
• Declare the donation as a donation deduction (income deduction) in your final tax return
• Deduction from income tax = (total donations - 2,000) × income tax rate
• Deduction from resident tax is calculated separately (including special treatment amounts)

Reference File Reference Guide

references/furusato-tax-rules.md

references/furusato-consultation-guide.md

Next Step Guidance

• Proceed to calculate income tax using the

  income-tax

  skill (donation deductions will be automatically reflected)
• If you have other deductions (e.g., medical expense deduction), process those first

Output Handover Files

Output Step-Specific File

.shinkoku/progress/05-furusato.md

---
step: 5
skill: furusato
status: completed
completed_at: "{Current Date YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# Furusato Nozei Management Results

## List of Registered Donations

| Municipality Name | Prefecture | Amount | Donation Date | One-Stop |
|---------|---------|------|--------|------------|
| {Municipality Name} | {Prefecture} | {Amount} yen | {Date} | {Applied/Not Applied} |

## Aggregation

- Number of recipient municipalities: {Count}
- Total donation amount: {Total Amount} yen
- Deduction amount (total - 2,000 yen): {Deduction Amount} yen

## Comparison with Deduction Limit

- Estimated deduction limit: {Limit Amount} yen (if income information is available)
- Limit exceeded: {No/Yes (Excess amount: {Amount} yen)}

## Next Step

Proceed to income tax calculation with /income-tax

skipped

Update Progress Summary

.shinkoku/progress/progress-summary.md

• YAML frontmatter: fiscal_year, last_updated (current date), current_step: furusato
• Table: Update the status of all steps (set furusato to completed or skipped)
• Guidance on next steps

Guidance After Output

• "Handover files have been saved to

  .shinkoku/progress/

  . Even if the session is interrupted, subsequent skills can inherit the results."
• Guidance on next steps