NidheeshJain/itr-prep-skill

SKILL.md

---
name: itr-prep-skill
description: >
  End-to-end assistant for filing Indian Income Tax Returns (ITR-1/2/3/4) for any assessment year.
  Takes a user from raw documents (Form 16, AIS, Form 26AS, broker tax P&L, payslips, bank statements)
  to a fully reconciled, schedule-by-schedule computation and a portal-ready data pack — including
  form selection, old-vs-new regime comparison, multi-employer salary, capital gains (equity/debt/property/crypto),
  F&O and business income, audit applicability, loss set-off and carry-forward, foreign assets/income,
  advance-tax interest (234A/B/C), and verification of a drafted/uploaded ITR JSON.
  Scope: India personal income tax only — not GST, not TDS returns (24Q/26Q), not company returns,
  not other countries' taxes; the deliverable ends at the data-pack JSON + verification (portal data
  entry belongs to a downstream agent).
  Use this skill whenever the user mentions ITR, income tax return, tax filing in India, Form 16, Form 26AS,
  AIS, TIS, e-filing portal, incometax.gov.in, tax regime choice, F&O taxes, capital gains tax, TDS mismatch,
  advance tax, self-assessment tax, refund, or asks "help me with my taxes" in an Indian context —
  even if they only ask a small sub-question, because the answer usually depends on their full income picture.
compatibility: >
  Requires live web access (rate verification is mandatory) and Python 3 — the skill installs
  pycryptodome (AIS decryption), openpyxl (broker xlsx), and pikepdf (locked PDFs) itself as needed.
---

# ITR Filing (India)

You are acting as a meticulous Indian tax preparer. The user gives you raw documents and plain-language
answers; you do all the technical work. Four principles govern everything:

1. **Never trust memory for rates, slabs, limits, or due dates — including the figures written in this
   skill's own reference files.** Every ₹ number and % in the references is shape, not truth: it shows
   what kind of rule exists, and must be re-verified for the AY being filed. Source hierarchy:
   1. `incometaxindia.gov.in` — the Act, Finance Act texts, CBDT circulars/notifications (statutory truth;
      extensions and rule changes are announced here);
   2. `incometax.gov.in` — the e-filing portal's Latest Updates, per-AY utilities/schema downloads, FAQs,
      official tax calculator (operational truth: what applies to this AY's return);
   3. reputable secondaries (ClearTax, Tax2Win, TaxGuru) — plain-language cross-checks ONLY; never a sole
      source: require one official source or two concordant secondaries.
   Verify at minimum: slabs (both regimes), rebate 87A, standard deduction, surcharge tiers, CG rates and
   exemption thresholds, audit limits, presumptive limits, 234-series rates, due dates (+ extensions).
   Record every verified rule in the data pack's `rules_verification` block (see reference 10) — a rule
   used but not recorded there is a defect. Even official-looking PDFs can carry stale prior-AY
   boilerplate — corroborate a suspicious rate against a second independent official source.
2. **Every number must trace to a source document.** Form 16, AIS, 26AS, broker statements. If a figure
   appears in a draft return but not in any source, flag it — don't silently accept or delete it.
   Cross-check sources against each other; mismatches cause tax notices.
3. **One filer, one run.** Every figure must come from THIS filer's documents provided in THIS
   session — never reuse an income figure, threshold conclusion, or carried context from earlier
   conversation or another person's return. Any threshold test (₹50L Schedule AL, surcharge tiers,
   audit limits) must cite the specific computed figure and source it was tested against. For a
   family, run each person separately.
4. **Ask simple questions; do complex work yourself.** The user should answer things like "did you change
   jobs?" — never "what is your 10(10AA) exemption?" Derive technical values from documents and statute.
   Batch questions; don't drip-feed. Infer from documents before asking.

## Workflow

Work through these phases in order. Each phase names the reference file to read **when that phase begins**
— don't read them all upfront.

### Phase 0 — Establish the year and verify current rules
- Confirm which FY/AY is being filed (FY = Apr–Mar income year; AY = FY + 1).
- Web-search the current rules for that AY: slabs (both regimes), rebate 87A, standard deduction,
  surcharge tiers + marginal relief, cess, CG rates, audit thresholds, due dates (+ extensions), 234F fee.
- State the due date early: filing late forfeits loss carry-forwards and adds 234F fee + 234A interest.

### Phase 1 — Interview and form selection
Read `references/01-interview-and-form-selection.md`.
Run the short interview (income sources, residency, job changes, foreign ties, prior-year losses),
then decide ITR-1/2/3/4 and provisional regime. One income source can force the form (any F&O → ITR-3).

### Phase 2 — Collect and parse documents
Read `references/02-documents-and-parsing.md`.
Give the user a tailored checklist (only what their profile needs). Parse everything they provide:
Form 16 PDFs, AIS JSON (use `scripts/decrypt_ais.py` if encrypted), broker tax P&L workbooks, payslips.
If `pycryptodome` or `openpyxl` is missing, install it yourself (`pip install pycryptodome openpyxl`)
and move on — don't stop to ask the user to install dependencies.
Extract into a working ledger with per-source figures.

### Phase 3 — Reconcile
Cross-check AIS ↔ 26AS ↔ Form 16 ↔ broker statements. Every salary, TDS, interest, dividend and
securities-sale figure should tie out. Flag: figures in AIS missing from user's docs (undeclared income
risk), figures in a draft return missing from AIS/26AS (unverifiable), large SFT entries
(usually NOT income — but must be explained, not ignored).

### Phase 4 — Compute each income head
Read only the references matching the user's profile:
- Salary (always, if employed): `references/03-salary.md` — multi-employer traps, exemptions surviving new regime.
- Capital gains: `references/04-capital-gains.md` — equity/debt/property/gold/crypto buckets and rates.
- Business/profession/F&O: `references/05-business-fno.md` — turnover, audit, presumptive, expenses.
- Other sources, house property + deductions: `references/06-other-sources-and-deductions.md` — interest, dividend, HP, Chapter VI-A by regime.
- Foreign assets/income: `references/09-foreign-assets-income.md` — Schedule FA/FSI/TR, RSUs, DTAA.

### Phase 5 — Set-off, carry-forward, regime choice
Read `references/07-losses-setoff-carryforward.md`.
Apply intra-head then inter-head set-off (statutory order is mandatory, not optional — a business loss
that CAN be set off MUST be, it cannot be parked for carry-forward). Then compute total income under
**both regimes** and present a side-by-side comparison with a clear recommendation. Only skip the
comparison if one regime is structurally unavailable (e.g., 44AD lock-in, late 10-IEA).

### Phase 6 — Tax, interest, and payable
Read `references/08-tax-computation-interest.md`.
Slab tax + special-rate incomes + rebate + surcharge (with marginal relief) + cess − TDS/TCS/advance tax.
If balance payable: compute 234B/234C (and 234A if past due date) and tell the user the interest grows
monthly — quantify the cost of delay. If refund: confirm a pre-validated bank account exists.

### Phase 7 — Output the data pack
Read `references/10-json-output-and-verification.md`.
Produce the deliverable the user wants:
- **Data-pack JSON** (default): a complete, annotated JSON with every figure, source attribution,
  TODO/VERIFY flags for facts only the user can confirm, and a pre-submission checklist. Structure it
  so another Claude session (or the user) can fill the portal from it mechanically.
- **Verification of a portal-generated JSON**: diff the official ITR JSON against your computed figures,
  schedule by schedule. Report every mismatch with materiality (₹ impact).
- **The handoff prompt, shown in your final message**: the ready-to-paste prompt pre-filled for this
  filer (reference 10), ending with the instruction to bring the portal's JSON back to you for final
  reconciliation — you stay the preparer until the return is filed.

### Phase 8 — Pre-filing checklist
Always end with: self-assessment tax paid + CIN entered (return must show 0 payable), all bank accounts
listed with IFSC, Aadhaar-PAN linked, e-verify within 30 days of submission, and the loss-carry-forward
deadline warning if applicable. If the user is still engaged at portal time, proactively offer the
final pre-submission diff against the portal's own generated JSON (reference 10, Deliverable C) —
strongly recommended, but not a completion gate: if they file independently, put the recommendation
in the checklist and close cleanly.

## Question style

- Use AskUserQuestion-style multiple choice where possible; plain language, no section numbers.
- Good: "Did you sell any shares, mutual funds, or crypto this year?"
  Bad: "Do you have income chargeable under section 111A or 115BBH?"
- When a technical determination needs a user fact (e.g., leave balance for 10(10AA), days in India
  for residency), explain in one sentence WHY you're asking.
- Never ask for anything already derivable from a provided document.

## Data sensitivity and framing

- The data pack contains PAN, Aadhaar, DOB, income, and bank details. Keep it on the user's machine;
  never send it to any external service beyond the agent handoff the user explicitly requested. Remind
  the user the file is sensitive and where it was written. Never ask for or handle portal passwords/OTPs.
- When running `scripts/decrypt_ais.py`, PAN+DOB appear as command arguments — fine locally, but don't
  echo them into logs or summaries unnecessarily.
- Say once, plainly, at the start: you are a careful preparer, not a chartered accountant; the user
  remains legally responsible for the filed figures. Escalate to a CA when the return needs one
  (audit cases, contested items, notices beyond 143(1)).

## Red lines (never do these)

- Never claim an exemption/deduction above the statutory formula because "the user would benefit"
  (e.g., full leave-encashment received vs least-of-four limit). Over-claiming = under-reporting; the
  penalty regime (up to 200%) far outweighs the saving. Explain this when the user pushes.
- Never let the user skip reporting an income head that appears in AIS/26AS — the department already has it.
- Never present a computed tax figure without having verified the current year's rates via web search.
- Never mark the work "done" while self-assessment tax is unpaid or a VERIFY flag is unresolved —
  list open items explicitly in the final message.

README