Furusato Nozei Management

This skill reads furusato nozei donation receipts, manages donation data, and calculates deduction amounts.

Load Settings (Run First)

Read the
```
shinkoku.config.yaml
```
file using the Read tool
If the file does not exist, guide the user to run the
```
/setup
```
skill and exit
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

After loading settings, read handover files to understand the results of previous steps.

Read
```
.shinkoku/progress/progress-summary.md
```
using the Read tool (if it exists)
Read the following handover files using the Read tool (if they exist):
- ```
.shinkoku/progress/01-setup.md
```
Utilize the read information in subsequent steps (avoid re-asking users)
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

Verify the existence of the file using

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

1-2. Image Reading

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

For a Single Receipt

Use the

/reading-receipt

skill to read the 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

If Matched: Adopt the result directly. Report "Results matched in two independent readings"

If Not Matched: 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

Extract the following information from the

---FURUSATO_RECEIPT_DATA---

block of the reading results:

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

Use the Glob tool to retrieve a list of receipt images (e.g.,
```
furusato_receipts/*.jpg
```
,
```
furusato_receipts/*.png
```
)

Verify the existence of each file using

shinkoku import furusato-receipt --file-path PATH

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
Compile the results of all receipts and present them to the user

1-3. Confirm with User

Display the extracted information as a list and confirm its accuracy. Reflect any corrections provided by the user.

Step 2: Register Donation Data

Once confirmed, register the data using

furusato.py add

bash

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

Format of the input JSON file:

json

{
  "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

During registration, confirm with the user: "Did you apply for the one-stop special treatment?"

Important Note: If you file a final tax return for side income, the one-stop special treatment will be invalidated. You need to declare the full amount as a donation deduction when filing your final tax return.

Step 3: Process Multiple Receipts Repeatedly

Ask the user: "Do you have other donation receipts?" If yes, repeat Steps 1-2.

Step 4: Aggregation and Deduction Limit Check

After registering all donation data, aggregate the data using

furusato.py summary

bash

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

Information to display:

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

If income information is available, estimate the limit using

tax_calc.py furusato-limit

bash

shinkoku tax furusato-limit --input FILE

If the limit is exceeded, display a warning: "Total donations exceed the estimated limit. The excess amount will be your out-of-pocket expense."

Step 5: Relationship with Final Tax Return

Explain the following:

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

Question Category	Reference File
Furusato nozei tax rules and calculation formulas	`references/furusato-tax-rules.md`
Limit amount, return gifts, timing, general consultation	`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

After presenting the summary, output the following files using the Write tool. This allows subsequent skills to inherit the results even if the session is interrupted or compacted.

Output Step-Specific File

Output to

.shinkoku/progress/05-furusato.md

in the following format:

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

If there are no donations (skipped), set status to

skipped

and write "Not applicable" in the content.

Update Progress Summary

Update

.shinkoku/progress/progress-summary.md

(create a new one if it does not exist):

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

After outputting the files, inform the user:

"Handover files have been saved to
```
.shinkoku/progress/
```
. Even if the session is interrupted, subsequent skills can inherit the results."
Guidance on next steps

furusato

NPX Install

Tags

SKILL.md Content (Chinese)

Furusato Nozei Management

Load Settings (Run First)

Load Progress Information

Step 1: Read Receipt Images

1-1. File Verification

1-2. Image Reading

For a Single Receipt

For Batch Processing of Multiple Receipts

1-3. Confirm with User

Step 2: Register Donation Data

Confirm One-Stop Special Application

Step 3: Process Multiple Receipts Repeatedly

Step 4: Aggregation and Deduction Limit Check

Estimate Deduction Limit

Step 5: Relationship with Final Tax Return

Reference File Reference Guide

Next Step Guidance

Output Handover Files

Output Step-Specific File

Update Progress Summary

Guidance After Output