income-tax

Income Tax Calculation (所得税計算)

A skill to calculate the income tax amount from business income and various deductions. It assumes that the preparation of financial statements has been completed with the settlement skill. The calculation results are entered into the /e-tax skill (Claude in Chrome) in the e-Tax preparation corner for tax returns, etc.

Loading settings (execute first)

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

Path resolution example

config の db_path が ./shinkoku.db で CWD が /home/user/tax-2025/ In the case of:

shinkoku tax calc-income --input /home/user/tax-2025/output/income_input.json

Loading progress information

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

.shinkoku/progress/progress-summary.md Read with the Read tool (if it exists)
Read the following handover files with the Read tool (if they exist):
- .shinkoku/progress/06-settlement.md
- .shinkoku/progress/02-assess.md
- .shinkoku/progress/05-furusato.md
Use the loaded information in subsequent steps (avoid re-asking the user)
If the file does not exist, skip it and confirm the necessary information directly with the user

Basic policy

Confirm that the blue return financial statements have been completed with the settlement skill before starting
Proceed in the order of income calculation → deduction calculation → tax amount calculation
Present the calculation results of each step to the user and obtain confirmation
Set the values correctly in each field of references/form-b-fields.md
Strictly observe the rounding rules:
- Taxable income: Round down to the nearest 1,000 yen (Article 118 of the Act on General Rules for National Taxes)
- Special income tax for reconstruction: Round down to the nearest 1 yen (Article 13 of the Act on Special Measures for Securing Financial Resources for Reconstruction)
- ㊺ Income tax and special income tax for reconstruction: No rounding
- Tax amount to be paid (only in the case of payment): Round down to the nearest 100 yen (Article 119 of the Act on General Rules for National Taxes)
- Refund: In units of 1 yen, no rounding down (Article 120 of the Act on General Rules for National Taxes)

Confirmation of preconditions

Before starting the income tax calculation, confirm the following:

Whether the blue return financial statements have been completed: Check the output of the settlement skill
Loading the taxpayer profile: uv run shinkoku profile --config {config_path} Obtain taxpayer information from config with
- Name, address, tax office → Used for input into the e-Tax preparation corner for tax returns, etc.
- Status as widow/single parent, disabled person, working student → Used for calculating personal deductions
Income other than business income: If there is employment income, miscellaneous income, dividend income, occasional income, etc., collect the information
Withholding slip: If there is employment income, guide the user to import it
Application status of various deductions: Comprehensively check for applicable deductions
Estimated tax prepayment amount: Obtain the estimated tax prepayment amount already confirmed in assess
- If unconfirmed, determine it from the previous year's final tax return (field ㊺)
- Manage the estimated tax prepayment amount separately from the withholding tax amount
Confirmation of separate taxation: Separate taxation for stocks and FX (Form 3) is out of scope. If applicable, guide the user to consult a tax accountant

Mandatory confirmation checklist (cannot be skipped)

Before starting the income tax calculation, verify that the following items areall confirmed. For items not listed in the config or handover document, confirm directly with the user before proceeding.

Family structure: Have you confirmed whether there is a spouse and whether there are dependent relatives?
- Unconfirmed → Confirm with the user and register the details in step 1.5
- Confirmed (not applicable) → Step 1.5 can be skipped
Housing loan deduction: Have you confirmed whether it applies?
- Unconfirmed → Confirm with the user
- Applicable (first year) → Create the statement in step 3.7
Estimated tax prepayment: Have you confirmed whether it applies and the amount?
- Unconfirmed → Ask the user to determine it from the previous year's final tax return (field ㊺)
- Amount not finalized → estimated_tax_payment Do not proceed until the correct value can be set in the parameters

Step 1: Importing the withholding slip

If there is employment income, import the data from the withholding slip.

`import_data.py import-withholding` Call of

shinkoku import import-withholding --input withholding_input.json

Input JSON:

{
  "file_path": "path/to/withholding_slip.pdf"
}

Output:

{
  "payer_name": "支払者名",
  "payment_amount": 5000000,
  "deduction_amount": 3560000,
  "income_tax_withheld": 100000,
  "social_insurance": 700000,
  "life_insurance": 50000,
  "spouse_deduction": 0
}

For image files: OCR reading

extracted_text If is empty (image file or scanned PDF), use the /reading-withholding skill to read the image. Follow the skill instructions and obtain the result by performing dual verification (cross-checking two independent reading results).

Result verification: Compare payment_amount, withheld_tax, social_insurance from both reading results

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

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 options Adopt A / Adopt B / Manual input using AskUserQuestion

Post-import verification (mandatory):

To verify the consistency of the OCR results, cross-check the "Total amount of income deductions" against the sum of each breakdown:

検算: 所得控除の額の合計額 ≟ 社会保険料等の金額          ← 小規模企業共済等掛金を含む（内数）
                            + 生命保険料の控除額
                            + 地震保険料の控除額
                            + 配偶者（特別）控除の額
                            + 扶養控除額                ← 人数×単価から算出（特定63万/老人48万or58万/その他38万）
                            + 障害者控除                ← 人数×単価から算出（一般27万/特別40万/同居特別75万）
                            + 寡婦控除（27万）またはひとり親控除（35万） ← 該当時
                            + 勤労学生控除（27万）       ← 該当時
                            + 基礎控除の額              ← 源泉徴収票の記載額を使用。未記載なら所得と年度から算出

Note:

"(Of which, amount of small and medium enterprise mutual aid, etc. premiums)" is theincluded amount. If added separately, it would result in double counting
The dependent deduction and disability deduction are entered in the number-of-persons column rather than the amount column, so calculate as number of persons × unit amount
For the basic deduction amount, use the value stated on the withholding tax slip if available. If not stated, calculate according to total income and tax year (Reiwa 7: 580,000 yen + additions, up to 950,000 yen; Reiwa 8 and 9: 620,000 yen + additions, up to 1,040,000 yen; Reiwa 10 onward: 620,000 yen + additions, 990,000 yen only if 1,320,000 yen or less)
If they match: Adopt them assuming the OCR accuracy of each field has been confirmed
If they do not match: Show the difference and present to the user which fields may have been misread. Correct them by comparing against the original image

Other items to confirm:

If there are multiple employers, import the data for each company
Confirm the deductions already applied in the year-end adjustment and determine whether there are any additional deductions

Step 1.5: Confirmation of dependent relatives and spouse information

Before calculating income deductions, collect information on dependent relatives. First check the data already registered in the DB, and if anything is missing, enter it additionally.

Loading from the DB

ledger.py get-spouse --db-path DB_PATH to obtain spouse information (if registered)
ledger.py list-dependents --db-path DB_PATH to obtain the list of dependent relatives (if registered)

Items to confirm if not registered

Spouse: Confirm whether there is a spouse and the spouse's annual income amount
- Income of 480,000 yen or less → Spouse deduction (380,000 yen)
- Income over 480,000 yen and up to 1,330,000 yen → Special spouse deduction (graduated)
- Taxpayer's income over 10,000,000 yen → No spouse deduction
- After confirmation, ledger.py set-spouse --db-path DB_PATH --input spouse.json register in the DB
Dependent relatives: Collect the following information
- Name, relationship, date of birth, annual income, presence of disability, whether living together
- Under 16 years old: No dependent deduction (eligible for child allowance)
- 16 years old or older: General dependent 380,000 yen
- 19 years old or older and under 23: Specified dependent 630,000 yen
- 70 years old or older: Elderly dependent 480,000 yen (580,000 yen if living together)
- After confirmation, ledger.py add-dependent --db-path DB_PATH --input dependent.json register each person in the DB
Collection of My Number(required to be stated in Part 2 of Form B):
- Spouse's My Number (12 digits)
- My Numbers of all dependent relatives (16 years old or older)
- My Numbers of children under 16 years old (required for stating matters related to resident tax)
- Handling caution: Store in the DB, but do not display in tool output or logs
Confirmation of business dedicated workers:
- If the spouse is receiving salary as a blue-return business dedicated worker → Not eligible for the spouse deduction
- If a dependent relative is a blue-return business dedicated worker or white-return business dedicated worker → Not eligible for the dependent deduction
- If applicable, exclude from the deduction calculation and clearly indicate this to the user
Disability deduction: If a dependent relative has a disability
- Ordinary disability: 270,000 yen, Special disability: 400,000 yen, Special disability living together: 750,000 yen

Important: Be sure to register dependent relatives under age 16 as well

Children under age 16 are not eligible for the dependent deduction, but they must be listed on the return for the following reasons:

Determination of the non-taxable limit for resident tax (the number of dependents includes those under age 16)
Determination of non-taxation of the per-capita portion of resident tax
Entry in Form B, Page 2, "Matters concerning resident tax - Dependent relatives under age 16"

ledger.py add-dependent When registering with , be sure to register even those under age 16 without skipping.

Step 1.6: Confirmation of iDeCo and small business mutual aid

If you have a premium payment certificate, import_data.py import-deduction-certificate can be used to import it.

Confirm the annual premium for iDeCo (individual-type defined contribution pension plan)
- Confirm the amount from the Small Business Mutual Aid, etc. Premium Payment Certificate
- The full amount is an income deduction (upper limit: 816,000 yen per year for self-employed persons)
If there are small business mutual aid premiums, confirm them in the same way

For image files: OCR reading

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

Result verification: From both reading results, annual_premium, certificate_type 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 differences
Present the three choices Adopt A / Adopt B / Manual input using AskUserQuestion

Step 1.7: Aggregation of medical expense statements

If applying the medical expense deduction, aggregate the statements.

Registration and aggregation of medical expenses

ledger.py list-medical-expenses --db-path DB_PATH --input query.json Obtain the registered medical expense statements with

If there are unregistered medical expenses, register them with ledger.py add-medical-expense --db-path DB_PATH --input medical.json :

{
  "fiscal_year": 2025,
  "detail": {
    "date": "2025-03-15",
    "patient_name": "山田太郎",
    "medical_institution": "ABC病院",
    "amount": 150000,
    "insurance_reimbursement": 0,
    "description": null
  }
}

Use the aggregation result (total_amount - total_reimbursement) for calculating the medical expense deduction

Step 1.8: Withholding tax on business income (payment records)

Importing payment records

import_data.py import-payment-statement --input payment_input.json Extract data from payment record PDFs/images with

For image files: OCR reading

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

Result verification: From both reading results, gross_amount, withholding_tax, payer_name compare

If they match: Adopt as is. Report "Two independent reads matched."

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

Specify the fields that differ
Present the three choices Adopt A / Adopt B / Manual input using AskUserQuestion

ledger.py add-business-withholding --db-path DB_PATH --input withholding.json Register withholding tax information by payee with:

{
  "fiscal_year": 2025,
  "detail": {
    "client_name": "取引先名",
    "gross_amount": 1000000,
    "withholding_tax": 102100
  }
}

ledger.py list-business-withholding --db-path DB_PATH --input query.json Check the registered information with
Use the total withholding tax amount as business_withheld_tax for income tax calculation

Step 1.8.5: Registration of professional fees such as tax accountant fees

If fees are paid to a tax accountant, lawyer, etc., register the fee details.

ledger.py list-professional-fees --db-path DB_PATH --input query.json Check registered professional fees such as tax accountant fees with

If not registered, register with ledger.py add-professional-fee --db-path DB_PATH --input fee.json :

{
  "fiscal_year": 2025,
  "detail": {
    "payer_address": "支払者住所",
    "payer_name": "税理士名",
    "fee_amount": 300000,
    "expense_deduction": 0,
    "withheld_tax": 30630
  }
}

Add the withholding tax amount to business_withheld_tax as part of the total

Step 1.9: Confirmation of loss carryforward

If a business loss occurred in a prior year or earlier and blue return filing is used, the carryforward deduction can be applied.

ledger.py list-loss-carryforward --db-path DB_PATH --input query.json Check registered carryforward losses with

If not registered, register with ledger.py add-loss-carryforward --db-path DB_PATH --input loss.json :

{
  "fiscal_year": 2025,
  "detail": {
    "loss_year": 2023,
    "amount": 500000
  }
}

Use the total carryforward loss as loss_carryforward_amount for income tax calculation

Step 1.10: Confirmation of other income (miscellaneous income, dividend income, occasional income, pension income, retirement income)

Confirm and register comprehensive-taxation income other than business income and salary income.

Miscellaneous income from public pensions, etc.

If there is income from public pensions, etc., calculate the pension deduction to determine miscellaneous income.

Confirm whether there is pension income

uv run shinkoku tax calc-pension --input pension_input.json Calculate the public pension deduction with:

uv run shinkoku tax calc-pension --input pension_input.json

Input JSON:

{
  "pension_income": 2000000,
  "is_over_65": true,
  "other_income": 0
}

Output:

{
  "pension_income": 2000000,
  "deduction_amount": 1100000,
  "taxable_pension_income": 900000,
  "other_income_adjustment": 0
}

taxable_pension_income Add to misc_income as miscellaneous income
The minimum guaranteed amount of the public pension deduction (600,000 yen for under 65, 1.1 million yen for 65 and over) remains unchanged in the Reiwa 7 and Reiwa 8 revisions. For Reiwa 9 and later, if the total with the salary income deduction exceeds 2.8 million yen, the excess is reduced from the pension deduction (Reiwa 8 revision, not yet reflected in calculations)

Retirement income

If retirement pay is received, calculate retirement income.

Confirm whether there is retirement pay

uv run shinkoku tax calc-retirement --input retirement_input.json Calculate retirement income with:

uv run shinkoku tax calc-retirement --input retirement_input.json

Input JSON:

{
  "severance_pay": 10000000,
  "years_of_service": 20,
  "is_officer": false,
  "is_disability_retirement": false
}

Output:

{
  "severance_pay": 10000000,
  "retirement_income_deduction": 8000000,
  "taxable_retirement_income": 1000000,
  "half_taxation_applied": true
}

Retirement income is in principle subject to separate taxation (withholding is completed at retirement), but it may also be settled through a final tax return
For short-term retirement of officers, etc. (5 years or less of service), the 1/2 taxation is not applied

Miscellaneous income (miscellaneous)

Manuscript fees from side work, gains from selling crypto assets, and other miscellaneous income.

ledger.py list-other-income --db-path DB_PATH --input query.json Check registered miscellaneous income with

If there is unregistered income, register with ledger.py add-other-income --db-path DB_PATH --input other_income.json :

{
  "fiscal_year": 2025,
  "detail": {
    "income_type": "miscellaneous",
    "description": "収入の内容",
    "revenue": 500000,
    "expenses": 50000,
    "withheld_tax": 51050,
    "payer_name": "支払者名"
  }
}

Miscellaneous income = income - expenses (no special deduction)

Cryptocurrency (crypto assets)

Capital gains from selling crypto assets must be declared as miscellaneous income (comprehensive taxation).

ledger.py list-crypto-income --db-path DB_PATH --input query.json Check registered cryptocurrency income with

If not registered, ledger.py add-crypto-income --db-path DB_PATH --input crypto.json register by exchange with :

{
  "fiscal_year": 2025,
  "detail": {
    "exchange_name": "取引所名",
    "gains": 300000,
    "expenses": 10000
  }
}

Add the total as miscellaneous income to total_income

Dividend income (portion elected for comprehensive taxation)

Dividends for which comprehensive taxation is elected are eligible for the dividend credit (tax credit).

ledger.py list-other-income --db-path DB_PATH --input query.json で income_type: "dividend_comprehensive" Check
If not registered, ledger.py add-other-income --db-path DB_PATH --input dividend.json register with
Dividend credit: portion of taxable income up to 10 million yen → 10% of dividends; portion exceeding that → 5%

Occasional income

Temporary income such as insurance maturity proceeds and prize money.

ledger.py list-other-income --db-path DB_PATH --input query.json で income_type: "one_time" Check
If not registered, ledger.py add-other-income --db-path DB_PATH --input one_time.json register with
Occasional income = max(0, (revenue - expenses - special deduction 500,000 yen)) × 1/2

`calc_income_tax` Reflection in

The above other income is passed to calc_income_tax with the following parameters:

misc_income: Total miscellaneous income (including cryptocurrency)
dividend_income_comprehensive: Dividend income (portion elected for comprehensive taxation)
one_time_income: Revenue amount of occasional income (1/2 calculation performed internally)
other_income_withheld_tax: Total withholding tax on other income

Step 1.11: (Not applicable) Separate taxation

Separate taxation (Form 3 for stocks and FX) is not applicable. If applicable, guide the user to consult a tax accountant.

Step 1.12: Registering breakdown of social insurance premiums by type

Since the income deduction breakdown statement requires entries by type, register social insurance premiums by type.

If you have a social insurance premium deduction certificate, you can import it with import_data.py import-deduction-certificate .

ledger.py list-social-insurance-items --db-path DB_PATH --input query.json Check registered items with
If not registered, ledger.py add-social-insurance-item --db-path DB_PATH --input insurance.json register by type with :
```
{
  "fiscal_year": 2025,
  "detail": {
    "insurance_type": "national_health",
    "name": "保険者名",
    "amount": 300000
  }
}
```
insurance_type: national_health / national_pension / national_pension_fund / nursing_care / labor_insurance / other
Use the total amount as social_insurance in the deduction calculation

Step 1.13: Registering the insurance company name for insurance contracts

Since the income deduction breakdown statement requires the insurance company name, register the insurance contract.

If you have an image or PDF of the deduction certificate, you can import it with import_data.py import-deduction-certificate . After importing, register with ledger.py add-insurance-policy based on the extracted data.

ledger.py list-insurance-policies --db-path DB_PATH --input query.json Check registered items with
If not registered, ledger.py add-insurance-policy --db-path DB_PATH --input policy.json register with :
```
{
  "fiscal_year": 2025,
  "detail": {
    "policy_type": "life_general_new",
    "company_name": "保険会社名",
    "premium": 80000
  }
}
```
policy_type: life_general_new / life_general_old / life_medical_care / life_annuity_new / life_annuity_old / earthquake / old_long_term
Reflect life insurance premiums in the life_insurance_detail parameter, and earthquake insurance premiums in earthquake_insurance_premium .

Step 1.14: Confirming donations other than hometown tax donations

Confirm donations to political activity donations, certified NPO corporations, public interest incorporated associations, etc.

ledger.py list-donations --db-path DB_PATH --input query.json Check registered donations with

If not registered, ledger.py add-donation --db-path DB_PATH --input donation.json register with :

{
  "fiscal_year": 2025,
  "detail": {
    "donation_type": "npo",
    "recipient_name": "寄附先名",
    "amount": 50000,
    "date": "2025-06-01",
    "receipt_number": null
  }
}

donation_type: political / npo / public_interest / specified / other

Calculation of donation deduction:
- Income deduction: All donations - 2,000 yen (upper limit 40% of total income amount)
- Tax credit (political activity donations): (donations - 2,000 yen) × 30% (upper limit 25% of income tax amount)
- Tax credit (certified NPOs, etc.): (donations - 2,000 yen) × 40% (upper limit 25% of income tax amount)
calc_deductions の donations Pass a list of donation records to the parameter

Step 2: Calculation of income deductions

`tax_calc.py calc-deductions` call

shinkoku tax calc-deductions --input deductions_input.json

Input JSON:

{
  "total_income": 5000000,
  "social_insurance": 700000,
  "life_insurance_premium": 80000,
  "earthquake_insurance_premium": 30000,
  "medical_expenses": 200000,
  "furusato_nozei": 50000,
  "housing_loan_balance": 0,
  "spouse_income": null,
  "ideco_contribution": 276000,
  "dependents": [],
  "fiscal_year": 2025,
  "housing_loan_detail": null,
  "donations": null
}

Output (DeductionsResult):

income_deductions: List of income deductions (basic_deduction, social_insurance_deduction, life_insurance_deduction, earthquake_insurance_deduction, ideco_deduction, medical_deduction, furusato_deduction, donation_deduction, spouse_deduction, dependent_deduction, disability_deduction)
tax_credits: List of tax credits (housing_loan_credit, political_donation_credit, npo_donation_credit)
total_income_deductions: Total income deductions
total_tax_credits: Total tax credits

Items to check for each deduction:

Basic deduction: Graduated deduction according to total income amount (Reiwa 7: 1.32 million or less = 950,000, Reiwa 8: 4.89 million or less = 1.04 million.fiscal_year automatically switched by)
Social insurance premium deduction: National Pension, National Health Insurance, and other annual payment amounts
Life insurance premium deduction: Calculated using old and new systems × 3 categories (general/nursing care medical/individual pension)
- life_insurance_detail Specify the premiums for 5 categories with the parameter:
  - general_new: General (new system),general_old: General (old system)
  - medical_care: Nursing care medical (new system only)
  - annuity_new: Individual pension (new system),annuity_old: Individual pension (old system)
- Upper limit for each category: New system 40,000 yen / Old system 50,000 yen / Combined upper limit 40,000 yen
- Upper limit for the total of 3 categories: 120,000 yen
- If the withholding tax slip states the 5 categories of life insurance premiums, use them as is
Earthquake insurance premium deduction: Earthquake insurance (upper limit 50,000 yen) + old long-term casualty insurance (upper limit 15,000 yen), combined upper limit 50,000 yen
- old_long_term_insurance_premium Old long-term casualty insurance premiums can be specified with the parameter
Small enterprise mutual aid, etc. premium deduction: Individual tracking of 3 subtypes
- iDeCo (individual-type defined contribution pension)
- Small enterprise mutual aid
- Mutual aid for dependents with physical or mental disabilities
- small_business_mutual_aid Specify small enterprise mutual aid premiums with the parameter
Medical expense deduction: The portion exceeding 100,000 yen (or 5% of income) after subtracting insurance payouts, etc. from the amount paid
- Selective application with the self-medication tax system: OTC drug purchase amount - 12,000 yen (upper limit 88,000 yen)
- Medical expense deduction and self-medication cannot be used together. Choose the more advantageous one
Spouse deduction/special deduction: The deduction amount changes in stages according to the spouse's income
Dependent deduction: Deduction amount according to age category (general 380,000/specified 630,000/elderly 480,000 or 580,000)
Disability deduction: Deduction amount according to the degree of disability
Personal deductions(Automatically determined from the taxpayer information in config):
- Widow deduction: 270,000 yen (income 5 million or less)
- Single parent deduction: 350,000 yen (income 5 million or less)
- Disability deduction (self): Ordinary 270,000 yen / Special 400,000 yen
- Working student deduction: 270,000 yen (income 750,000 or less)
Furusato Nozei: Donation − 2,000 yen (include the one-stop special exception portion in the tax return)
Housing loan deduction: Year-end balance cap by housing category and deduction rate 0.7% (moved in on or after Reiwa 4)

Step 3: Calculation of income tax amount

`tax_calc.py calc-income` call of

shinkoku tax calc-income --input income_input.json

Input JSON (IncomeTaxInput):

{
  "fiscal_year": 2025,
  "salary_income": 5000000,
  "business_revenue": 3000000,
  "business_expenses": 1000000,
  "blue_return_deduction": 650000,
  "social_insurance": 700000,
  "life_insurance_premium": 80000,
  "earthquake_insurance_premium": 30000,
  "medical_expenses": 0,
  "furusato_nozei": 50000,
  "housing_loan_balance": 0,
  "spouse_income": null,
  "ideco_contribution": 276000,
  "withheld_tax": 100000,
  "business_withheld_tax": 30000,
  "estimated_tax_payment": 0,
  "loss_carryforward_amount": 0
}

Output (IncomeTaxResult):

salary_income_after_deduction: Amount after employment income deduction
business_income: Business income
total_income: Total income amount (after applying carryover loss)
total_income_deductions: Total income deductions
taxable_income: Taxable income amount (rounded down to the nearest 1,000 yen)
income_tax_base: Calculated tax amount
total_tax_credits: Total tax credits
income_tax_after_credits: After tax credits
reconstruction_tax: Special income tax for reconstruction (base income tax amount x 2.1%)
total_tax: Amount of income tax and special income tax for reconstruction (no rounding)
withheld_tax: Withheld tax amount (employment portion)
business_withheld_tax: Withheld tax amount on business income
estimated_tax_payment: Estimated tax prepayment amount
loss_carryforward_applied: Carryover loss amount applied
tax_due: Tax amount to be paid (= total_tax - withheld_tax - business_withheld_tax - estimated_tax_payment)

Reflection of donation deduction:

Donation deductions other than Furusato Nozei (registered in Step 1.14) arecalc_deductions included in the result of. calc_income_tax internally calc_deductions calls, so if the following parameters are passed correctly, they will be reflected automatically:

furusato_nozei: Total Furusato Nozei donation amount
Tax credits for political activity donations, certified NPOs, etc. are calc_deductions の donations calculated via parameters

Before calculating income tax, calc_deductions if calling individually,donations be sure to pass the list of donation records registered in Step 1.14 to the parameter.

Automatic cap on the blue return special deduction:

blue_return_deduction the value in config may be passed as is. The calculation engine automatically caps it at the business profit (Special Tax Measures Act Article 25-2). Be sure to check the result's effective_blue_return_deduction と warnings .

Checking the calculation results:

Display the breakdown of the total income amount
effective_blue_return_deduction check, and if there is any automatic adjustment, display the contents of warnings display the contents of
If a carryover loss is applied, specify its amount
Check whether the application of the income tax quick table is correct
Check whether the special income tax for reconstruction is correctly added
Check whether the withheld tax amount (employment portion + business portion) is correctly deducted
Check whether the estimated tax prepayment amount is correctly deducted
Specify the final payment amount (or refund amount)

For the income tax quick calculation table, spouse deduction table, housing loan limit, etc., refer to references/deduction-tables.md refer to.

Step 3.1: Sanity check (required)

calc-income automatically verify the results of. This step cannot be skipped.

`tax_calc.py sanity-check` call of

shinkoku tax sanity-check --input sanity_input.json

Input JSON:

{
  "input": { ... },
  "result": { ... }
}

input: In Step 3, calc-income IncomeTaxInput passed to
result: In Step 3, calc-income IncomeTaxResult returned from

Output (TaxSanityCheckResult):

passed: true/false
items: List of check items (severity, code, message)
error_count: Number of errors
warning_count: Number of warnings

Action based on the result

error > 0: There is a problem with the calculation result. Check the error details, correct the input, and rerun Step 3.
warning > 0: Present the warning details to the user and proceed after confirmation.
passed = true: No problems. Proceed to the next step.

Step 3.5: DB registration of housing loan deduction details (only for eligible persons)

If applying the housing loan deduction (first year), register the detailed information in the DB.

ledger.py add-housing-loan-detail --db-path DB_PATH --input housing.json Register the housing loan deduction details with:

{
  "fiscal_year": 2025,
  "detail": {
    "housing_type": "new_custom",
    "housing_category": "certified",
    "move_in_date": "2024-03-15",
    "year_end_balance": 30000000,
    "is_new_construction": true,
    "is_childcare_household": false,
    "has_pre_r6_building_permit": false,
    "purchase_date": "2024-01-20",
    "purchase_price": 40000000,
    "total_floor_area": 8000,
    "residential_floor_area": 8000,
    "property_number": null,  // 不動産番号（13桁）を入力すると登記事項証明書の添付省略可（令和3年度改正）
    "application_submitted": false
  }
}

For the year-end balance upper limit table by housing category, refer to references/deduction-tables.md refer to.

Step 6: Presentation of calculation result summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
所得税の計算結果（令和○年分）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ 所得金額（総合課税）
  事業所得:           ○○○,○○○円
  給与所得:           ○○○,○○○円
  雑所得:             ○○○,○○○円（該当者のみ）
  配当所得:           ○○○,○○○円（総合課税分、該当者のみ）
  一時所得:           ○○○,○○○円（該当者のみ）
  合計所得金額:       ○○○,○○○円

■ 所得控除
  社会保険料控除:     ○○○,○○○円
  生命保険料控除:      ○○,○○○円
  基礎控除:           480,000円
  [その他の控除...]
  所得控除合計:       ○○○,○○○円

■ 税額計算
  課税所得金額:       ○○○,○○○円
  算出税額:           ○○○,○○○円
  税額控除:            ○○,○○○円
  復興特別所得税:       ○,○○○円
  所得税及び復興特別所得税: ○○○,○○○円
  源泉徴収税額:       ○○○,○○○円
  予定納税額:          ○○,○○○円
  ---------------------------------
  申告納税額:          ○○,○○○円（納付 / 還付）

■ 次のステップ:
  → /consumption-tax で消費税の計算を行う
  → /e-tax で確定申告書等作成コーナーに入力する（Claude in Chrome）
  → /submit で提出準備を行う
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Output of handover document

After presenting the summary, output the following file 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 step-specific files

.shinkoku/progress/07-income-tax.md Output in the following format to:

---
step: 7
skill: income-tax
status: completed
completed_at: "{当日日付 YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# 所得税計算・確定申告書作成の結果

## 所得金額の内訳

- 事業所得: {金額}円
- 給与所得: {金額}円
- 雑所得: {金額}円（該当者のみ、仮想通貨含む）
- 配当所得（総合課税）: {金額}円（該当者のみ）
- 一時所得: {金額}円（該当者のみ）
- 合計所得金額: {金額}円

## 扶養親族・配偶者

- 配偶者控除/特別控除: {適用あり（控除額）/適用なし}
- 扶養控除: {適用あり（控除額、人数）/適用なし}

## iDeCo・小規模企業共済

- 小規模企業共済等掛金控除: {金額}円（{iDeCo/小規模企業共済/なし}）

## 医療費控除

- 適用: {あり/なし}
- 医療費控除額: {金額}円

## 事業所得の源泉徴収

- 源泉徴収税額（事業分）: {金額}円

## 損失繰越控除

- 適用: {あり/なし}
- 繰越損失控除額: {金額}円

## 所得控除の内訳

| 控除項目 | 金額 |
|---------|------|
| 基礎控除 | {金額}円 |
| 社会保険料控除 | {金額}円 |
| 生命保険料控除 | {金額}円 |
| 地震保険料控除 | {金額}円 |
| 小規模企業共済等掛金控除 | {金額}円 |
| 医療費控除 | {金額}円 |
| 寄附金控除 | {金額}円 |
| 配偶者控除/特別控除 | {金額}円 |
| 扶養控除 | {金額}円 |
| 障害者控除 | {金額}円 |
| **所得控除合計** | **{金額}円** |

## 税額計算

- 課税所得金額: {金額}円
- 算出税額: {金額}円
- 税額控除（住宅ローン控除等）: {金額}円
- 復興特別所得税: {金額}円
- 所得税及び復興特別所得税: {金額}円
- 源泉徴収税額（給与分）: {金額}円
- 源泉徴収税額（事業分）: {金額}円
- 予定納税額: {金額}円
- **申告納税額: {金額}円（{納付/還付}）**

## 次のステップ

/consumption-tax で消費税の計算を行う
/e-tax で確定申告書等作成コーナーに入力する（Claude in Chrome）
/submit で提出準備を行う

Update of 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: income-tax
Table: Update the status of all steps (set income-tax to completed)
Describe guidance for the next step

Guidance after output

After outputting the file, tell the user the following:

"I saved the handover document to .shinkoku/progress/ . Even if the session is interrupted, you can carry over the results in the next skill."
Guidance for the next step

Additional Resources

Reference Files

For detailed tables and parameters, refer to the following:

references/form-b-fields.md — Correspondence of each field in Form B of the final tax return
references/deduction-tables.md — Income tax quick calculation table, spouse deduction table, basic deduction table, housing loan limit, life insurance premium deduction, etc.

Disclaimer

This calculation is based on general income tax calculation logic
Separate taxation (stocks/FX) is not covered — the calculation for Form 3 is not performed
White tax return (income and expenditure statement) is not covered
Real estate income, capital gains (real estate sale, etc.), and retirement income are currently not supported
It is recommended that the final return contents be confirmed with a tax accountant or other specialist

About this skill

Loading settings (execute first)

Path resolution example

Loading progress information

Basic policy

Confirmation of preconditions

Mandatory confirmation checklist (cannot be skipped)

Step 1: Importing the withholding slip

import_data.py import-withholding Call of

For image files: OCR reading

Step 1.5: Confirmation of dependent relatives and spouse information

Loading from the DB

Items to confirm if not registered

Step 1.6: Confirmation of iDeCo and small business mutual aid

For image files: OCR reading

Step 1.7: Aggregation of medical expense statements

Registration and aggregation of medical expenses

Step 1.8: Withholding tax on business income (payment records)

Importing payment records

For image files: OCR reading

Step 1.8.5: Registration of professional fees such as tax accountant fees

Step 1.9: Confirmation of loss carryforward

Step 1.10: Confirmation of other income (miscellaneous income, dividend income, occasional income, pension income, retirement income)

Miscellaneous income from public pensions, etc.

Retirement income

Miscellaneous income (miscellaneous)

Cryptocurrency (crypto assets)

Dividend income (portion elected for comprehensive taxation)

Occasional income

calc_income_tax Reflection in

Step 1.11: (Not applicable) Separate taxation

Step 1.12: Registering breakdown of social insurance premiums by type

Step 1.13: Registering the insurance company name for insurance contracts

Step 1.14: Confirming donations other than hometown tax donations

Step 2: Calculation of income deductions

tax_calc.py calc-deductions call

Step 3: Calculation of income tax amount

tax_calc.py calc-income call of

Step 3.1: Sanity check (required)

tax_calc.py sanity-check call of

Action based on the result

Step 3.5: DB registration of housing loan deduction details (only for eligible persons)

Step 6: Presentation of calculation result summary

Output of handover document

Output of step-specific files

Update of progress summary

Guidance after output

Additional Resources

Reference Files

Disclaimer

`import_data.py import-withholding` Call of

`calc_income_tax` Reflection in

`tax_calc.py calc-deductions` call

`tax_calc.py calc-income` call of

`tax_calc.py sanity-check` call of