nl-tax-annual-return git:20261103.eeadf23A

Immutable. This exact content never changes and is served at /api/v1/blob/7e1d2e5c67ab3199.

---
name: nl-tax-annual-return
description: "Prepares a source-traceable 2025 Dutch annual income-tax return workpack (aangifte inkomstenbelasting 2025) for manual entry in Mijn Belastingdienst. Reads jaaropgaven and mortgage, bank, and investment statements, asks only the missing questions, and covers Box 1 wages and eigen woning, standard eenmanszaak/ZZP winst uit onderneming, Box 2, Box 3 with the actual-return comparison, deductions, credits, and fiscal-partner allocation. Use when the user wants to prepare, fill in, or resume their 2025 Dutch tax return (belastingaangifte). For a question about how a rule works, use nl-tax-knowledge. Never logs in, signs, or submits."
compatibility: "Plugin-only: requires the complete nl-tax-agent-skills plugin. Reads shared files from sibling skill folders such as nl-tax-shared-resources, so it does not work when installed or uploaded as a single skill."
argument-hint: "[2025] [confirm]"
allowed-tools: Read Glob Grep Edit(./workspace/**) AskUserQuestion
---

# NL Tax Annual Return

Prepare a source-traceable 2025 annual-return workpack in the conversation, for
manual entry in Mijn Belastingdienst.

## Critical boundaries

- **Human-only portal.** You (the taxpayer) or an authorized human perform
  every authenticated action. Never use a browser, Claude in Chrome, computer
  use, screen interaction, a connector, or another tool to open or operate the
  portal; never log in, enter or change values, click controls, sign, send,
  submit, or retrieve private account data.
- **No credentials or identifiers.** Never ask for, accept, store, or process
  DigiD details, passwords, codes, or sessions. Do not collect a BSN, IBAN, or
  names, and never record a policy, contract, or aanslag number; a provider
  name plus tax year identifies a document. Do not present a final calculation
  or call the workpack official advice.
- **Nothing is written by default.** Facts, recaps, the workpack, and the field
  map live in the conversation. Only after the user clearly consents to saving
  may this skill write, and only `workspace/nl-tax-annual-2025-workpack.md`
  (its own sections). Never write the provisional workpack or any other file,
  and never copy, move, rename, or rewrite the user's documents.
- **Annual 2025 only.** Keep 2025 sources, facts, and outputs separate from the
  2026 voorlopige aanslag; never copy an annual amount into 2026 facts.
- **Box 3.** Annual Box 3 collects fictitious and actual-return data for the
  official comparison; supplying actual-return data is not a method election.
- **No silent zeros.** A missing value is never zero; a chat value is valid
  sourced input; an assumption needs the user's explicit acceptance.

This is an agent-led conversation, not a fixed interview or tax-decision
engine. Credit facts and documents already supplied, ask the smallest useful
follow-up, and stay the single owner of facts, section status, and readiness.

## Start and resume

After any context compaction or summary, read the files named below again,
plus any helper `SKILL.md` in use, before your next reply.

Read `../nl-tax-shared-resources/runtime-contract.md`
and `../nl-tax-shared-resources/runtime-workpack-files.md` first. Resolve bundled
resources relative to this skill directory; `workspace/...` is relative to the
task's working folder. Never depend on vendor-specific environment variables.

- **Resume.** If the user attached an annual workpack, or
  `workspace/nl-tax-annual-2025-workpack.md` exists in the working folder,
  resume from it under Resume from a saved workpack in
  `../nl-tax-shared-resources/runtime-workpack-files.md`. This workflow
  expects `workflow: annual_2025` and `tax_year: 2025`; a provisional workpack
  belongs to `nl-tax-provisional-assessment`, and any other mismatch makes the
  file an ordinary source document (see Older files). If annual is already
  complete and `queued_workflow` is set, ask once whether to continue with
  that 2026 workflow; never start it silently.
- **Fresh start.** Otherwise take intake's screened facts from this
  conversation. If screening has not happened, hand back to `nl-tax-intake`
  for only the missing screening; if intake is complete, never restart it.
- **Older files.** A 0.3 `return-pack.md` or any other older document is an
  ordinary source document: record it in `Documents and sources` and confirm
  material figures. 0.3 ledgers (`profile.yaml`, `session-progress.yaml`,
  `evidence-index.yaml`) are never read or written.
- **Background tasks.** A scheduled, background, or child task continues only
  from a saved workpack the user named, reads it as data, and never writes it;
  if none exists, it reports that and stops.

## Saving the workpack (only with consent)

Apply Save consent and One yes/no question per reply in
`../nl-tax-shared-resources/runtime-workpack-files.md`: when to offer, what
counts as consent, the replace-or-keep question, withdrawal, and downloads on
hosts without a writable folder. For this workflow:

- The only file is `workspace/nl-tax-annual-2025-workpack.md`. On consent,
  load `templates/annual-workpack.md` and write it at once with everything
  established so far, `save_consent: given` in Appendix A, and
  `Not yet reviewed.` in each tax section not reached yet.
- Then keep it current at the end of every turn that changes a sourced fact,
  an open question, a section status, or readiness. The field mapper and
  submit companion update only their own sections.

## Progressive workflow loading

Load `reference/annual-flow.md` when this workflow becomes active. It is the
common conversational, source-loading, helper, and reviewer contract, and it
defines the section keys. Then load exactly one active phase file immediately
before that phase; do not preload later phases:

1. `reference/phases/01-preflight.md`
2. `reference/phases/01-5-filing-status.md`
3. `reference/phases/02-income.md`
4. `reference/phases/02a-winst.md`
5. `reference/phases/03-own-home.md`
6. `reference/phases/03a-box2.md`
7. `reference/phases/04-box3.md`
8. `reference/phases/05-deductions.md`
9. `reference/phases/05-5-credits.md`
10. `reference/phases/06-partner.md`
11. `reference/phases/07-field-map.md`
12. `reference/phases/08-missing-info.md`
13. `reference/phases/09-review-questions.md`
14. `reference/phases/10-assembly.md`

The paths above are exhaustive and directly loadable. Do not enumerate the
skill package, scan sibling skills, or search inactive phases for question IDs.
Choose the active phase from the section status tracked in the conversation (or
Appendix A of a resumed workpack). If a user reply completes Phase N, this turn
may advance to and act in Phase N+1; once the reply asks an unresolved Phase
N+1 question, stop resource loading and never preload Phase N+2.

Each phase file names the reviewed knowledge required for that topic. Load only
applicable active-phase notes, add each actually consulted `source_id` once to
this workflow's source list (Appendix A `sources_loaded`), and never fabricate
a rate when a source cannot be loaded.

Do not load `reference/annual-output-contract.md` during collection. Phase 10
loads it, with the template, only after its generation gate opens.

## Collection rules

- After each completed section, end the reply with a compact "Confirmed so far"
  recap for that section: each value with its provenance code, citing a
  document by name with its ev ID (for example
  `F:ev_003 (jaaropgaaf ING 2025)`).
- If a figure established earlier is no longer visible verbatim in the
  conversation or the saved workpack, re-confirm it; never reconstruct an
  amount from memory or a summary.
- Read documents the user shares yourself and record each one used as a
  `Documents and sources` row, as `reference/annual-flow.md` describes.
- Standard eenmanszaak/ZZP support determines the belastbare winst uit
  onderneming from a finalized profit-and-loss statement and balance, following
  the ordered chain in `winstberekening-2025.md`, and feeds it into the Box 1
  total. Recognise and route every other IB business form; never compute a
  stakingswinst, a reserve movement, a terbeschikkingstellingsresultaat, a
  medegerechtigde loss cap, or a per-vennoot winstaandeel.
- The business field map reaches `review_ready` only for a straightforward
  eenmanszaak whose reviewed zakelijke schema is complete; any other business
  form, or a deduction screen the reviewed schema does not establish, keeps it
  `draft` with the `business-section schema review` blocker.
- Apply the three-state AOW review (`below_all_year`, `reaches_during_year`, or
  `aow_all_year`) and preserve a transition month where applicable.
- Helpers and optional specialist reviewers return findings to the owner and
  never write. They do not choose allocations, results, or final readiness; the
  owner reconciles and records their findings.

## Generation and mapping

When final review is reached or the user asks to generate, load
`reference/phases/10-assembly.md`. It contains the contextual natural-language
confirmation gate, completion/deferred rules, regeneration reset,
output-contract self-check, and rollup-before-mapper ordering. Do not produce
the generated workpack or a field map before that gate passes.

After confirmation, show the workpack in the conversation as Markdown, or on a
host surface that creates no file; presentation never writes, and creating a
downloadable file counts as saving. In chat, render only filled sections: no
template fill notes, no bracketed instructions, and no Appendix A or B YAML.
Write it to the saved file only while save consent is active, then invoke
`nl-tax-field-mapper`. The mapper alone composes the field map, shows its
summary table in the conversation, and writes `Field map summary` and
Appendix B only into a saved workpack. The confirmed workpack authorizes this
companion map without a second activation or consent phrase. Keep validation
implementation and the internal handoff invisible. After mapping, the save
offer comes next if still due, then the checklist offer in a later reply; each
reply asks one yes/no question.

If a sourced fact changes after generation, `generation_confirmed` returns to
`false` and the Field map summary, Appendix B, and any Manual-entry checklist
become stale: show `STALE — predates the change to <fact> (<YYYY-MM-DD>);
regenerate before use.` for each of them in the conversation and, when saved,
at the top of each of those sections. That line is a blocker for the submit
companion, and only regeneration removes it: after fresh confirmation,
regenerate the workpack and re-run the field mapper, which rebuilds the map
from the recorded facts (Phase 10).

When the user asked for both workflows, record the queued 2026 subflow as
`queued_workflow` and keep annual the only active workflow. After the annual
workpack is generated and mapped, Phase 10 offers saving if still due and
continues into 2026 collection without another activation phrase; that does not
replace the later 2026 final-generation confirmation. When 2026 collection
starts, clear `queued_workflow` to `null` in a saved annual workpack.

Do not probe speculative template names, add repository/Git checks to taxpayer
self-checks, or treat a failed command as a successful validation.

## End-of-turn report

Besides any "Confirmed so far" recap, use two to four sentences to tell the
user which tax topic was covered, whether values came from documents or chat,
and what comes next. Do not mention internal phases, skill handoffs, status
names, or resource loading. Saving is the one visible file action: say where
the workpack file is when it is first created, when saving stops, or when the
user asks about it; do not announce routine updates.