playbooks

home / skills / lerianstudio / ring / regulatory-templates-setup

regulatory-templates-setup skill

/finops-team/skills/regulatory-templates-setup

This skill initializes regulatory template setup by guiding template selection and context initialization, ensuring valid dictionary status and audit-ready

npx playbooks add skill lerianstudio/ring --skill regulatory-templates-setup

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
9.6 KB
---
name: ring:regulatory-templates-setup
description: |
  Initial setup sub-skill - handles template selection and context initialization
  for the 3-gate regulatory workflow.

trigger: |
  - Called by regulatory-templates orchestrator at workflow start
  - Need to select template type and initialize context

skip_when: |
  - Not in regulatory-templates workflow
  - Setup already completed for current template

sequence:
  after: [regulatory-templates]
  before: [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

**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 |

---

### 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. Interactive validation required (~40 min). Proceed?"
- Options: "Proceed with interactive validation" | "Choose different template"
- Alert user: Query APIs → Suggest mappings → User approval each → Save as new dictionary

---

### 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) |

**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.

Overview

This skill performs the initial setup for the 3-gate regulatory workflow by managing template selection and initializing the full context object. It validates authority and template choices, checks dictionary availability, alerts users when interactive validation is required, and returns a complete context for downstream gates.

How this skill works

It asks the user to pick a regulatory authority and then a template option for that authority, using AskUserQuestion to record selections and preserve an audit trail. It checks the local dictionary path for a pre-configured dictionary to determine automatic vs interactive validation, alerts the user if interactive validation is required, applies any provided or default deadline, and builds a complete context object with all required fields and template-specific extensions.

When to use it

  • At the start of the regulatory-templates workflow to gather selections and initialize context
  • When you need an auditable template choice to prevent downstream spec errors
  • Before any gate executes so gates receive a complete, validated context
  • When dictionary availability must determine validation mode (auto vs interactive)
  • When a deadline must be set or defaulted for the selected template

Best practices

  • Always use AskUserQuestion for authority and template selection to avoid typos and create an audit trail
  • Do the dictionary status check against ~/.claude/docs/regulatory/dictionaries/{category}-{code}.yaml before initializing context
  • If no dictionary exists, alert the user and obtain explicit consent to proceed with interactive validation
  • Initialize every context field (authority, template_category, template_code, template_name, dictionary_status, documentation_path, deadline, gate1/gate2/gate3) — no shortcuts
  • Prefer returning a single complete context object to the parent skill to prevent mysterious gate failures

Example use cases

  • User starts a CADOC 4010 workflow: select BACEN → CADOC → 4010, check dictionary, return full context
  • User requests APIX integration: select BACEN → APIX → 002, confirm JSON API template and path, set deadline
  • No dictionary found for a chosen template: alert user, ask to proceed with interactive validation or choose another template
  • User omits a deadline: apply the standard default for the template type and record it in context

FAQ

What if the user already mentioned a template in their message?

You must still run AskUserQuestion to confirm authority and template selection to prevent typos and preserve the audit trail.

What determines automatic vs interactive validation?

Presence of a dictionary file at ~/.claude/docs/regulatory/dictionaries/{category}-{code}.yaml determines validation_mode; missing dictionary triggers interactive validation (~40 min) and requires user alert.