Income Tax Calculation

/e-tax

Load Settings (Run 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 of CLI scripts

   • output_dir

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

Example of Path Resolution

db_path

./shinkoku.db

/home/user/tax-2025/

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

Load 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/06-settlement.md

   • .shinkoku/progress/02-assess.md

   • .shinkoku/progress/05-furusato.md

3. Utilize the loaded information in subsequent steps (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 only after confirming that the blue tax return financial statements have been completed with the settlement skill
• 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
• Correctly set values in each field of references/form-b-fields.md
• Strictly adhere to rounding rules:
  • Taxable income: Round down amounts less than 1,000 yen (National Tax Act Article 118)
  • Reconstruction Special Income Tax: Round down amounts less than 1 yen (Reconstruction Resource Securement Act Article 13)
  • ㊺ Amount of Income Tax and Reconstruction Special Income Tax: No rounding
  • Declared tax amount (only for payment cases): Round down amounts less than 100 yen (National Tax Act Article 119)
  • Refund amount: In 1-yen units, no rounding down (National Tax Act Article 120)

Precondition Confirmation

1. Are blue tax return financial statements completed?: Check the output of the settlement skill
2. Load taxpayer profile: Retrieve taxpayer information from the config using

   skills/setup/scripts/profile.py get-taxpayer

   • Name, address, tax signature → Used for input into the Final Tax Return Preparation Corner
   • Status of widow/single parent, disabled person, working student → Used for calculating personal deductions
3. Income other than business income: Collect information if there is salary income, miscellaneous income, dividend income, temporary income, etc.
4. Withholding slips: Guide the user to import them if there is salary income
5. Application status of various deductions: comprehensively confirm applicable deductions
6. Estimated tax payment amount: Obtain the estimated tax payment amount confirmed by assess
   • If not confirmed, guide the user to determine it from the previous year's final tax return (column ㊺)
   • Manage the estimated tax payment amount separately from the withholding tax amount
7. Confirmation of separate taxation: Separate taxation for stocks/FX (Table 3) is not covered. If applicable, guide the user to consult a tax accountant

Mandatory Confirmation Checklist (Cannot Be Skipped)

• Family composition: Has the presence of a spouse and dependent family members been confirmed?
  • Unconfirmed → Confirm with the user and register details in Step 1.5
  • Confirmed (not applicable) → Step 1.5 can be skipped
• Housing loan deduction: Has the applicability been confirmed?
  • Unconfirmed → Confirm with the user
  • Applicable (first year) → Prepare a detailed statement in Step 3.7
• Estimated tax payment: Has the presence and amount been confirmed?
  • Unconfirmed → Guide the user to determine it from the previous year's final tax return (column ㊺)
  • Amount unconfirmed → Do not proceed until the correct value can be set in the

    estimated_tax_payment

    parameter

Step 1: Import Withholding Slips

Call

import_data.py import-withholding

shinkoku import import-withholding --input withholding_input.json

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

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

/reading-withholding

payment_amount

withheld_tax

social_insurance

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

Verification: Total amount of income deductions ≟ Amount of social insurance premiums, etc.          ← Includes small business mutual aid premiums (internal amount)
                            + Deduction amount for life insurance premiums
                            + Deduction amount for earthquake insurance premiums
                            + Amount of spouse (special) deduction
                            + Dependent deduction amount                ← Calculated from number of people × unit price (630,000 yen for specified/480,000 or 580,000 yen for elderly/380,000 yen for others)
                            + Disabled person deduction                ← Calculated from number of people × unit price (270,000 yen for general/400,000 yen for special/750,000 yen for cohabiting special)
                            + Widow deduction (270,000 yen) or single parent deduction (350,000 yen) ← If applicable
                            + Working student deduction (270,000 yen)       ← If applicable
                            + Amount of basic deduction              ← Use the amount stated on the withholding slip. If not stated, calculate from income and fiscal year

• "(Including amount of small business mutual aid premiums)" is an internal amount of the amount of social insurance premiums, etc. Adding it separately will result in double counting
• Dependent deductions and disabled person deductions are stated in the number of people column, not the amount column, so calculate from number of people × unit price
• For the amount of basic deduction, use the value stated on the withholding slip if available. If not stated, calculate according to total income and fiscal year (special addition for Reiwa 7 and 8, uniform 580,000 yen from Reiwa 9 onwards)
• If matching: Adopt as the OCR accuracy of each field has been confirmed
• If not matching: Clearly indicate the difference, present to the user which fields may have been misread, and correct by cross-checking with the original image

1. If there are multiple employers, import each one
2. Confirm deductions already adjusted at year-end, and determine if there are additional deductions

Step 1.5: Confirm Dependent Family Member/Spouse Information

Load from DB

1. Retrieve spouse information using

   ledger.py get-spouse --db-path DB_PATH

   (if registered)
2. Retrieve a list of dependent family members using

   ledger.py list-dependents --db-path DB_PATH

   (if registered)

Confirmation Items If Not Registered

1. Spouse: Confirm the presence of a spouse and annual income amount
   • Income ≤ 480,000 yen → Spouse deduction (380,000 yen)
   • Income > 480,000 yen and ≤ 1,330,000 yen → Special spouse deduction (graduated)
   • Taxpayer's income > 10,000,000 yen → No spouse deduction
   • After confirmation, register in the DB using

     ledger.py set-spouse --db-path DB_PATH --input spouse.json

2. Dependent family members: Collect the following information
   • Name, relationship, date of birth, annual income, presence of disability, presence of cohabitation
   • Under 16 years old: Not eligible for dependent deduction (target of child allowance)
   • 16 years old or older: General dependent deduction (380,000 yen)
   • 19 years old or older and under 23 years old: Specified dependent deduction (630,000 yen)
   • 70 years old or older: Elderly dependent deduction (480,000 yen for non-cohabiting/580,000 yen for cohabiting)
   • After confirmation, register each person in the DB using

     ledger.py add-dependent --db-path DB_PATH --input dependent.json

3. Collect My Number (required for entry in Tax Return Form B Table 2):
   • Spouse's My Number (12 digits)
   • My Number of all dependent family members aged 16 or older
   • My Number of children under 16 years old (required for entry in "Matters related to resident tax" section)
   • Handling note: Save in DB, but do not display in tool output or logs
4. Confirmation of business exclusive employees:
   • If the spouse receives salary as a blue business exclusive employee → Not eligible for spouse deduction
   • If dependent family members are blue business exclusive employees or white business exclusive employees → Not eligible for dependent deduction
   • If applicable, exclude from deduction calculation and clearly inform the user
5. Disabled person deduction: If dependent family members have disabilities
   • General disabled person: 270,000 yen, Special disabled person: 400,000 yen, Cohabiting special disabled person: 750,000 yen

• Determination of the non-taxable limit for resident tax (dependent count includes those under 16)
• Non-taxable determination of the uniform tax for resident tax
• Entry in the "Matters related to resident tax - Dependent family members under 16" column of Tax Return Form B Table 2

ledger.py add-dependent

Step 1.6: Confirm iDeCo・Small Business Mutual Aid

import_data.py import-deduction-certificate

1. Confirm the annual contribution for iDeCo (Individual-type Defined Contribution Pension)
   • Confirm the amount from the small business mutual aid premium payment certificate
   • Full amount is eligible for income deduction (upper limit: 816,000 yen per year for self-employed individuals)
2. Similarly confirm if there are contributions for small business mutual aid

For Image Files: OCR Reading

extracted_text

/reading-deduction-cert

annual_premium

certificate_type

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

Step 1.7: Aggregate Medical Expense Details

Register and Aggregate Medical Expenses

1. Retrieve registered medical expense details using

   ledger.py list-medical-expenses --db-path DB_PATH --input query.json

2. If there are unregistered medical expenses, register them using

   ledger.py add-medical-expense --db-path DB_PATH --input medical.json

   :
   json

   {
     "fiscal_year": 2025,
     "detail": {
       "date": "2025-03-15",
       "patient_name": "Taro Yamada",
       "medical_institution": "ABC Hospital",
       "amount": 150000,
       "insurance_reimbursement": 0,
       "description": null
     }
   }

3. Use the aggregated result (total_amount - total_reimbursement) to calculate the medical expense deduction

Step 1.8: Withholding Tax on Business Income (Payment Statement)

Import Payment Statements

1. Extract data from payment statement PDFs/images using

   import_data.py import-payment-statement --input payment_input.json

For Image Files: OCR Reading

extracted_text

/reading-payment-statement

gross_amount

withholding_tax

payer_name

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

1. Register withholding tax information by business partner using

   ledger.py add-business-withholding --db-path DB_PATH --input withholding.json

   :
   json

   {
     "fiscal_year": 2025,
     "detail": {
       "client_name": "Business Partner Name",
       "gross_amount": 1000000,
       "withholding_tax": 102100
     }
   }

2. Confirm registered information using

   ledger.py list-business-withholding --db-path DB_PATH --input query.json

3. Use the total withholding tax amount as

   business_withheld_tax

   for income tax calculation

Step 1.8.5: Register Fees for Tax Accountants, Etc.

1. Confirm registered fees for tax accountants, etc. using

   ledger.py list-professional-fees --db-path DB_PATH --input query.json

2. If unregistered, register using

   ledger.py add-professional-fee --db-path DB_PATH --input fee.json

   :
   json

   {
     "fiscal_year": 2025,
     "detail": {
       "payer_address": "Payer Address",
       "payer_name": "Tax Accountant Name",
       "fee_amount": 300000,
       "expense_deduction": 0,
       "withheld_tax": 30630
     }
   }

3. Add the withholding tax amount to

   business_withheld_tax

Step 1.9: Confirm Loss Carryforward

1. Confirm registered loss carryforwards using

   ledger.py list-loss-carryforward --db-path DB_PATH --input query.json

2. If unregistered, register using

   ledger.py add-loss-carryforward --db-path DB_PATH --input loss.json

   :
   json

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

3. Use the total loss carryforward amount as

   loss_carryforward_amount

   for income tax calculation

Step 1.10: Confirm Other Income (Miscellaneous, Dividend, Temporary, Pension, Retirement)

Miscellaneous Income from Public Pensions, Etc.

1. Confirm if there is pension income
2. Calculate the public pension, etc. deduction using

   skills/income-tax/scripts/tax_calc.py calc-pension

   :
   bash

   shinkoku tax calc-pension --input pension_input.json

   Input JSON:
   json

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

   Output:
   json

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

3. Add

   taxable_pension_income

   to

   misc_income

   as miscellaneous income
4. Reiwa 7 revision: Minimum guarantee amount increased from 600,000 to 700,000 yen for under 65, from 1,100,000 to 1,300,000 yen for 65 and over

Retirement Income

1. Confirm if there is retirement pay
2. Calculate retirement income using

   skills/income-tax/scripts/tax_calc.py calc-retirement

   :
   bash

   shinkoku tax calc-retirement --input retirement_input.json

   Input JSON:
   json

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

   Output:
   json

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

3. Retirement income is generally subject to separate taxation (withholding tax already deducted at retirement), but may be settled in the final tax return in some cases
4. Short-term retirement for officers, etc. (less than 5 years of service) is not eligible for half taxation

Miscellaneous Income

1. Confirm registered miscellaneous income using

   ledger.py list-other-income --db-path DB_PATH --input query.json

2. If there is unregistered income, register using

   ledger.py add-other-income --db-path DB_PATH --input other_income.json

   :
   json

   {
     "fiscal_year": 2025,
     "detail": {
       "income_type": "miscellaneous",
       "description": "Content of income",
       "revenue": 500000,
       "expenses": 50000,
       "withheld_tax": 51050,
       "payer_name": "Payer Name"
     }
   }

3. Miscellaneous income = Revenue - Expenses (no special deduction)

Virtual Currency (Cryptocurrency)

1. Confirm registered virtual currency income using

   ledger.py list-crypto-income --db-path DB_PATH --input query.json

2. If unregistered, register by exchange using

   ledger.py add-crypto-income --db-path DB_PATH --input crypto.json

   :
   json

   {
     "fiscal_year": 2025,
     "detail": {
       "exchange_name": "Exchange Name",
       "gains": 300000,
       "expenses": 10000
     }
   }

3. Add the total to

   total_income

   as miscellaneous income

Dividend Income (Comprehensive Taxation Selection)

1. Confirm

   income_type: "dividend_comprehensive"

   using

   ledger.py list-other-income --db-path DB_PATH --input query.json

2. If unregistered, register using

   ledger.py add-other-income --db-path DB_PATH --input dividend.json

3. Dividend deduction: 10% of dividends for taxable income up to 10,000,000 yen, 5% for amounts exceeding that

Temporary Income

1. Confirm

   income_type: "one_time"

   using

   ledger.py list-other-income --db-path DB_PATH --input query.json

2. If unregistered, register using

   ledger.py add-other-income --db-path DB_PATH --input one_time.json

3. Temporary income = max(0, (Revenue - Expenses - Special deduction of 500,000 yen)) × 1/2

Reflection in

calc_income_tax

calc_income_tax

• misc_income

  : Total miscellaneous income (including virtual currency)

• dividend_income_comprehensive

  : Dividend income (comprehensive taxation selection)

• one_time_income

  : Revenue amount of temporary income (1/2 calculation is performed internally)

• other_income_withheld_tax

  : Total withholding tax amount for other income

Step 1.11: (Not Covered) Separate Taxation

Step 1.12: Register Breakdown of Social Insurance Premiums by Type

import_data.py import-deduction-certificate

1. Confirm registered items using

   ledger.py list-social-insurance-items --db-path DB_PATH --input query.json

2. If unregistered, register by type using

   ledger.py add-social-insurance-item --db-path DB_PATH --input insurance.json

   :
   json

   {
     "fiscal_year": 2025,
     "detail": {
       "insurance_type": "national_health",
       "name": "Insurer Name",
       "amount": 300000
     }
   }

   insurance_type: national_health / national_pension / national_pension_fund / nursing_care / labor_insurance / other
3. Use the total amount as

   social_insurance

   for deduction calculation

Step 1.13: Register Insurance Company Names for Insurance Policies

import_data.py import-deduction-certificate

ledger.py add-insurance-policy

1. Confirm registered items using

   ledger.py list-insurance-policies --db-path DB_PATH --input query.json

2. If unregistered, register using

   ledger.py add-insurance-policy --db-path DB_PATH --input policy.json

   :
   json

   {
     "fiscal_year": 2025,
     "detail": {
       "policy_type": "life_general_new",
       "company_name": "Insurance 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
3. Reflect life insurance premiums in the

   life_insurance_detail

   parameter, and earthquake insurance premiums in

   earthquake_insurance_premium

Step 1.14: Confirm Donations Other than Furusato Nozei

1. Confirm registered donations using

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

2. If unregistered, register using

   ledger.py add-donation --db-path DB_PATH --input donation.json

   :
   json

   {
     "fiscal_year": 2025,
     "detail": {
       "donation_type": "npo",
       "recipient_name": "Recipient Name",
       "amount": 50000,
       "date": "2025-06-01",
       "receipt_number": null
     }
   }

   donation_type: political / npo / public_interest / specified / other
3. Calculation of donation deduction:
   • Income deduction: Total donations - 2,000 yen (upper limit of 40% of total income amount)
   • Tax credit (political activity donations): (Donations - 2,000 yen) × 30% (upper limit of 25% of income tax amount)
   • Tax credit (certified NPOs, etc.): (Donations - 2,000 yen) × 40% (upper limit of 25% of income tax amount)
4. Pass the list of donation records to the

   donations

   parameter of

   calc_deductions

Step 2: Calculate Income Deductions

Call

tax_calc.py calc-deductions

shinkoku tax calc-deductions --input deductions_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
}

• 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

• Basic deduction: Graduated deduction according to total income amount (reflects Reiwa 7 revision, 950,000 yen for up to 1,320,000 yen)
• Social insurance premium deduction: Annual payment amount for national pension, national health insurance, etc.
• Life insurance premium deduction: Calculated using new/old systems × 3 categories (general/long-term care medical/individual annuity)
  • Specify insurance premiums for 5 categories with the

    life_insurance_detail

    parameter:

    • general_new

      : General (new system),

      general_old

      : General (old system)

    • medical_care

      : Long-term care medical (new system only)

    • annuity_new

      : Individual annuity (new system),

      annuity_old

      : Individual annuity (old system)
  • Upper limit for each category: 40,000 yen for new system / 50,000 yen for old system / 40,000 yen for combined total
  • Upper limit for total of 3 categories: 120,000 yen
  • If the withholding 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 damage insurance (upper limit 15,000 yen), combined upper limit 50,000 yen
  • Can specify old long-term damage insurance premiums with the

    old_long_term_insurance_premium

    parameter
• Small business mutual aid premium deduction: Track 3 subtypes individually
  • iDeCo (Individual-type Defined Contribution Pension)
  • Small business mutual aid
  • Mutual aid for supporting persons with disabilities
  • Specify small business mutual aid premiums with the

    small_business_mutual_aid

    parameter
• Medical expense deduction: Amount exceeding 100,000 yen (or 5% of income) after subtracting insurance benefits, etc.
  • Optional application with 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. Select the more advantageous one
• Spouse deduction/special deduction: Deduction amount varies gradually according to spouse's income
• Dependent deduction: Deduction amount according to age category (380,000 yen for general/630,000 yen for specified/480,000 or 580,000 yen for elderly)
• Disabled person deduction: Deduction amount according to disability level
• Personal deductions (automatically determined from taxpayer information in config):
  • Widow deduction: 270,000 yen (income up to 5,000,000 yen)
  • Single parent deduction: 350,000 yen (income up to 5,000,000 yen)
  • Disabled person deduction (self): 270,000 yen for general / 400,000 yen for special
  • Working student deduction: 270,000 yen (income up to 750,000 yen)
• Furusato Nozei: Donations − 2,000 yen (includes one-stop special case in final tax return)
• Housing loan deduction: Upper limit of year-end balance by housing category and deduction rate of 0.7% (for move-in from Reiwa 4 onwards)

Step 3: Calculate Income Tax Amount

Call

tax_calc.py calc-income

shinkoku tax calc-income --input income_input.json

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

• salary_income_after_deduction

  : Amount after salary income deduction

• business_income

  : Business income

• total_income

  : Total income amount (after applying loss carryforward)

• total_income_deductions

  : Total income deductions

• taxable_income

  : Taxable income amount (round down amounts less than 1,000 yen)

• income_tax_base

  : Calculated tax amount

• total_tax_credits

  : Total tax credits

• income_tax_after_credits

  : After tax credits

• reconstruction_tax

  : Reconstruction Special Income Tax (base income tax amount x 2.1%)

• total_tax

  : Amount of Income Tax and Reconstruction Special Income Tax (no rounding)

• withheld_tax

  : Withholding tax amount (salary portion)

• business_withheld_tax

  : Withholding tax amount for business income

• estimated_tax_payment

  : Estimated tax payment amount

• loss_carryforward_applied

  : Amount of loss carryforward applied

• tax_due

  : Declared tax amount (= total_tax - withheld_tax - business_withheld_tax - estimated_tax_payment)

calc_deductions

calc_income_tax

calc_deductions

• furusato_nozei

  : Total donations for Furusato Nozei
• Tax credits for political activity donations and certified NPOs, etc. are calculated via the

  donations

  parameter of

  calc_deductions

calc_deductions

donations

blue_return_deduction

effective_blue_return_deduction

warnings

1. Display the breakdown of total income amount
2. Check

   effective_blue_return_deduction

   , and display the contents of

   warnings

   if there was automatic adjustment
3. If loss carryforward was applied, clearly indicate the amount
4. Confirm that the income tax quick calculation table was applied correctly
5. Confirm that the Reconstruction Special Income Tax was added correctly
6. Confirm that the withholding tax amount (salary + business portion) was deducted correctly
7. Confirm that the estimated tax payment amount was deducted correctly
8. Clearly indicate the final payment amount (or refund amount)

references/deduction-tables.md

Step 3.1: Sanity Check (Mandatory)

calc-income

Call

tax_calc.py sanity-check

shinkoku tax sanity-check --input sanity_input.json

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

• input

  : IncomeTaxInput passed to

  calc-income

  in Step 3

• result

  : IncomeTaxResult returned from

  calc-income

  in Step 3

• passed

  : true/false

• items

  : List of check items (severity, code, message)

• error_count

  : Number of errors

• warning_count

  : Number of warnings

Response According to Results

• error > 0: There is a problem with the calculation results. Check the error details, correct the input, and re-run Step 3
• warning > 0: Present the warning contents to the user, and continue after confirmation
• passed = true: No issues. Proceed to the next step

Step 3.5: Register Housing Loan Deduction Details in DB (Only for Applicable Persons)

1. Register housing loan deduction details using

   ledger.py add-housing-loan-detail --db-path DB_PATH --input housing.json

   :
   json

   {
     "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,
       "application_submitted": false
     }
   }

references/deduction-tables.md

Step 6: Present Calculation Result Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Income Tax Calculation Results (Reiwa ○)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ Income Amount (Comprehensive Taxation)
  Business Income:           ○○○,○○○ Yen
  Salary Income:           ○○○,○○○ Yen
  Miscellaneous Income:             ○○○,○○○ Yen (Only for applicable persons)
  Dividend Income:           ○○○,○○○ Yen (Comprehensive taxation portion, only for applicable persons)
  Temporary Income:           ○○○,○○○ Yen (Only for applicable persons)
  Total Income Amount:       ○○○,○○○ Yen

■ Income Deductions
  Social Insurance Premium Deduction:     ○○○,○○○ Yen
  Life Insurance Premium Deduction:      ○○,○○○ Yen
  Basic Deduction:           480,000 Yen
  [Other Deductions...]
  Total Income Deductions:       ○○○,○○○ Yen

■ Tax Calculation
  Taxable Income Amount:       ○○○,○○○ Yen
  Calculated Tax Amount:           ○○○,○○○ Yen
  Tax Credits:            ○○,○○○ Yen
  Reconstruction Special Income Tax:       ○,○○○ Yen
  Income Tax and Reconstruction Special Income Tax: ○○○,○○○ Yen
  Withholding Tax Amount:       ○○○,○○○ Yen
  Estimated Tax Payment Amount:          ○○,○○○ Yen
  ---------------------------------
  Declared Tax Amount:          ○○,○○○ Yen (Payment / Refund)

■ Next Steps:
  → Calculate consumption tax with /consumption-tax
  → Enter into the Final Tax Return Preparation Corner with /e-tax (Claude in Chrome)
  → Prepare for submission with /submit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Output Handover Files

Output Step-by-Step Files

.shinkoku/progress/07-income-tax.md

---
step:7
skill: income-tax
status: completed
completed_at: "{Current date YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# Results of Income Tax Calculation and Final Tax Return Preparation

## Breakdown of Income Amount

- Business Income: {Amount} Yen
- Salary Income: {Amount} Yen
- Miscellaneous Income: {Amount} Yen (Only for applicable persons, including virtual currency)
- Dividend Income (Comprehensive Taxation): {Amount} Yen (Only for applicable persons)
- Temporary Income: {Amount} Yen (Only for applicable persons)
- Total Income Amount: {Amount} Yen

## Dependent Family Members/Spouse

- Spouse Deduction/Special Deduction: {Applicable (deduction amount)/Not applicable}
- Dependent Deduction: {Applicable (deduction amount, number of people)/Not applicable}

## iDeCo・Small Business Mutual Aid

- Small Business Mutual Aid Premium Deduction: {Amount} Yen ({iDeCo/Small Business Mutual Aid/None})

## Medical Expense Deduction

- Applicable: {Yes/No}
- Medical Expense Deduction Amount: {Amount} Yen

## Withholding Tax on Business Income

- Withholding Tax Amount (Business Portion): {Amount} Yen

## Loss Carryforward Deduction

- Applicable: {Yes/No}
- Loss Carryforward Deduction Amount: {Amount} Yen

## Breakdown of Income Deductions

| Deduction Item | Amount |
|---------|------|
| Basic Deduction | {Amount} Yen |
| Social Insurance Premium Deduction | {Amount} Yen |
| Life Insurance Premium Deduction | {Amount} Yen |
| Earthquake Insurance Premium Deduction | {Amount} Yen |
| Small Business Mutual Aid Premium Deduction | {Amount} Yen |
| Medical Expense Deduction | {Amount} Yen |
| Donation Deduction | {Amount} Yen |
| Spouse Deduction/Special Deduction | {Amount} Yen |
| Dependent Deduction | {Amount} Yen |
| Disabled Person Deduction | {Amount} Yen |
| **Total Income Deductions** | **{Amount} Yen** |

## Tax Calculation

- Taxable Income Amount: {Amount} Yen
- Calculated Tax Amount: {Amount} Yen
- Tax Credits (Housing Loan Deduction, etc.): {Amount} Yen
- Reconstruction Special Income Tax: {Amount} Yen
- Income Tax and Reconstruction Special Income Tax: {Amount} Yen
- Withholding Tax Amount (Salary Portion): {Amount} Yen
- Withholding Tax Amount (Business Portion): {Amount} Yen
- Estimated Tax Payment Amount: {Amount} Yen
- **Declared Tax Amount: {Amount} Yen ({Payment/Refund})**

## Next Steps

Calculate consumption tax with /consumption-tax
Enter into the Final Tax Return Preparation Corner with /e-tax (Claude in Chrome)
Prepare for submission with /submit

Update Progress Summary

.shinkoku/progress/progress-summary.md

• 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 next steps

Guidance After Output

• "Handover files have been saved to

  .shinkoku/progress/

  . Results can be carried over to the next skill even if the session is interrupted."
• Guidance for next steps

Additional Resources

Reference Files

• references/form-b-fields.md

  — Correspondence of each column in Final Tax Return Form B

• 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 — Calculation for Table 3 is not performed
• White tax return (income and expenditure statement) is not covered
• Real estate income, transfer income (real estate sales, etc.), retirement income are not currently supported
• It is recommended to confirm the final declaration contents with a professional such as a tax accountant