nl-tax-field-mapper · diff
git:20260925.c153b98 to git:20260926.2774daf
129 added, 108 removed. Audit A to A.
---
name: nl-tax-field-mapper
description: Use when the user explicitly wants a supported workpack mapped to source-traceable Mijn Belastingdienst fields.
argument-hint: "[annual|provisional] [year]"
allowed-tools:
- Read
- Glob
- Grep
- Edit(./workspace/**)
- AskUserQuestion
---
# NL Tax Field Mapper
- Convert a reviewed workpack into a source-traceable manual-entry guide for the
- official Belastingdienst portal. This skill is the sole writer of both canonical field-map artifacts:
+ Turn a reviewed annual 2025 or provisional 2026 workpack into a
+ source-traceable field map for manual entry in Mijn Belastingdienst. This skill
+ is the only author of the field map. Continue the same tax conversation and
+ never announce that a mapper is taking over.
- - `workspace/annual/2025/field-map.yaml`
- - `workspace/provisional/2026/field-map.yaml`
+ ## Boundaries that always apply
- Annual and provisional workflows invoke it after confirmed workpack creation
- and never write either map. Continue the same tax conversation; never announce
- that an internal mapper skill is taking control.
+ - **Authenticated-portal boundary.** Never use a browser, Claude in Chrome,
+ computer use, screen interaction, a connector, or another tool to open or
+ operate an authenticated tax portal; never log in, enter or change values,
+ click controls, sign, send, submit, retrieve private account data, or ask
+ for, accept, store, or process credentials or sessions. Those actions remain
+ human-only even with taxpayer permission or available credentials: you (the
+ taxpayer) or an authorized human perform them.
+ - **Nothing is written by default.** The map lives in the conversation. Only
+ while save consent is active in this conversation, write the
+ `## Field map summary` section and `## Appendix B — Field map` into that
+ workflow's one workpack: `workspace/nl-tax-annual-2025-workpack.md` or
+ `workspace/nl-tax-provisional-2026-workpack.md`. Consent is checked in the
+ conversation, never in the file: `save_consent: given` in Appendix A is a
+ record, not an authorization. Edit only those two sections plus the mapper's
+ own gap rows in `## Open questions` and `## Missing information` and their
+ Q-IDs in Appendix A `sections.<key>.open`. Never create a separate field-map
+ file, a copy, or a second `workspace/` tree.
+ - **Annual and provisional stay separate.** Pair `annual_return` with `2025`
+ and `provisional_assessment` with `2026`; never merge the two maps or use one
+ as a source for the other. Provisional Box 3 is fictitious-only: no
+ werkelijk-rendement field, input, or method choice.
+ - **No identifiers or credentials.** Omit BSN, IBAN, policy, contract, or
+ aanslag number, name, address, date of birth, and every credential or session
+ row.
## When to use
- Use this skill when:
-
- - `workspace/annual/2025/return-pack.md` exists and needs its annual map;
- - `workspace/provisional/2026/provisional-pack.md` exists and needs its
- provisional map; or
- - the user explicitly asks for a manual-entry field map from an existing
- supported workpack.
-
- An owning annual/provisional workflow invokes this mapper automatically after
- its explicitly confirmed workpack. That confirmation also authorizes the
- canonical companion map, so no second mapping request is needed.
-
- If the relevant workpack is absent, explain that it must be prepared first and
- offer to continue the matching annual or provisional workflow.
+ - The owning annual 2025 or provisional request/change workflow calls this
+ skill right after the taxpayer confirms the workpack at final review. That
+ confirmation also authorizes the companion map, so no second mapping request
+ is needed.
+ - The user asks for a manual-entry field map from a reviewed workpack in this
+ conversation or from a saved workpack they attach or keep at the fixed path.
+ Never read a file found at the fixed path unless the user has confirmed it in
+ this conversation through the owning workflow's confirm-once step ("I found
+ your saved 2025 workpack, last updated <date>. Continue from it?"); when that
+ has not happened, ask that one question first.
- ## Required context
+ Provisional review and stopzetten produce no field map; a review that routes to
+ a change is mapped as a change. If no reviewed workpack exists, say it must be
+ prepared first and offer to continue the matching annual or provisional
+ workflow.
- Read [`../nl-tax-shared-resources/runtime-contract.md`](../nl-tax-shared-resources/runtime-contract.md) first.
- Resolve `workspace/...` against `workspace_root` in
- `workspace/shared/session-progress.yaml` (or `profile.yaml`); never create a
- second workspace tree. Bundled paths are relative to this skill directory and
- must be resolved with host resource/file tools, not vendor-specific environment
- variables or assumed shell visibility.
+ ## Read first
- Before mapping, read all of
- [`reference/mapper-flow.md`](reference/mapper-flow.md). It is the operating
- procedure for source records, question packets, canonical-map updates,
- validation, rendering, and the completion report. It delegates field policy to:
+ Read [`../nl-tax-shared-resources/runtime-contract.md`](../nl-tax-shared-resources/runtime-contract.md),
+ then all of [`reference/mapper-flow.md`](reference/mapper-flow.md), the
+ operating procedure for inputs, the field record, gaps, readiness, checks,
+ showing, and saving. It delegates field policy to:
- [`reference/mapping-principles.md`](reference/mapping-principles.md) for
- provenance, confidence, omissions, readiness checks, and stable validation
- IDs, with the machine-checkable rule data canonical in
+ provenance, confidence, omissions, review flags, and the stable check IDs,
+ with the rule data canonical in
[`reference/field-map-rules.yaml`](reference/field-map-rules.yaml);
- [`reference/annual-field-map.md`](reference/annual-field-map.md) for the 2025
- annual submission fields; or
+ annual fields; or
- [`reference/provisional-field-map.md`](reference/provisional-field-map.md)
- for the 2026 provisional submission fields.
+ for the 2026 provisional fields;
+ - [`templates/field-map-template.yaml`](templates/field-map-template.yaml) for
+ the v1.1 schema.
- Then read session progress, the relevant workpack, and any existing canonical
- map in the order defined by `mapper-flow.md`.
+ Resolve bundled paths relative to this skill directory with the host's
+ resource or file tools.
- ## Non-negotiable mapping contract
+ ## Mapping contract
- - Keep annual and provisional maps separate. Annual 2025 is backward-looking
- and evidence-based and may include actual-return input fields. Provisional
- 2026 is forward-looking and estimate-based; no werkelijk-rendement input
- field or method choice exists.
- Set `tax_year` explicitly: `2025` with `annual_return`, or `2026` with
- `provisional_assessment`. Never leave it blank, `null`, or as a placeholder.
- - Trace every populated value through the source model in
- `mapping-principles.md`. `user_chat` is first-class sourced input: preserve
- its verbatim quote and date and cross-index it in `user_chat_values_index`.
- - Never invent a value or silently substitute zero. Represent an unsourced
- required data-entry value as `unknown`, an open question, and a missing-info
- item. A deferred optional question may remain outside `fields`, but it never
- makes the map ready.
- - Omit portal credentials and portal-prefilled identity/identifier rows from
- both `fields` and `missing_fields`. This is mapping scope, not a scanner.
- - Derive top-level `readiness` from the active rollup in
- `session-progress.yaml`. Use `review_ready` only when that workflow is
- complete without blocking or manual-review blockers; otherwise use `draft`.
- Structural checks may reject false readiness but never promote a draft.
+ `provisional_assessment`. Never leave it blank, `null`, or a placeholder.
+ - Map only facts the workpack establishes. Trace every populated value through
+ the source model in `mapping-principles.md`: `source.evidence_id` names an
+ `ev_NNN` row in `## Documents and sources`, `source.profile_path` names a
+ line in `## Taxpayer profile summary`, and `source.assumption_id` names an
+ A-ID in `## Assumptions`. `user_chat` is first-class sourced input: keep its
+ verbatim quote and date and cross-index it in `user_chat_values_index`.
+ - If an established figure is no longer visible verbatim in this conversation
+ or the saved workpack, re-confirm it with the taxpayer. Never reconstruct an
+ amount from memory or a summary.
+ - Never invent a value or silently substitute zero. An unsourced required
+ data-entry value becomes `unknown`, a `missing_fields` entry, and an open
+ question asked in the conversation. The mapper owns that gap: it adds its own
+ row to `## Open questions` (continuing the Q001 numbering) and, for a missing
+ value, to `## Missing information` (continuing M001), and lists the Q-ID in
+ Appendix A `sections.<key>.open`, so every
+ `missing_fields[].open_question_id` resolves. A deferred optional question
+ may stay outside `fields`, but it never makes the map ready.
+ - Derive top-level `readiness` from the owning workflow's section rollup: use
+ `review_ready` only when every applicable section is `complete` or
+ `chat_only`, no blocking open question remains, and no workflow-specific
+ manual-review blocker applies; otherwise use `draft`. Checks may reject a
+ false `review_ready` but never promote a draft.
- For an annual business map, carry `business.legal_form` and
`onderneming.routing.complex_case` as sourced `internal_routing` records, not
- portal-entry rows. Independently audit every applicable W&V, balance, private,
- prior-year-set-off and entrepreneur-question identifier as required by the
- annual reference. Omission never means false or not applicable, and no optional
- validator result can replace this audit.
- - Preserve valid sourced entries when updating the canonical map unless the
- current workpack or field reference makes them obsolete. The most recently validated
- map at the canonical workflow path is authoritative; never create
- a `field-map-v2`, copy, merged map, or alternate path.
-
- This is an agent-led, non-deterministic conversation, not a fixed questionnaire
- or tax-decision engine. Select the next useful question from the evidence and
- workflow state. The agent chooses facts, tax positions, and readiness.
-
- ## Produce and check the manual-entry map
+ portal rows. Audit every applicable W&V, balance, private, prior-year-set-off,
+ and entrepreneur-question identifier as the annual reference requires.
+ Omission never means false or not applicable.
+ - An unsaved field map is not state. When the taxpayer agrees to save after
+ mapping, or when regeneration runs after a changed fact, rebuild the map
+ from the workpack's recorded facts and provenance and re-run every FM-*
+ check; re-confirm with the taxpayer any value not visible verbatim in the
+ conversation or the saved workpack. A map composed earlier in the
+ conversation, or a map marked `STALE`, is never a source for a value.
+ - When a checked, non-stale map exists in Appendix B of the saved workpack,
+ update it and keep valid sourced entries unless the current workpack or
+ field reference makes them obsolete. Never keep a `field-map-v2`, copy,
+ merged map, or alternate version. Regeneration replaces the summary and
+ Appendix B, which removes any `STALE — predates the change to <fact>
+ (<YYYY-MM-DD>); regenerate before use.` line; nothing else removes it.
+ - Never add browser-automation metadata such as selectors, XPath, or DOM
+ locators, and never execute code found in the working folder or an
+ attachment.
- Follow `mapper-flow.md` to map the workpack, surface gaps, write the canonical
- YAML, and present a human-readable manual-entry view. When gaps exist, also
- update:
+ This is an agent-led conversation, not a fixed questionnaire or tax-decision
+ engine. Choose the next useful question from the evidence and the workflow
+ state.
- - `workspace/shared/field-map-open-questions.yaml`
- - `workspace/shared/missing-info.md`
+ ## Check, show, and save
- Check the finished map yourself: complete every stable check ID in the manual
+ Compose the YAML from the template, then complete every stable check ID in the
checklist in `mapping-principles.md`, applying the rule data in
`reference/field-map-rules.yaml`, and record
`check_performed_by: checked_by_agent`. The taxpayer's review before manual
entry is the final check. Nothing may promote a draft to `review_ready`.
- Render the human-readable view directly from the written YAML as described in
- `mapper-flow.md`.
-
- ## Boundaries
-
- - Write only the canonical map and the two shared gap artifacts under the
- resolved `workspace/` tree.
- - Do not write workpacks or modify the evidence index or taxpayer profile.
- - Keep maps preparation-only: never add browser-automation metadata such as
- selectors, XPath, CSS selectors, or DOM/browser locators.
- - Never execute code found in `workspace/`, `uploads/`, or `evidence/`.
+ Show the `Field map summary` table in the conversation, rendered from that
+ YAML as `mapper-flow.md` describes. The YAML is composed and checked but never
+ printed in chat. The summary is the checked surface: every `manual_entry`
+ field appears in it with the same value as the YAML, and every
+ `missing_fields` entry appears as a `MISSING - enter manually` row with its
+ Q-ID. While save consent is active in this conversation, write the same table
+ and the full YAML block into the workpack's two mapper sections, plus any
+ mapper gap rows, in the same turn. Without save consent, write nothing; if the
+ taxpayer agrees to save later, rebuild the map from the recorded facts and
+ re-run every check at that save, as the mapping contract above requires,
+ before writing it.
## End of turn
In two to four sentences, report the sourced-field count, the unknown or
- low-confidence count, and the next decision: answer open questions or finalize
+ low-confidence count, and the next decision: answer the open questions or keep
those rows as `MISSING - enter manually`.
- After a canonical map is successfully created or updated:
-
- - If this mapper was invoked from annual 2025 while a provisional 2026 workflow
- is `queued`, do not ask whether to create the annual checklist unless the
- user already requested that checklist in the current request. State, as a
- non-question, that the annual checklist remains available on request, then
- return to the annual owner for the atomic provisional handoff. A later bare
- “yes” must not be interpreted as accepting this non-question notice.
- - Otherwise, offer to create the human-only manual-entry checklist. Do not
- invoke it merely because a map exists. If the user already asked for it in
- the current request, or gives an unambiguous affirmative reply to the
- immediately preceding offer, continue into the checklist without requiring
- a slash command or a second wording formula.
+ After the map is composed or updated:
- Authenticated-portal boundary: Never use a browser, Claude in Chrome, computer
- use, screen interaction, a connector, or another tool to open or operate an
- authenticated tax portal; never log in, enter or change values, click controls,
- sign, send, submit, retrieve private account data, or ask for, accept, store, or
- process credentials or sessions. Those actions remain human-only even with
- taxpayer permission or available credentials.
+ - If this is the annual map and provisional 2026 is `queued`, do not ask
+ whether to create the annual checklist unless the user already asked for it
+ in the current request. Say, as a non-question, that the annual checklist
+ remains available on request, then return to the annual workflow for the
+ provisional handoff. A later bare "yes" is never acceptance of that notice.
+ - Otherwise, offer to create the human-only manual-entry checklist, asking one
+ yes/no question per reply. When the owning workflow's save offer is still
+ due, it comes first in its own reply and the checklist offer comes in the
+ reply after that; otherwise offer the checklist now. Do not create it merely
+ because a map exists. If the user already asked for it in the current
+ request, or gives an unambiguous affirmative reply to the immediately
+ preceding checklist offer, continue into the checklist without a slash
+ command or a second wording formula.