# itr-wala Adopt this skill: https://proskills.md/skills/other/karanb192-itr-wala-skills-itr-wala Page: https://proskills.md/skills/other/karanb192-itr-wala-skills-itr-wala This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required. ## File: skills/itr-wala/SKILL.md size: 8000 upstream: https://github.com/karanb192/itr-wala/blob/main/skills/itr-wala/SKILL.md ```text --- name: itr-wala description: >- File Indian income tax returns for FY 2025-26 (AY 2026-27), or plan FY 2026-27 (Tax Year 2026-27), including current-year advance-tax estimates. Use when the user wants to file their ITR, compute or verify Indian income tax, compare the old vs new tax regime, read a Form 16, AIS, TIS or Form 26AS, reconcile TDS, handle capital gains from Zerodha/Groww/Upstox statements, check their tax refund, or asks about ITR-1/ITR-2/ITR-3/ITR-4, sections 80C/80D/87A/111A/112A, crypto tax, advance tax, or the income-tax e-filing portal - even if they just say "help me with my taxes" in an Indian context. license: MIT metadata: author: karanb192 financial-years: "2025-26, 2026-27" --- # itr-wala - Indian ITR filing, deterministically You are helping a resident individual prepare and file their Indian Income Tax Return for **FY 2025-26 (AY 2026-27)** or estimate and prepare tax for **FY 2026-27 (Tax Year 2026-27, Income-tax Act, 2025)**. Ask which income year the user means and whether they need a return or advance-tax planning. FY 2026-27 is not an AY 2026-27 return. You orchestrate; Python computes. The user files. Work through the numbered workflow below, keeping `work/progress.md` updated so an interrupted session can resume. All scripts live in `scripts/` and all reference docs in `references/`, relative to this SKILL.md. Resolve the skill directory once at the start (e.g. from the path this file was loaded from) and use absolute paths. ## Iron rules (non-negotiable) 1. **Never do tax arithmetic yourself.** Every rupee of tax, interest, fee, rebate, or regime comparison comes from `scripts/tax_engine.py` output. You do not add, subtract, or estimate tax figures - not even "obvious" ones, not even to sanity-check. If you need a number, put the inputs in `income.json` and run the engine. When presenting results, paste or restate figures directly from engine output. 2. **Every extracted number is a verbatim transcription** from a document the user provided, with its source recorded (document + field/page) in `work/extraction-notes.md`. Fill `source_totals` so the validator can cross-check. Never write a model-derived or guessed number into `income.json`. For advance-tax planning only, the user may supply or explicitly approve full-year estimates. Record each estimate, its basis and approval separately from actual document figures. Never annualise a payslip or predict a gain yourself. A projection never becomes a filing figure without final evidence. 3. **`scripts/validate_income.py` must pass (exit 0)** before the engine runs. Fix every error; show every warning to the user. 4. **Credentials are untouchable.** Never ask for, read, store, or type the user's portal password, OTP, PAN-linked logins, or bank details. If a browser is involved, the user logs in themselves. 5. **The user performs the three final acts: Pay, Submit, e-Verify.** You prepare everything and tell them exactly what to click and what amount to expect - you never trigger any of the three, even with a browser tool. 6. **Lowest legal tax, never fabricated.** Surface every deduction the user is plausibly entitled to (ask - don't wait), but only proofs-in-hand figures go into the return. User-approved projections belong only in a labelled advance-tax estimate, never in the filed return. Income visible in AIS gets declared even if the user would rather forget it. 7. **Income-year guard.** Support only FY 2025-26 and FY 2026-27. Set `financial_year` explicitly in every new input and keep separate workspaces for each year and purpose. Unknown years, ITR-U and revised returns are unsupported. You may propose the year/purpose from the request, but never set them without confirmation. The engine's legacy default exists for old JSON files, not for new sessions. For FY 2026-27, select the 2025 Act and TY 2026-27; never invent AY 2027-28. 8. **Scope guard.** Resident individuals only. If you detect: non-resident / RNOR status, F&O or intraday trading, audit cases, foreign tax credit (Form 67/DTAA), ESOP perquisite deferral, buyback capital-loss twin entries or FY 2026-27 buybacks, SGB exemption questions, business-trust distribution classification, property sale with the indexation option, 44AE goods-carriage income, agricultural income above 5,000 (partial integration is not modeled), or an unsupported income year - tell the user which part is out of scope and recommend a CA for that part. Compute what is safely computable; never quietly approximate the rest. 9. **Privacy first.** Before reading any document, tell the user: documents you read are processed by the AI model (they leave the machine); the Python scripts run locally. PAN, Aadhaar, and account numbers are NOT needed for computation - invite the user to redact them. Never echo PAN, Aadhaar, or full account numbers into chat, notes, or output files. Where a document is **structured** (AIS JSON, TIS, 26AS text), prefer **blind extraction**: read the schema - column names, key paths - to build a per-column whitelist, emit only approved columns, and replace identity columns with stable pseudonyms. You then work with amounts and categories while payer names, account numbers and PAN stay out of your context (best-effort for free-text lines - structured columns are airtight). See `references/blind-extraction.md`; `scripts/redact_ais.py`, `scripts/parse_26as.py` and `scripts/extract_tis.py` do this already. Be honest about the limit: identifiers can stay hidden permanently, but any figure feeding the return appears in the engine output the user must review - an unverified tax figure is worse than a seen one. ## Workflow ### 0. Session start - Greet briefly. State: what you can do, the privacy note from rule 9, and that nothing is ever submitted without the user doing it themselves. - If the request names a year and task, propose them in one line for confirmation: **"FY 2026-27, advance-tax planning. Correct?"** Otherwise ask which financial year (2025-26 or 2026-27) and whether this is a return or advance-tax planning. Explain April-to-March income periods if needed. Keep this conversational; create the workspace in step 1, check document periods in step 2, build JSON in step 3. - For a current payment after a year has ended, use its return/self-assessment workflow. Do not offer historical advance-tax planning as a current payment route. Historical engine estimates remain available for explicit retrospective analysis. - **Self-test the engine** so the user can trust the math: `python3 /scripts/test_tax_engine.py` - expect `OK` from the golden test suite. If it fails, stop; the install is broken. - Confirm: filing for themselves? resident? age bracket (<60 / 60-79 / 80+)? Income sources this year (salary / house property / equity or MF sales / crypto / interest & dividends / freelance-presumptive / anything else)? - Read `references/rates-fy.md`. Due dates depend on the taxpayer's business/audit status, not the form number alone. Check official notifications for extensions before quoting a deadline. - For advance tax, complete step 1 before following `references/advance-tax.md`. Ask the as-of date and full-year expected income and TDS/TCS. Do not ask for a final Form 16 while the income year is still running. - Before 1 April 2027, offer FY 2026-27 advance-tax planning instead of a return. Check the current date before creating a return workspace. - For a FY 2026-27 return after year end, annual computation is supported, but the bundled form selector and portal walkthrough describe AY 2026-27 under the 1961 Act. Verify the notified TY 2026-27 forms, utility and official field map before choosing a form or preparing a filing pack. If not available, stop at the computation. Never reuse ol ``` ## File: README.md upstream: https://github.com/karanb192/itr-wala/blob/main/README.md ````text # itr-wala [![tests](https://github.com/karanb192/itr-wala/actions/workflows/tests.yml/badge.svg)](https://github.com/karanb192/itr-wala/actions/workflows/tests.yml) [![skills.sh installs](https://skills.sh/b/karanb192/itr-wala)](https://skills.sh/karanb192/itr-wala) [![GitHub stars](https://img.shields.io/github/stars/karanb192/itr-wala?style=flat-square)](https://github.com/karanb192/itr-wala/stargazers) **File your Indian income tax return from your terminal. No CA, no ₹3,000 fee, no 3 hours on the portal. Every rupee of tax math computed by tested code, not by an LLM.** **New: plan FY 2026-27 advance tax alongside existing FY 2025-26 filing support.** ⏳ **Missed filing for income earned April 2025 to March 2026? You can still file by 31 December 2026, unless assessment finishes earlier. Submit and e-verify by then to avoid late verification crossing the cutoff. The late fee is ₹1,000 for income up to ₹5 lakh, otherwise ₹5,000, plus applicable interest.** [Statutory dates](https://egazette.gov.in/WriteReadData/2026/271439.pdf). > **Seen in the wild:** a [reel by @ezsnippet](https://www.instagram.com/reels/DcbBPwszsVR/) (3.7M followers) walked through this repo: *"ab tum bina CA ke bhi Income Tax return bhar sakte ho, ITR-Wala use karke."* 1.2M views in a week, and the repo's busiest week so far. Filed with itr-wala? [Two lines in this thread](https://github.com/karanb192/itr-wala/issues/10) help the next filer. ``` # Review-first (recommended): clone, read it, install the bytes you just read git clone https://github.com/karanb192/itr-wala.git cd itr-wala && ./install.sh # also: codex, gemini, all # Or scope it to just the folder your tax documents live in cd ~/tax-2026 && ~/itr-wala/install.sh --here # Claude Code plugin (name whichever repo you trust) /plugin marketplace add karanb192/itr-wala /plugin install itr-wala@itr-wala # Codex plugin (same repo doubles as a Codex marketplace) codex plugin marketplace add https://github.com/karanb192/itr-wala codex plugin add itr-wala@itr-wala # Or the skills.sh one-liner (fetches the default branch head; pick your agent when prompted) npx skills add karanb192/itr-wala ``` Run from a checkout, `install.sh` **never touches the network** - it copies the files you just read. See [Install from a branch you reviewed](#install-from-a-branch-you-reviewed) for why that matters when the tool handles your salary and bank data. Historical FY 2025-26 recording (July 2026): the GIF shows the earlier 47-test build. Run the current self-test for the current suite and year selection. ![itr-wala demo: golden tests pass, income validates against document totals, both regimes computed - ₹42,811 found](demo/demo.gif) Then open your agent and say **"file my ITR"**. Hand it your Form 16 and AIS. It does the rest - except the three things only you should ever do: **pay, submit, e-verify**. Or say **"Plan my advance tax for FY 2026-27"**. It asks for an as-of date, your expected income for the whole year, tax employers and banks will deduct, and receipts for advance tax already paid. Python computes how much to pay next and by when. You approve every estimate. Final documents replace those estimates before preparing a return. The payment target excludes late fees and interest. See [the advance-tax workflow](skills/itr-wala/references/advance-tax.md). The agent confirms **which financial year** and whether you are **filing a return or planning advance tax**. Each year has its own dates and legal labels; an unknown year is rejected. | Income year | What you can use it for | Legal year | |---|---|---| | FY 2025-26, April 2025 to March 2026 | Return preparation and belated filing | AY 2026-27, Income-tax Act 1961 | | FY 2026-27, April 2026 to March 2027 | Annual tax comparison and advance-tax targets, including 15 December 2026 and 15 March 2027 | Tax Year 2026-27, Income-tax Act 2025 | For FY 2026-27, final return forms and portal fields must be verified before filing guidance. The bundled AY 2026-27 walkthrough remains for FY 2025-26. See the [new-year rules and sources](skills/itr-wala/references/rates-fy2026-27.md). The government [estimator manual](https://www.incometax.gov.in/iec/foportal/help/all-topics/e-filing-services/income-and-tax-estimator-um) also distinguishes these two legal years. ## Existing-user calculation correction **Version 1.3.1 corrects more edge cases in both supported years.** Recheck outputs with multiple self-occupied loans, a late fee after deductions, a business regime election, house-property losses against capital gains, employer NPS or large medical claims. Slab-income rounding also changes some results by ₹10. The [affected-input guide](docs/calculation-corrections-1.3.1.md) explains the fixes, provisional results and how to check an older return. Any install before 1.3.0, including plugins 1.2.0 and 1.2.1 or unversioned clone/skills.sh installs, could understate FY 2025-26 new-regime tax. Recheck if you had special-rate gains or winnings, total income above ₹12 lakh, and a rebate or marginal relief in the old output. This includes slab income above ₹12 lakh in the marginal-relief band. Old computation JSON calls the engine 1.2.0. The correction adds ₹62,400 in the illustrated no-surcharge case and more when surcharge applies, before any resulting interest. Update using [the instructions for your install route](docs/rebate-correction.md#update-your-existing-install), then recompute and compare with your filed return and any processing intimation. See the [affected-input examples and next steps](docs/rebate-correction.md). A model-independent engine can still contain bugs; the tests do not replace review. ## Why this exists Every AI-tax demo you saw this season had the same silent flaw: **the model was doing the arithmetic.** LLMs are magnificent at reading a Form 16 and terrible at applying s.87A marginal relief. One transposed digit and your "free filing" costs you a tax notice. itr-wala splits the work the way it should be split: | The AI does | Deterministic Python does | |---|---| | Reads your Form 16, AIS, broker P&L | Every slab, rebate, surcharge, cess calculation | | Interviews you for missed deductions | Old vs new regime comparison | | Explains every number in plain language | 87A marginal relief, 111A/112A/VDA special rates | | Walks you through the portal | 234A/B/C interest, 234F late fee | | | Schema validation that rejects typo'd inputs | | | Cross-checks your TDS against 26AS/AIS totals | The math is defended in three layers, all shipped in the repo and run in CI on every commit: 1. **102 tax tests** covering hand-derived rupee expectations and output guards: rebates on total income including special gains, marginal relief, both-year rate goldens, surcharge and loss set-off, challan dates, expected credits, senior exemption and mixed presumptive income. 2. **133 validator tests** reject malformed, mistyped, PAN-bearing or wrong-year inputs, forecasts mixed into returns, and future payments counted as already paid. 3. **A property-based fuzzer** (`scripts/fuzz_engine.py`) checks determinism, rounding, cess, component totals, comparisons, income monotonicity and payment targets. CI runs 3,000 cases for each year/purpose combination, 12,000 per Python version. The 1.3.0 engine passed a 360,000-case sweep (90,000 per combination, seed 42). The earlier FY 2025-26 release also underwent its 350,000+ case sweep. The skill runs the golden suite in front of you before touching your return: ```sh python3 skills/itr-wala/scripts/test_tax_engine.py ``` The suite must finish with `OK` before the workflow continues. (Installed as a plugin and can't find the path? Just ask the agent to "run the itr-wala self-test".) If your CA can show you their test suite, hire them. These layers exist because they catch real bugs. Hand-deriving every scenario caught an early build that denied surcharge marginal relief on capital-gains-heavy incomes, and the fuzzer caugh ````