gh-lerianstudio-ring-finops-team/skills/regulatory-templates-setup/SKILL.md

name, description, trigger, skip_when, sequence

name	description	trigger	skip_when	sequence
regulatory-templates-setup	Initial setup sub-skill - handles template selection and context initialization for the 3-gate regulatory workflow.	- Called by regulatory-templates orchestrator at workflow start - Need to select template type and initialize context	- Not in regulatory-templates workflow - Setup already completed for current template	after before regulatory-templates regulatory-templates-gate1

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.

---

Setup Steps

Step 1: Regulatory Authority Selection

Use AskUserQuestion tool to present regulatory authority selection:

AskUserQuestion({
  questions: [
    {
      question: "Which regulatory authority template do you want to create?",
      header: "Authority",
      multiSelect: false,
      options: [
        {
          label: "CADOC",
          description: "BACEN - Cadastro de Clientes do SFN (select specific document next)"
        },
        {
          label: "e-Financeira",
          description: "RFB - SPED e-Financeira (select specific event next)"
        },
        {
          label: "DIMP",
          description: "RFB - Declaração de Informações sobre Movimentação Patrimonial"
        },
        {
          label: "APIX",
          description: "BACEN - Open Banking API (select specific API next)"
        }
      ]
    }
  ]
})

---

Step 1.1: Template Selection (Conditional by Authority)

Based on authority selected, show specific template options:

If "CADOC" selected:

AskUserQuestion({
  questions: [
    {
      question: "Which CADOC document do you want to create?",
      header: "CADOC",
      multiSelect: false,
      options: [
        {
          label: "4010",
          description: "Informações de Cadastro - Cadastral Information"
        },
        {
          label: "4016",
          description: "Informações de Operações de Crédito - Credit Operations"
        },
        {
          label: "4111",
          description: "Operações de Câmbio - Foreign Exchange Operations"
        }
      ]
    }
  ]
})

CADOC Template Details:

Code	Name	Description	Frequency
4010	Informações de Cadastro	Client cadastral data	Monthly
4016	Operações de Crédito	Credit operation details	Monthly
4111	Operações de Câmbio	Foreign exchange operations	Daily

---

If "e-Financeira" selected:

AskUserQuestion({
  questions: [
    {
      question: "Which e-Financeira event do you want to create?",
      header: "Event",
      multiSelect: false,
      options: [
        {
          label: "evtCadDeclarante",
          description: "Cadastro do Declarante - Entity registration (GIIN, FATCA/CRS)"
        },
        {
          label: "evtAberturaeFinanceira",
          description: "Abertura e-Financeira - Opens reporting period (semester)"
        },
        {
          label: "evtFechamentoeFinanceira",
          description: "Fechamento e-Financeira - Closes period and consolidates totals"
        },
        {
          label: "evtMovOpFin",
          description: "Movimento de Operações Financeiras - Semestral financial movements"
        }
      ]
    }
  ]
})

// If user selects "Other", show remaining events:
AskUserQuestion({
  questions: [
    {
      question: "Select additional e-Financeira event type:",
      header: "Event",
      multiSelect: false,
      options: [
        {
          label: "evtMovPP",
          description: "Movimento de Previdência Privada - Private pension (PGBL, VGBL)"
        },
        {
          label: "evtMovOpFinAnual",
          description: "Movimento de Operações Financeiras Anual - Annual consolidated"
        }
      ]
    }
  ]
})

e-Financeira Event Details:

Event Code	Event Name	Module	Frequency
evtCadDeclarante	Cadastro do Declarante	Structural	Per Period
evtAberturaeFinanceira	Abertura e-Financeira	Structural	Semestral
evtFechamentoeFinanceira	Fechamento e-Financeira	Structural	Semestral
evtMovOpFin	Mov. Operações Financeiras	Financial Operations	Semestral
evtMovPP	Mov. Previdência Privada	Private Pension	Semestral
evtMovOpFinAnual	Mov. Operações Fin. Anual	Financial Operations	Annual

---

If "DIMP" selected:

AskUserQuestion({
  questions: [
    {
      question: "Which DIMP version do you want to create?",
      header: "DIMP",
      multiSelect: false,
      options: [
        {
          label: "v10",
          description: "DIMP Versão 10 - Current version (Movimentação Patrimonial)"
        }
      ]
    }
  ]
})

DIMP Template Details:

Version	Name	Description	Frequency
v10	DIMP v10	Declaração de Informações sobre Movimentação Patrimonial	Annual

---

If "APIX" selected:

AskUserQuestion({
  questions: [
    {
      question: "Which APIX (Open Banking) API do you want to create?",
      header: "APIX",
      multiSelect: false,
      options: [
        {
          label: "001",
          description: "Dados Cadastrais - Registration/Customer Data API"
        },
        {
          label: "002",
          description: "Contas e Transações - Accounts & Transactions API"
        }
      ]
    }
  ]
})

APIX Template Details:

Code	Name	Description	Type
001	Dados Cadastrais	Customer registration data	REST API
002	Contas e Transações	Account balances and transactions	REST API

---

Selection Flow Diagram

┌─────────────────────────────────────┐
│ Step 1: Select Authority            │
│ ○ CADOC (BACEN)                     │
│ ○ e-Financeira (RFB)                │
│ ○ DIMP (RFB)                        │
│ ○ APIX (BACEN)                      │
└──────────────┬──────────────────────┘
               │
    ┌──────────┼──────────┬───────────┐
    ▼          ▼          ▼           ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ CADOC  │ │e-Financ│ │  DIMP  │ │  APIX  │
│────────│ │────────│ │────────│ │────────│
│○ 4010  │ │○ evtCad│ │○ v10   │ │○ 001   │
│○ 4016  │ │○ evtAbe│ │        │ │○ 002   │
│○ 4111  │ │○ evtFec│ │        │ │        │
│        │ │○ evtMov│ │        │ │        │
│        │ │○ evtPP │ │        │ │        │
│        │ │○ evtAnu│ │        │ │        │
└────────┘ └────────┘ └────────┘ └────────┘

Capture and extract:

• Authority (BACEN, RFB)
• Template category (CADOC, e-Financeira, DIMP, APIX)
• Template code (e.g., "4010", "evtMovOpFin", "v10", "001")
• Template name (full descriptive name)
• Additional metadata based on template type

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: Before initializing context, check if template has a data dictionary:

// Dictionary status check - MANDATORY
// STANDARDIZED DICTIONARY PATH
const DICTIONARY_BASE_PATH = "~/.claude/docs/regulatory/dictionaries";

const TEMPLATES_WITH_DICTIONARY = {
  "CADOC_4010": `${DICTIONARY_BASE_PATH}/cadoc-4010.yaml`,
  "CADOC_4016": `${DICTIONARY_BASE_PATH}/cadoc-4016.yaml`,
  "APIX_001": `${DICTIONARY_BASE_PATH}/apix-001.yaml`,
  "EFINANCEIRA_evtCadDeclarante": `${DICTIONARY_BASE_PATH}/efinanceira-evtCadDeclarante.yaml`
};

const TEMPLATES_WITHOUT_DICTIONARY = [
  "CADOC_4111",
  "APIX_002",
  "EFINANCEIRA_evtAberturaeFinanceira",
  "EFINANCEIRA_evtFechamentoeFinanceira",
  "EFINANCEIRA_evtMovOpFin",
  "EFINANCEIRA_evtMovPP",
  "EFINANCEIRA_evtMovOpFinAnual",
  "DIMP_v10"
];

function checkDictionaryStatus(templateKey) {
  if (TEMPLATES_WITH_DICTIONARY[templateKey]) {
    return {
      has_dictionary: true,
      dictionary_path: TEMPLATES_WITH_DICTIONARY[templateKey],
      validation_mode: "automatic"
    };
  } else {
    return {
      has_dictionary: false,
      dictionary_path: null,
      validation_mode: "interactive"
    };
  }
}

If template has NO dictionary, alert user with AskUserQuestion:

// Alert user about interactive validation requirement
if (!dictionaryStatus.has_dictionary) {
  await AskUserQuestion({
    questions: [{
      question: `⚠️ Template '${templateSelected}' does NOT have a pre-configured data dictionary.\n\n` +
                `This means you will need to MANUALLY VALIDATE each field mapping in Gate 1.\n\n` +
                `The process will:\n` +
                `1. Query API schemas (Midaz, CRM)\n` +
                `2. Suggest mappings for each regulatory field\n` +
                `3. Ask YOUR APPROVAL via selection boxes or custom typing\n` +
                `4. Save approved mappings as new dictionary for future use\n\n` +
                `Do you want to proceed?`,
      header: "Dictionary",
      multiSelect: false,
      options: [
        {
          label: "Proceed with interactive validation",
          description: "I'll validate each field mapping manually"
        },
        {
          label: "Choose different template",
          description: "Select a template that has pre-configured dictionary"
        }
      ]
    }]
  });
}

---

Step 4: Initialize Context Object

Create and return the complete initial context based on selections:

// Base context structure (common to all templates)
let context = {
  // From Step 1 - Authority selection
  authority: "BACEN", // or "RFB"
  template_category: "CADOC", // or "e-Financeira", "DIMP", "APIX"

  // From Step 1.1 - Template selection
  template_code: "4010", // specific code selected
  template_name: "Informações de Cadastro", // full name

  // Computed fields
  template_selected: "CADOC 4010", // combined identifier

  // Dictionary status (CRITICAL - determines validation mode)
  // STANDARDIZED PATH: ~/.claude/docs/regulatory/dictionaries/
  dictionary_status: {
    has_dictionary: true/false,
    dictionary_path: "~/.claude/docs/regulatory/dictionaries/cadoc-4010.yaml" or null,
    validation_mode: "automatic" or "interactive"
  },

  // Documentation reference (auto-resolved)
  documentation_path: ".claude/docs/regulatory/templates/BACEN/CADOC/cadoc-4010-4016.md",

  // Optional user input
  deadline: "2025-12-31", // or ask if needed

  // Gates (to be populated by subsequent sub-skills)
  gate1: null,
  gate2: null,
  gate3: null
};

---

Template-Specific Context Extensions

CADOC Context

const cadocContext = {
  ...baseContext,
  authority: "BACEN",
  template_category: "CADOC",
  template_code: "4010", // or "4016", "4111"
  template_name: "Informações de Cadastro",
  template_selected: "CADOC 4010",
  documentation_path: ".claude/docs/regulatory/templates/BACEN/CADOC/cadoc-4010-4016.md",
  format: "XML",
  frequency: "monthly" // or "daily" for 4111
};

e-Financeira Context

const efinanceiraContext = {
  ...baseContext,
  authority: "RFB",
  template_category: "e-Financeira",
  template_code: "evtMovOpFin", // event code selected
  template_name: "Movimento de Operações Financeiras",
  template_selected: "e-Financeira evtMovOpFin",
  documentation_path: ".claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md",
  format: "XML",

  // e-Financeira specific fields
  event_module: "financial_operations", // or "private_pension", "structural"
  event_category: "movement", // or "structural"
  event_frequency: "semestral", // or "annual", "per_period"
  fatca_applicable: true,
  crs_applicable: true
};

DIMP Context

const dimpContext = {
  ...baseContext,
  authority: "RFB",
  template_category: "DIMP",
  template_code: "v10",
  template_name: "DIMP Versão 10",
  template_selected: "DIMP v10",
  documentation_path: ".claude/docs/regulatory/templates/RFB/DIMP/dimp-v10-manual.md",
  format: "XML",
  frequency: "annual"
};

APIX Context

const apixContext = {
  ...baseContext,
  authority: "BACEN",
  template_category: "APIX",
  template_code: "001", // or "002"
  template_name: "Dados Cadastrais",
  template_selected: "APIX 001",
  documentation_path: ".claude/docs/regulatory/templates/BACEN/APIX/001/",
  format: "JSON",
  api_type: "REST"
};

---

Template Mapping Reference

const TEMPLATE_REGISTRY = {
  // CADOC Templates (BACEN)
  CADOC: {
    authority: "BACEN",
    templates: {
      "4010": {
        name: "Informações de Cadastro",
        description: "Client cadastral data",
        frequency: "monthly",
        format: "XML",
        documentation: ".claude/docs/regulatory/templates/BACEN/CADOC/cadoc-4010-4016.md"
      },
      "4016": {
        name: "Operações de Crédito",
        description: "Credit operation details",
        frequency: "monthly",
        format: "XML",
        documentation: ".claude/docs/regulatory/templates/BACEN/CADOC/cadoc-4010-4016.md"
      },
      "4111": {
        name: "Operações de Câmbio",
        description: "Foreign exchange operations",
        frequency: "daily",
        format: "XML",
        documentation: ".claude/docs/regulatory/templates/BACEN/CADOC/cadoc-4010-4016.md"
      }
    }
  },

  // e-Financeira Templates (RFB)
  "e-Financeira": {
    authority: "RFB",
    templates: {
      evtCadDeclarante: {
        name: "Cadastro do Declarante",
        module: "structural",
        category: "structural",
        frequency: "per_period",
        format: "XML",
        fatca_applicable: true,
        crs_applicable: true,
        description: "Entity registration with GIIN, FATCA/CRS categories",
        documentation: ".claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md"
      },
      evtAberturaeFinanceira: {
        name: "Abertura e-Financeira",
        module: "structural",
        category: "structural",
        frequency: "semestral",
        format: "XML",
        fatca_applicable: false,
        crs_applicable: false,
        description: "Opens reporting period (dtIni/dtFim)",
        documentation: ".claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md"
      },
      evtFechamentoeFinanceira: {
        name: "Fechamento e-Financeira",
        module: "structural",
        category: "structural",
        frequency: "semestral",
        format: "XML",
        fatca_applicable: true,
        crs_applicable: true,
        description: "Closes period, consolidates PP/OpFin/OpFinAnual totals",
        documentation: ".claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md"
      },
      evtMovOpFin: {
        name: "Movimento de Operações Financeiras",
        module: "financial_operations",
        category: "movement",
        frequency: "semestral",
        format: "XML",
        fatca_applicable: true,
        crs_applicable: true,
        description: "Financial movements - accounts, balances, income",
        documentation: ".claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md"
      },
      evtMovPP: {
        name: "Movimento de Previdência Privada",
        module: "private_pension",
        category: "movement",
        frequency: "semestral",
        format: "XML",
        fatca_applicable: false,
        crs_applicable: false,
        description: "Private pension movements - PGBL, VGBL, etc.",
        documentation: ".claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md"
      },
      evtMovOpFinAnual: {
        name: "Movimento de Operações Financeiras Anual",
        module: "financial_operations",
        category: "movement",
        frequency: "annual",
        format: "XML",
        fatca_applicable: true,
        crs_applicable: true,
        description: "Annual consolidated financial movements",
        documentation: ".claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md"
      }
    }
  },

  // DIMP Templates (RFB)
  DIMP: {
    authority: "RFB",
    templates: {
      v10: {
        name: "DIMP Versão 10",
        description: "Declaração de Informações sobre Movimentação Patrimonial",
        frequency: "annual",
        format: "XML",
        documentation: ".claude/docs/regulatory/templates/RFB/DIMP/dimp-v10-manual.md"
      }
    }
  },

  // APIX Templates (BACEN - Open Banking)
  APIX: {
    authority: "BACEN",
    templates: {
      "001": {
        name: "Dados Cadastrais",
        description: "Customer registration data API",
        api_type: "REST",
        format: "JSON",
        documentation: ".claude/docs/regulatory/templates/BACEN/APIX/001/"
      },
      "002": {
        name: "Contas e Transações",
        description: "Account balances and transactions API",
        api_type: "REST",
        format: "JSON",
        documentation: ".claude/docs/regulatory/templates/BACEN/APIX/002/"
      }
    }
  }
};

---

State Tracking Output

After completing setup, output:

SKILL: regulatory-templates-setup
STATUS: COMPLETE
TEMPLATE: {context.template_selected}
DEADLINE: {context.deadline}
NEXT: → Gate 1: Regulatory Compliance Analysis

---

Success Criteria

Setup is complete when:

• ✅ Template selected and validated
• ✅ Deadline established (input or default)
• ✅ Context object initialized with all values
• ✅ Documentation URL identified for selected template

---

Output

Return the complete context object to the parent skill for use in subsequent gates.