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
| # |
Symptom / Question |
Entry tree |
Priority |
| 1 |
"Am I resident or non-resident — and what changes?" |
residency-tree |
P1 (gateway) |
| 2 |
"Do I have to file? Can I accept IRS automático? Which annexes?" |
filing-obligation-tree |
P1 (router) |
| 3 |
"I receive rent from a PT property" (Categoria F) |
rental-income-tree |
P1 |
| 4 |
"I sold a property or shares" (Categoria G / mais-valias) |
capital-gains-tree |
P1 |
| 5 |
"I have salary or a pension" (Categoria A / H) |
employment-pension-tree |
P2 |
| 6 |
"I'm self-employed / recibos verdes" (Categoria B) |
self-employment-tree |
P2 |
| 7 |
"I have foreign income / risk of double taxation" (Anexo J) |
foreign-income-tree |
P2 |
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.
1---2name: pt-irs-runbook3description: 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.4---5# Portugal IRS Filing Runbook
6
7A diagnostic runbook for Portuguese personal income tax (IRS). Each *symptom* is a
8filing situation; each decision tree routes from the situation to the correct
9**annex, autonomous rate, and deadline**, then terminates in a concrete filing
10action or a clear "escalate to a contabilista certificado for {reason}".
11
12> **Not tax advice.** This skill encodes the CIRS and Portal das Finanças rules as
13> verified on the cited dates. Tax rates and thresholds change with each Orçamento
14> do Estado. Always confirm figures against the live Art. 68/72 text and the
15> official Modelo 3 / IRS automático screens before submitting, and involve a
16> contabilista certificado for anything non-routine. Default income year is
17> **2025 (return filed 1 Apr – 30 Jun 2026)** unless stated otherwise.
18
19## When to Apply
20
21- The user asks how to **file a Modelo 3** (PT annual income tax return) or which
22 annexes apply to their income.
23- The user needs to know whether they are a **PT tax resident or non-resident**,
24 and what that changes.
25- The user receives **Portuguese-source income** — rent, a property/share sale,
26 salary, pension, or self-employment fees — and must declare it.
27- The user is a **non-resident landlord** (or has foreign income as a resident)
28 and needs the right rate plus **double-taxation relief**.
29- The user asks about a specific PT regime: **IRS automático, IRS Jovem, IFICI
30 (the post-NHR regime), englobamento, mais-valias reinvestment**.
31
32This skill is Portugal-specific. For UK/other-country filing it is out of scope
33(though it covers the *PT side* of a cross-border situation, e.g. PT rental income
34that also appears on a UK SA106).
35
36## How to Use
37
381. **Always start at residency.** Read [residency-tree](references/residency-tree.md).
39 Residency status (Art. 16) determines the entire regime — worldwide vs
40 PT-source-only income, progressive vs flat rates, deductions vs none.
412. **Then check whether a return is even required** and which annexes:
42 [filing-obligation-tree](references/filing-obligation-tree.md).
433. **Open the tree for each income type the user has.** A taxpayer often needs
44 several annexes at once.
454. **Look up every rate/threshold in one place:**
46 [rates-and-deductions.md](references/rates-and-deductions.md) is the single
47 source of truth; the trees link to it rather than restating numbers.
485. **Estimate figures deterministically** with the calculators in
49 [references/queries/](references/queries/) (day-count, rental tax, capital
50 gain), then **verify on Portal das Finanças**.
516. **Summarise the outcome** with [assets/templates/report.md](assets/templates/report.md).
52
53## Common Symptoms
54
55| # | Symptom / Question | Entry tree | Priority |
56|---|--------------------|-----------|----------|
57| 1 | "Am I resident or non-resident — and what changes?" | [residency-tree](references/residency-tree.md) | P1 (gateway) |
58| 2 | "Do I have to file? Can I accept IRS automático? Which annexes?" | [filing-obligation-tree](references/filing-obligation-tree.md) | P1 (router) |
59| 3 | "I receive rent from a PT property" (Categoria F) | [rental-income-tree](references/rental-income-tree.md) | P1 |
60| 4 | "I sold a property or shares" (Categoria G / mais-valias) | [capital-gains-tree](references/capital-gains-tree.md) | P1 |
61| 5 | "I have salary or a pension" (Categoria A / H) | [employment-pension-tree](references/employment-pension-tree.md) | P2 |
62| 6 | "I'm self-employed / recibos verdes" (Categoria B) | [self-employment-tree](references/self-employment-tree.md) | P2 |
63| 7 | "I have foreign income / risk of double taxation" (Anexo J) | [foreign-income-tree](references/foreign-income-tree.md) | P2 |
64
65### Usual suspects — the mistakes a default answer makes
66
67| Wrong default | Reality | Where |
68|---------------|---------|-------|
69| "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](references/rental-income-tree.md) |
70| "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](references/rates-and-deductions.md) |
71| "Non-residents pay 28% on the whole property gain" | Since 2023 non-residents get the **50% inclusion + progressive rates**, like residents | [capital-gains-tree](references/capital-gains-tree.md) |
72| "Just sign up for NHR" | NHR is **closed to new arrivals**; the current regime is **IFICI** with much narrower eligibility | [foreign-income-tree](references/foreign-income-tree.md) |
73| "A non-resident must appoint a fiscal representative" | Optional if you adhere to **electronic notifications**; always optional for EU/EEA residents | [filing-obligation-tree](references/filing-obligation-tree.md) |
74
75## Setup
76
77On first use, populate [config.json](config.json) with the taxpayer's situation
78(residence country, fiscal representative status, applicable tax treaty, NIF). If a
79required field is empty, ask the user, then save it. Never store passwords — login
80to Portal das Finanças is interactive.
81
82## Gotchas
83
84Diagnostic dead-ends and portal quirks accumulate in [gotchas.md](gotchas.md).
85Read it before a non-trivial filing.
86
87## Related Skills
88
89- A UK Self Assessment / SA106 runbook would complement this for the cross-border
90 (PT rental → UK FTCR) case — not part of this skill.
pproenca