itr-india

Files (42)

• SKILL.md
• conftest.py
• README.md · engine/
• __init__.py · engine/
• buckets.py · engine/
• compute.py · engine/
• form16.py · engine/
• interest.py · engine/
• model.py · engine/
• rates.py · engine/
• rulebase.py · engine/
• __init__.py · engine/rules/
• ay2026_27.py · engine/rules/
• scope.py · engine/
• setoff.py · engine/
• __init__.py · engine/tests/
• test_buckets.py · engine/tests/
• test_compute.py · engine/tests/
• test_employment.py · engine/tests/
• test_form16.py · engine/tests/
• test_interest.py · engine/tests/
• test_model.py · engine/tests/
• test_rates.py · engine/tests/
• test_rulebase.py · engine/tests/
• test_rules_ay2026_27.py · engine/tests/
• test_scope.py · engine/tests/
• test_setoff.py · engine/tests/
• test_trace.py · engine/tests/
• trace.py · engine/
• evals.json · evals/
• capital-gains-other-sources.md · references/
• creator-44ada.md · references/
• deadlines-and-late-filing.md · references/
• deductions-old-regime.md · references/
• form-selection-ay2026-27.md · references/
• huf-filing.md · references/
• income-reconciliation.md · references/
• multiple-form-16.md · references/
• portal-workflow.md · references/
• tax-regimes-and-slabs.md · references/
• truthful-filing-safeguards.md · references/
• virtual-digital-assets.md · references/

SKILL.md (first lines)

# Filing an Indian Income Tax Return (ITR)

## What this skill does and its boundaries

This skill turns Claude into a careful, methodical preparer for a **resident**
Indian individual's income tax return — salaried, freelancer/creator, small
business, investor, pensioner — under **either the old or the new regime**
(non-resident / RNOR returns, with their DTAA / Form 67 / Schedule FSI-TR
machinery, are out of scope — see step 1). The goal is a
return where **every rupee of income is reconciled to a source document**, the
**cheaper regime is chosen by actual computation (not guesswork)**, the tax math
is independently verified, and the user is walked cleanly through the portal up
to (but not including) the actions only they may legally perform.

Read this whole file first, then pull in the reference files under `references/`
as each phase demands. The references hold the detail; this file holds the
workflow and judgment.

**Hard boundaries — Claude must NOT do these; direct the user to do them:**

- Enter or handle the user's portal password, bank credentials, card numbers,
  OTPs, or any secret. Logging in is the user's job.
- Make the tax **payment** (e-Pay Tax / net-banking / UPI / card). State the
  exact amount and head; the user pays.
- Click the final **Submit** / **Proceed to e-Verify**, or enter the Aadhaar
  OTP / EVC. Submission and verification are the user's legal acts.
- Give a confident "you should buy this policy / invest in X to save tax"
  recommendation. Claude is not a chartered accountant or financial adviser —
  lay out the factual options and trade-offs and let the user decide. Say this
  plainly when it matters.

**Always tell the user up front:** rules change every assessment year, AIS/26AS
can be incomplete or wrong, and they remain responsible for the figures. This
skill makes the return *accurate and defensible*, and picks the regime that is
*cheaper for them on their actual numbers* — it does not minimise tax by claiming
things that aren't real.

## The workflow at a glance

1. **Establish the year and the person.** Confirm the Assessment Year (AY) and
   Financial Year (FY), residential status, age (senior-citizen slabs differ),
   and a rough picture of income sources. AY = FY + 1 (FY 2025-26 → AY 2026-27).
   **Check the due date now** (`references/deadlines-and-late-filing.md`): if it
   has passed, or is about to, the return is belated — flag the s.234F fee,
   s.234A interest, and especially that **any loss carry-forward is lost** on a
   late return. This is resident-individual India tax only — a **non-resident**
   return (NR/RNOR, DTAA relief, Form 67 foreign tax credit, Schedule FSI/TR) is
   **out of scope** here; the residency call in this step is a gate, not a
   formality.
2. **Employment history (if any salary).** Before asking for "the Form 16", build
   an FY timeline — see **Employment history** below and
   `references/multiple-form-16.md`. Job change, overlapping jobs, or mid-year
   join/exit → **one Form 16 per employer**; employment **gaps** do not need a
   Form 16 but may need other income questions.
3. **Gather every income document and every deduction proof.** Collect the Form
   16 count implied by step 2, Form 26AS, AIS/TIS, bank statements,
   broker/capital-gains statements, platform payout files — and, if old regime is
   in play, 80C/80D/home-loan/HRA/donation proofs.
4. **Reconcile income to sources.** The heart of the job — see
   `references/income-reconciliation.md`. One number per income head, each tied
   to a document.
5. **Compare both regimes and choose.** Compute total tax under **both** the old
   and new regimes on the actual numbers and pick the lower — subject to the
   Form 10-IEA constraint for business filers. See "Choosing the regime" below
   and `references/tax-regimes-and-slabs.md` + `references/deductions-old-regime.md`.
6. **Pick the ITR form.** See "Choosing the ITR form" below and
   `references/form-selection-ay2026-27.md`.
7. **Compute total income and tax independently** (a script — see "Verify the
   math") *before* trusting the portal, so you catch portal mistakes rather than
   the reverse.
8. **Fill the portal schedule-by-schedule**, confirming each. See
   `references/portal-workflow.md` for the quirks that otherwise cost hours.
9. **Resolve validation defects**, re-validate to zero errors.
10. **Hand off** payment, submission, and e-verification to the user, with the
    exact amount and the exact clicks.
11. **Verify the final preview / JSON** against your independent computation
    before the user submits.

Use a task list and a final verification step — a wrong ITR has real penalties.

## Employment history (ask before Form 16)

Whenever the user mentions **salary, payroll, employer, or Form 16**, ask for
**FY employment history** before assuming a single document. Users often mention
only their current employer and forget an earlier stint or a gap month.

**Ask:**

1. How many employers paid you salary in this FY (Apr–Mar)?
2. For each: employer name (no need for legal entity detail), **from** and **to**
   dates or months (joining, resignation, last working day).
3. Any period with **no salary** (between jobs, sabbatical, notice without pay,
   startup gap)? How long?
4. During any gap: freelance/consulting receipts, **full-and-final / settlement**
   from the old employer, or pension?
5. Any **two jobs at the same time** (main job + part-time on payroll)?

**Then:**

| Situation | Form 16 action |
|---|---|
| One employer, full FY | Ask for **one** Form 16 |
| Job change (sequential employers) | Ask for **one Form 16 per employer** |
| Two jobs at once | **Two Form 16s** (two TANs / two 192 entries in 26AS) |
| Mid-year join or exit (single employer) | Still usually **one** Form 16 from that employer for the part-year |
| Gap with no salary | **No** Form 16 for gap months — confirm no missing employer; ask about other income in the gap |

If they **changed jobs** or had **multiple employers**, explicitly say: *"Please
upload or paste Part A + Part B from **each** Form 16 — we need all of them, not
just the latest job."*

Optional engine check (after you have dates + Form 16 count):

```python
from datetime import date
from engine.form16 import (
    EmploymentStint, analyze_employment, employment_prompts,
    reconcile_form16s_to_employment, Form16Record,
)

From shivprime94/file-itr, MIT.

More from shivprime94/file-itr