Regulatory Templates - Initial Setup

Overview

This sub-skill handles the initial setup phase for regulatory template creation, including template selection and context initialization.

Parent skill: regulatory-templates

Output: Complete initial context object with all selections and configurations

Foundational Principle

Setup initializes the foundation - errors here propagate through all 3 gates.

Setup is not "just configuration" - it's critical validation:

• Template selection: Wrong template = entire workflow on wrong regulatory spec (hours wasted)

• Context initialization: Incomplete context = gates fail mysteriously downstream

• Dictionary status check: Skipped check = lost automation, unnecessary interactive validation

• User awareness: No alert about validation mode = poor UX, blocked progress

Skipping setup steps means:

• Hard-coded context bypasses validation (typos, wrong versions)

• Missing values cause gate failures (debugging waste)

• Silent dictionary check = user unprepared for interactive validation

• No audit trail of selections (compliance gap)

Setup is the contract between user intent and gate execution. Get it wrong = everything downstream breaks.

When to Use

Called by: regulatory-templates skill at the beginning of the workflow

Purpose: Gather all user selections and initialize the context object that will flow through all gates

NO EXCEPTIONS - Setup Requirements Are Mandatory

Setup requirements have ZERO exceptions. Foundation errors compound through all gates.

Common Pressures You Must Resist

Pressure Your Thought Reality

Ceremony "User said CADOC 4010, skip selection" Validation confirms, prevents typos, initializes full context

Speed "Hard-code context, skip AskUserQuestion" Bypasses validation, loses audit trail, breaks contract

Simplicity "Dictionary check is file I/O ceremony" Check determines validation mode (auto vs interactive 40 min difference)

Efficiency "Skip user alert, they'll see validation later" Poor UX, unprepared user, blocked progress

Setup Requirements (Non-Negotiable)

Template Selection:

• ✅ REQUIRED: Use AskUserQuestion for authority and template selection

• ❌ FORBIDDEN: Hard-code based on user message, skip selection dialog

• Why: Validation confirms correct template, prevents typos, establishes audit trail

Dictionary Status Check:

• ✅ REQUIRED: Check ~/.claude/docs/regulatory/dictionaries/ for template dictionary

• ❌ FORBIDDEN: Skip check, assume no dictionary exists

• Why: Determines validation mode (automatic vs interactive = 40 min time difference)

User Alert:

• ✅ REQUIRED: Alert user if interactive validation required (no dictionary)

• ❌ FORBIDDEN: "They'll figure it out in Gate 1"

• Why: User preparedness, UX, informed consent for 40-min validation process

Complete Context:

• ✅ REQUIRED: Initialize ALL context fields (authority, template_code, template_name, dictionary_status, documentation_path)

• ❌ FORBIDDEN: Minimal context, "gates will add details later"

• Why: Incomplete context causes mysterious gate failures

The Bottom Line

Setup shortcuts = silent failures in all downstream gates.

Setup is foundation. Wrong template selection wastes hours on wrong spec. Missing context breaks gates mysteriously. Skipped checks lose automation.

If tempted to skip setup, ask: Am I willing to debug gate failures from incomplete initialization?

Rationalization Table

Excuse Why It's Wrong Correct Response

"User already said CADOC 4010" Validation confirms, prevents typos (4010 vs 4020) Run selection

"Hard-code context is faster" Bypasses validation, loses audit trail Use AskUserQuestion

"Dictionary check is ceremony" Determines 40-min validation mode difference Check dictionary

"They'll see validation in Gate 1" Poor UX, unprepared user Alert if interactive

"Just pass minimal context" Incomplete causes mysterious gate failures Initialize ALL fields

"Setup is just config" Foundation errors compound through 3 gates Setup is validation

If You Find Yourself Making These Excuses

STOP. You are rationalizing.

Setup appears simple but errors propagate through 4-6 hours of gate execution. Foundation correctness prevents downstream waste.

Severity Calibration

MUST classify setup issues using these severity levels:

Severity Definition Examples Gate Impact

CRITICAL BLOCKS workflow progression OR invalidates foundation

• Template not in registry- Authority selection invalid- Context initialization failed- Required field missing from context HARD BLOCK - Cannot proceed to Gate 1

HIGH REQUIRES resolution for accurate gate execution

• Dictionary status unknown- Documentation path missing- Template code incorrect- User not alerted about validation mode MUST resolve before Gate 1

MEDIUM SHOULD fix for optimal workflow

• Deadline not specified (using default)- Optional context fields missing- Documentation incomplete SHOULD resolve - document if deferred

LOW Minor improvements possible

• Context verbosity- Naming improvements- Additional metadata OPTIONAL - note in report

Classification Rules:

CRITICAL = ANY of:

• Template selection cannot be validated against registry

• Authority is not BACEN or RFB (invalid for Brazilian regulatory)

• Context object missing required fields (authority, template_code, template_name)

• Setup steps cannot complete

HIGH = ANY of:

• Dictionary status not checked (determines 40-min vs automatic validation)

• User not informed about interactive validation requirement

• Documentation path not set correctly

• Template metadata incomplete

Blocker Criteria - STOP and Report

You MUST distinguish between decisions you CAN make vs those requiring escalation.

Decision Type Examples Action

Can Decide Default deadline, context field ordering, documentation format Proceed with setup

MUST Escalate Template not in registry, user selection unclear, multiple valid authorities STOP and ask for clarification

CANNOT Override AskUserQuestion requirement, dictionary check, context completeness, user alert for interactive mode HARD BLOCK - Must complete before Gate 1

HARD GATES (STOP immediately):

• Template Not Found: Template missing from registry

• Ambiguous Selection: User response doesn't match available templates

• Missing Context: Required context fields cannot be populated

• Dictionary Check Skipped: Cannot determine validation mode without check

Escalation Message Template:

⛔ SETUP BLOCKER - Cannot Initialize Context

Issue: [Specific blocker] Impact: [What cannot be determined/initialized] Required: [What needs resolution]

Cannot proceed to Gate 1 until resolved.

Cannot Be Overridden

NON-NEGOTIABLE requirements (no exceptions, no user override):

Requirement Why NON-NEGOTIABLE Verification

AskUserQuestion for Selection Prevents typos, validates against registry, creates audit trail Used AskUserQuestion tool

Dictionary Status Check Determines validation mode (40-min difference) Checked dictionary path

User Alert for Interactive Mode UX requirement, informed consent for long process Alert shown if no dictionary

Complete Context Initialization Incomplete context causes mysterious gate failures ALL required fields populated

Template Registry Validation Ensures template exists and is supported Template verified in registry

CANNOT allow user to:

• Skip template selection ("I already told you CADOC 4010" = NO - validate anyway)

• Bypass dictionary check ("just assume no dictionary" = NO)

• Skip user alert ("they'll figure it out" = NO)

• Initialize partial context ("add missing fields later" = NO)

• Hard-code selections ("same as last time" = NO - run selection)

Pressure Resistance

See shared-patterns/pressure-resistance.md for universal pressure scenarios.

Setup-Specific Pressures

User Says Your Response

"I already said CADOC 4010, just start" "I MUST validate the selection against our registry. This takes 30 seconds and prevents typos (4010 vs 4020). Running AskUserQuestion now."

"Skip dictionary check, it doesn't exist" "I CANNOT skip the dictionary check. It determines if we need 40-minute interactive validation or can proceed automatically. Checking now."

"Don't alert me, just proceed" "I MUST inform you if interactive validation is required. This is a 40-minute process that requires your input. You need to be prepared."

"Just use the same template as last time" "I CANNOT hard-code previous selections. Each workflow MUST validate against current registry. Requirements may have changed."

"Setup is ceremony, go straight to analysis" "I CANNOT skip setup. It initializes the context that ALL gates depend on. Incomplete setup = mysterious failures in Gates 1-3."

Setup Steps

Step 1: Regulatory Authority Selection

AskUserQuestion: "Which regulatory authority template?"

Option Description

CADOC BACEN - Cadastro de Clientes do SFN

e-Financeira RFB - SPED e-Financeira

DIMP RFB - Declaração de Informações sobre Movimentação Patrimonial

APIX BACEN - Open Banking API

Novo template Qualquer regulação BACEN/RFB/CVM/SUSEP/outro não listado acima

Open system: The workflow supports ANY regulatory template, not just the pre-defined list. If the template is not listed, select "Novo template" and provide the spec.

Step 1.0: New Template Intake (only if "Novo template" selected)

If the user selects "Novo template", collect the following before proceeding:

AskUserQuestion (sequence):

• Template name — ex: "CADOC 4030", "DLO", "e-Financeira evtPatrimonio", "DECRED"

• Regulatory authority — BACEN | RFB | CVM | SUSEP | COAF | outro (especificar)

• Output format — XML | TXT (fixed-width) | HTML | CSV | JSON

• Official spec — URL do manual/circular oficial OU caminho de arquivo XSD/PDF (OBRIGATÓRIO)

• Reporter dev URL (optional) — URL do ambiente de desenvolvimento para validação pós-geração

Context additions for new templates:

is_new_template: true template_spec_url: "<URL fornecida>" template_spec_format: "<XML|TXT|HTML|CSV>" reporter_dev_url: "<URL ou null>" # for optional Test Gate

Alert user:

"Template novo detectado. Gate 1 irá extrair os campos da spec fornecida, usar pattern matching com templates existentes para sugerir mapeamentos, e salvar o dicionário automaticamente ao final. Na próxima execução deste template, o workflow será automático (~5 min)."

BLOCKER: If no official spec URL/file is provided → STOP. Cannot map fields without the authoritative specification.

Step 1.1: Template Selection (Conditional by Authority)

AskUserQuestion: Show template options based on authority selected:

Authority Question Options

CADOC "Which CADOC document?" 4010 (Cadastro), 4016 (Crédito), 4111 (Câmbio)

e-Financeira "Which event?" evtCadDeclarante, evtAbertura, evtFechamento, evtMovOpFin, evtMovPP, evtMovOpFinAnual

DIMP "Which version?" v10 (current)

APIX "Which API?" 001 (Cadastrais), 002 (Contas/Transações)

Template Registry:

Category Code Name Frequency Format FATCA/CRS

CADOC 4010 Informações de Cadastro Monthly XML N/A

CADOC 4016 Operações de Crédito Monthly XML N/A

CADOC 4111 Operações de Câmbio Daily XML N/A

e-Financeira evtCadDeclarante Cadastro do Declarante Per Period XML Yes/Yes

e-Financeira evtAberturaeFinanceira Abertura e-Financeira Semestral XML No/No

e-Financeira evtFechamentoeFinanceira Fechamento e-Financeira Semestral XML Yes/Yes

e-Financeira evtMovOpFin Mov. Operações Financeiras Semestral XML Yes/Yes

e-Financeira evtMovPP Mov. Previdência Privada Semestral XML No/No

e-Financeira evtMovOpFinAnual Mov. Operações Fin. Anual Annual XML Yes/Yes

DIMP v10 DIMP Versão 10 Annual XML N/A

APIX 001 Dados Cadastrais REST API JSON N/A

APIX 002 Contas e Transações REST API JSON N/A

Capture: Authority (BACEN/RFB), category, code, name, metadata

Step 2: Optional Deadline Input

If not provided by user, use standard deadline for the template type.

Step 3: Check Dictionary Status and Alert User

CRITICAL: Check dictionary BEFORE initializing context. Path: ~/.claude/docs/regulatory/dictionaries/{category}-{code}.yaml

Template Has Dictionary Validation Mode

CADOC_4010 ✅ Yes Automatic

CADOC_4016 ✅ Yes Automatic

APIX_001 ✅ Yes Automatic

EFINANCEIRA_evtCadDeclarante ✅ Yes Automatic

All others ❌ No Interactive

If NO dictionary exists → AskUserQuestion:

• Question: "Template has no pre-configured dictionary. Gate 1 will use batch approval by confidence level (~10-15 min). Proceed?"

• Options: "Proceed" | "Choose different template"

• Alert user: Gate 1 will query APIs → suggest mappings → batch approval by confidence level → auto-save dictionary for future use

Step 4: Initialize Context Object

Base context structure (ALL fields required):

Field Source Example

authority

Step 1 "BACEN" or "RFB"

template_category

Step 1 "CADOC", "e-Financeira", "DIMP", "APIX"

template_code

Step 1.1 "4010", "evtMovOpFin", "v10", "001"

template_name

Registry "Informações de Cadastro"

template_selected

Computed "CADOC 4010"

dictionary_status

Step 3 {has_dictionary, dictionary_path, validation_mode}

documentation_path

Registry ".claude/docs/regulatory/templates/..."

deadline

User/Default "2025-12-31"

gate1/gate2/gate3

Initialize null (populated by subsequent gates)

is_new_template

Step 1.0 false (default) or true (new template)

template_spec_url

Step 1.0 null (default) or URL/path of official spec

reporter_dev_url

Step 1.0 null (default) or Reporter dev environment URL

Template-Specific Extensions:

Category Extra Fields

CADOC format: "XML" , frequency: "monthly"/"daily"

e-Financeira format: "XML" , event_module , event_category , event_frequency , fatca_applicable , crs_applicable

DIMP format: "XML" , frequency: "annual"

APIX format: "JSON" , api_type: "REST"

Documentation Paths:

• CADOC: .claude/docs/regulatory/templates/BACEN/CADOC/cadoc-4010-4016.md

• e-Financeira: .claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md

• DIMP: .claude/docs/regulatory/templates/RFB/DIMP/dimp-v10-manual.md

• APIX: .claude/docs/regulatory/templates/BACEN/APIX/{code}/

State Tracking Output

Output on completion: SKILL: regulatory-templates-setup | STATUS: COMPLETE | TEMPLATE: {template_selected} | DEADLINE: {deadline} | NEXT: → Gate 1

Success Criteria

• ✅ Template selected and validated

• ✅ Deadline established (input or default)

• ✅ Context object initialized with ALL fields

• ✅ Dictionary status checked

Output: Return complete context object to parent skill.