Social Insurance Filing Kit

When this helps

You want to file on time, but deadlines differ by filing type and you often notice only after they've passed.

What it does

Describe an HR event — hiring, resignation, a dependent, a bonus, a raise — and the kit lists the filings needed (health insurance, employee pension, employment insurance), where to send each, the deadline, and a draft of the values for each form. It also estimates coverage based on weekly hours and company size. Before filing, it checks for missing names, dates or pay figures and dependents whose income exceeds the limit, separating what must be fixed from what to double-check. It also produces guidance on documents to collect from each employee and an Excel ledger tracking everyone's deadlines, nearest first. Hand it a staff list (CSV) and it flags likely new hires and resignations. You are the one who actually files everything.

The fixes baked into this kit

1. The staff list's "within dependent limits" mark gets confused with the dependent filingThat mark on a staff list means the employee is working while covered as someone else's dependent — it isn't the company's own dependent filing, which is only created when adding the employee's own family member as a dependent.
2. Using base pay alone for monthly remuneration drops the commuting allowancePutting base pay straight into the acquisition filing's monthly remuneration field omits the commuting allowance, so the kit asks for base pay, commuting allowance and other pay separately, and flags it for review if no commuting allowance was given.
3. The old ¥88,000/month threshold wrongly excludes part-timersThat condition was abolished in October 2026, so the kit switches based on that date and only flags the remaining exceptions for review. Company-size and weekly-hour thresholds for 2027 and 2028 are switched by date the same way.
4. Periodic review can't be determined for some part-timersPart-timers who worked under 17 days in all of April–June are assessed using months with 15 or more days instead — easy to miss — plus the income and furigana fields on the dependent filing that often get left blank by mistake.
5. Counting "within 5 days" from the next day makes the deadline a day lateOfficial guidance never states how to count the "within 5 days" deadline, so the kit counts the day the event happened as day one and reports the earliest resulting date.
6. No filing or deadline appears when weekly hours aren't known yetIf coverage can't yet be determined, producing no filing at all risks missing the deadline entirely, so the kit still issues a deadline under a "needs confirmation" filing and adds it to the ledger.
7. Number strings resembling My Number IDs leak into employee-facing documentsIf something resembling a 12-digit My Number appears in a dependent's details, the kit masks everything from that point on, and re-reads any document meant for the employee before producing it, refusing to produce it if the number is still present.

What's inside

• A filing list, destination, deadline and draft form values generated from a description of what happened
• A reasoned estimate of whether someone is covered by health, pension or employment insurance
• Pre-filing checks (missing names/dates, pay figures, dependents over the income limit, etc.)
• Calculations for standard monthly remuneration, periodic/revised reviews and bonus caps
• Guidance on the documents to request from each employee (their documents only)
• An Excel ledger tracking everyone's filings by nearest deadline
• A tool that scans a staff list (CSV) for likely new hires and resignations
• A runnable sample: 10 fictional events plus a staff list, to try before using real data

The first three decisions

1. Health insurance type (Kyokai Kenpo, or the name of your health insurance association)
2. Number of people enrolled in employee pension (company-wide; part-timers counted separately aren't included)
3. Regular employees' weekly hours and working days per month

What you need

• No extra costClaude Code or CodexBoth CLAUDE.md and AGENTS.md are included.
• No extra costNode.js 18 or newerUsed to run the tools (events, ledger, imports, etc.).
• No extra costExcel or NumbersUsed to view the filing ledger (Excel file).
• No extra costA browserUsed to view the results page and draft form values.

How to use

Just paste this into your AI.

I want to use the nice to have kit "Social Insurance Filing Kit". Follow https://nicetohave.app/en/g/6L6CVPVD-•••••••••• and set it up.

Works the same in Claude Code or Codex.
Read what this tells your AI to do, before you paste it

FAQ

Does this work for companies with their own health insurance association?

Yes, but their own forms, deadlines and attachments are separate, so check those with your health insurance association. The deadlines and values the kit produces assume Kyokai Kenpo.

How long is the grade table valid for?

Through August 2027. Since the employee pension ceiling rises from September 2027, calculating a grade for a later month triggers a notice at the top of the results page to check the new table (it doesn't stop the work).

If it's unclear whether someone is covered, does no filing get produced?

No — a filing and deadline are still produced, marked "needs confirmation," and added to the ledger, so the deadline isn't missed. It gets rebuilt once details like weekly hours are known.

Can it handle maternity/childcare leave or workers' comp filings?

No. It covers hiring, resignation, dependents, address/name changes, bonuses, pay changes, periodic review, turning 70, and changes in working pattern. Leave, workers' comp, and pay/premium calculations themselves are out of scope.

Can I enter a My Number ID or basic pension number?

Please don't enter a My Number (personal number) — if one is found, the kit stops and doesn't keep that input. Basic pension numbers and employment insurance numbers also aren't entered into the kit; you write those directly on the form.

Supporters

Once support opens, the people who backed this kit will be listed here.