| name | pt-irs-runbook |
| description | Portuguese personal income tax (IRS / Código do IRS) and Modelo 3 filing — determining tax residency (Art. 16), classifying income by category (rental/Anexo F, capital gains/Anexo G, employment/Anexo A, self-employment/Anexo B, pensions, foreign income/Anexo J), choosing the right annexes, applying current Art. 72 autonomous rates, and meeting Portal das Finanças deadlines. Covers residents and non-residents, including landlords with Portuguese-source rental income and double-taxation relief. Portugal-specific; not a substitute for a contabilista certificado. |
Portugal IRS Filing Runbook
A diagnostic runbook for Portuguese personal income tax (IRS). Each symptom is a
filing situation; each decision tree routes from the situation to the correct
annex, autonomous rate, and deadline, then terminates in a concrete filing
action or a clear "escalate to a contabilista certificado for {reason}".
Not tax advice. This skill encodes the CIRS and Portal das Finanças rules as
verified on the cited dates. Tax rates and thresholds change with each Orçamento
do Estado. Always confirm figures against the live Art. 68/72 text and the
official Modelo 3 / IRS automático screens before submitting, and involve a
contabilista certificado for anything non-routine. Default income year is
2025 (return filed 1 Apr – 30 Jun 2026) unless stated otherwise.
When to Apply
- The user asks how to file a Modelo 3 (PT annual income tax return) or which
annexes apply to their income.
- The user needs to know whether they are a PT tax resident or non-resident,
and what that changes.
- The user receives Portuguese-source income — rent, a property/share sale,
salary, pension, or self-employment fees — and must declare it.
- The user is a non-resident landlord (or has foreign income as a resident)
and needs the right rate plus double-taxation relief.
- The user asks about a specific PT regime: IRS automático, IRS Jovem, IFICI
(the post-NHR regime), englobamento, mais-valias reinvestment.
This skill is Portugal-specific. For UK/other-country filing it is out of scope
(though it covers the PT side of a cross-border situation, e.g. PT rental income
that also appears on a UK SA106).
How to Use
- Always start at residency. Read residency-tree.
Residency status (Art. 16) determines the entire regime — worldwide vs
PT-source-only income, progressive vs flat rates, deductions vs none.
- Then check whether a return is even required and which annexes:
filing-obligation-tree.
- Open the tree for each income type the user has. A taxpayer often needs
several annexes at once.
- Look up every rate/threshold in one place:
rates-and-deductions.md is the single
source of truth; the trees link to it rather than restating numbers.
- Estimate figures deterministically with the calculators in
references/queries/ (day-count, rental tax, capital
gain), then verify on Portal das Finanças.
- Summarise the outcome with assets/templates/report.md.
Common Symptoms
Usual suspects — the mistakes a default answer makes
| Wrong default | Reality | Where |
|---|
| "Rental income is taxed at the progressive scale" | Cat F has its own autonomous rate (25% base, lower for long leases); englobamento is optional | rental-income-tree |
| "A 2-year lease gets a reduced rental rate" | The Art. 72 reductions start at 5-year permanent-housing contracts; under 5 years = 25% | rates-and-deductions.md |
| "Non-residents pay 28% on the whole property gain" | Since 2023 non-residents get the 50% inclusion + progressive rates, like residents | capital-gains-tree |
| "Just sign up for NHR" | NHR is closed to new arrivals; the current regime is IFICI with much narrower eligibility | foreign-income-tree |
| "A non-resident must appoint a fiscal representative" | Optional if you adhere to electronic notifications; always optional for EU/EEA residents | filing-obligation-tree |
Setup
On first use, populate config.json with the taxpayer's situation
(residence country, fiscal representative status, applicable tax treaty, NIF). If a
required field is empty, ask the user, then save it. Never store passwords — login
to Portal das Finanças is interactive.
Gotchas
Diagnostic dead-ends and portal quirks accumulate in gotchas.md.
Read it before a non-trivial filing.
Related Skills
- A UK Self Assessment / SA106 runbook would complement this for the cross-border
(PT rental → UK FTCR) case — not part of this skill.
