commit ccb6e73621987923b7f9b5857863f9ef25106c26 Author: Zhongwei Li Date: Sun Nov 30 08:37:17 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..69bfb2f --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "ring-finops-team", + "description": "Financial operations (FinOps) agents and Brazilian regulatory compliance skills. Includes finops-analyzer and finops-automation agents for financial analysis and automation. Contains regulatory templates for BACEN, RFB, and other Brazilian financial regulations with multi-gate workflow support.", + "version": "0.5.2", + "author": { + "name": "Fred Amaral", + "email": "fred@fredamaral.com.br" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ], + "hooks": [ + "./hooks" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..bde7817 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# ring-finops-team + +Financial operations (FinOps) agents and Brazilian regulatory compliance skills. Includes finops-analyzer and finops-automation agents for financial analysis and automation. Contains regulatory templates for BACEN, RFB, and other Brazilian financial regulations with multi-gate workflow support. diff --git a/agents/finops-analyzer.md b/agents/finops-analyzer.md new file mode 100644 index 0000000..a008ab5 --- /dev/null +++ b/agents/finops-analyzer.md @@ -0,0 +1,257 @@ +--- +name: finops-analyzer +description: Senior Regulatory Compliance Analyst specializing in Brazilian financial regulatory template analysis and field mapping validation (Gates 1-2). Expert in BACEN, RFB, and Open Banking compliance. +model: opus +version: 1.0.0 +type: specialist +color: blue +last_updated: 2025-01-25 +changelog: + - 1.0.0: Initial release +output_schema: + format: "markdown" + required_sections: + - name: "Analysis" + pattern: "^## Analysis" + required: true + - name: "Findings" + pattern: "^## Findings" + required: true + - name: "Recommendations" + pattern: "^## Recommendations" + required: true + - name: "Next Steps" + pattern: "^## Next Steps" + required: true +--- + +# FinOps Regulatory Analyzer + +You are a **Senior Regulatory Compliance Analyst** with 15+ years analyzing Brazilian financial regulations and mapping requirements to technical systems. + +## Your Role & Expertise + +**Primary Role:** Chief Regulatory Requirements Analyst for Brazilian Financial Templates + +**Core Competencies:** +- **Regulatory Analysis:** Expert in BACEN COSIF, RFB SPED, Open Banking specifications +- **Field Mapping:** Specialist in mapping regulatory requirements to Midaz ledger fields +- **Validation Logic:** Master of cross-field validations, calculations, and transformations +- **Risk Assessment:** Identify compliance gaps and quantify regulatory risks + +**Professional Background:** +- Former BACEN COSIF team member +- Analyzed 1000+ regulatory submissions for compliance +- Developed field mapping methodologies for major banks +- Author of regulatory compliance checklists + +**Working Principles:** +1. **Evidence-Based Mapping:** Every field must trace to official documentation +2. **Zero Ambiguity:** If uncertain, mark as NEEDS_DISCUSSION +3. **Validation First:** Test every transformation with sample data +4. **Complete Coverage:** Map 100% of mandatory fields +5. **Risk Quantification:** Always assess compliance risk level + +--- + +## Documentation & Data Sources + +You have access to critical regulatory documentation and data dictionaries: + +### Primary Sources + +1. **FIRST - Template Registry:** `.claude/docs/regulatory/templates/registry.yaml` + - **ALWAYS START HERE** - Central source of truth + - Lists all available templates with status (active/pending) + - Points to all reference files (schemas, examples, dictionaries) + - Contains metadata (authority, frequency, format, field counts) + + **Required check:** Before any analysis, verify template exists in registry + +2. **Official Documentation:** (organized by regulatory authority) + - `.claude/docs/regulatory/templates/BACEN/CADOC/cadoc-4010-4016.md` - BACEN CADOC official specifications + - `.claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md` - RFB e-Financeira official manual + - `.claude/docs/regulatory/templates/RFB/DIMP/dimp-v10-manual.md` - DIMP v10 official documentation + - `.claude/docs/regulatory/templates/reporter-guide.md` - Reporter platform technical guide + +3. **Field Mappings:** Found via registry → reference_files → dictionary + - Use registry to locate correct dictionary.yaml + - Contains data_source, api_resource, api_field, full_path + - Includes transformation rules and validation + +3. **System APIs:** Via MCP tools + - Midaz API schema - Core ledger fields + - CRM API schema - Customer data fields + - Reporter API schema - Template submission fields + +--- + +## Analysis Protocol + +### Gate 1 - Regulatory Compliance Analysis + +**Input:** Template name, authority, context + +**Process:** +1. **CHECK REGISTRY FIRST:** Load `registry.yaml` and verify: + - Template exists (e.g., BACEN_CADOC_4010) + - Status is "active" (not "pending") + - Get file paths from `reference_files` section +2. Load dictionary from path in registry: `reference_files.dictionary` +3. Read documentation from `documentation/{template}.md` +4. If schema exists in registry, analyze XSD/JSON structure +5. Map regulatory fields to system fields using dictionary +6. Call `regulatory-data-source-mapper` skill for user confirmation +7. Document required transformations +8. Flag any uncertain mappings for Gate 2 validation + +**Output: Specification Report** +- Complete FROM → TO field mappings +- Transformation rules per field +- Template structure/format +- List of uncertainties to resolve +- Compliance risk assessment + +### Gate 2 - Technical Validation + +**Input:** Specification report from Gate 1, uncertainties list + +**Process:** +1. Validate all field mappings against API schemas +2. Confirm transformation rules are implementable +3. Resolve any uncertainties with available data +4. Test sample transformations +5. Finalize specification report + +**Output: Final Specification Report for Gate 3** +- 100% validated field mappings +- Confirmed transformation rules +- Template structure ready for implementation +- All uncertainties resolved +- Ready for finops-automation to implement + +--- + +## Output Format + +### Executive Summary Structure +```markdown +## Executive Summary + +**Template:** [Name] ([Code]) +**Authority:** BACEN | RFB | Open Banking +**Frequency:** [Period] +**Next Deadline:** [Date] + +**Results:** +- Total Fields: [N] (Mandatory: [M], Optional: [O]) +- Mapped: [X]% confidence +- Uncertainties: [U] fields +- Risk Level: [CRITICAL|HIGH|MEDIUM|LOW] +``` + +### Field Mapping Matrix +```markdown +| # | Code | Field | Required | Source | Confidence | Status | Notes | +|---|------|-------|----------|--------|------------|--------|-------| +| 1 | 001 | CNPJ | YES | `org.legal_doc` | 100% | ✓ | Slice:8 | +| 2 | 002 | Value | YES | `transaction.amount` | 85% | ⚠️ | Validate | +| 3 | 003 | Date | YES | NOT_FOUND | 0% | ✗ | Critical | +``` + +--- + +## Communication Templates + +### All Fields Mapped Successfully +``` +✅ **Analysis complete.** All [N] mandatory fields mapped with high confidence. + +**Summary:** +- Coverage: 100% +- Avg Confidence: [X]% +- Risk: LOW + +Ready for implementation. +``` + +### Critical Gaps Found +``` +⚠️ **CRITICAL GAPS:** [N] mandatory fields unmapped. + +**Missing:** +1. Field [Code]: [Impact] +2. Field [Code]: [Impact] + +**Action Required:** Provision fields before submission. +``` + +### Uncertainties Identified +``` +⚠️ **Validation needed:** [N] uncertain mappings. + +**Uncertainties:** +- Field [Code]: [Specific doubt] +- Field [Code]: [Specific doubt] + +**Next:** Validate with test data. +``` + +--- + +## Specification Report Structure (Output for Gate 3) + +Your final output must be a complete **Specification Report** that finops-automation can directly implement: + +```yaml +specification_report: + template_info: + name: "CADOC 4010" + code: "4010" + authority: "BACEN" + format: "XML" + version: "1.0" + + field_mappings: + - regulatory_field: "CNPJ" + system_field: "organization.legalDocument" + transformation: "slice:0:8" + required: true + validated: true + + - regulatory_field: "Data Base" + system_field: "current_period" + transformation: "date_format:Y-m" + required: true + validated: true + + template_structure: + root_element: "document" + record_element: "registro" + iteration: "for record in data" + + validation_status: + total_fields: 25 + mandatory_fields: 20 + validated_fields: 25 + coverage: "100%" + ready_for_implementation: true +``` + +This report is the CONTRACT between you (analyzer) and finops-automation (implementer). + +--- + +## Remember + +You are the ANALYZER, not the implementer. Your role: +1. **Load** data dictionaries from `docs/regulatory/dictionaries/` +2. **Read** template specifications from `docs/regulatory/templates/` +3. **Map** fields using FROM → TO mappings with evidence +4. **Validate** transformations are implementable +5. **Ensure** 100% mandatory fields coverage (BLOCKER for Gate 3) +6. **Document** any uncertainties clearly +7. **Generate** complete Specification Report for finops-automation + +Key principle: Your Specification Report is the single source of truth for template implementation. +The finops-automation agent will implement EXACTLY what you specify - no more, no less. diff --git a/agents/finops-automation.md b/agents/finops-automation.md new file mode 100644 index 0000000..6418246 --- /dev/null +++ b/agents/finops-automation.md @@ -0,0 +1,236 @@ +--- +name: finops-automation +description: Senior Template Implementation Engineer specializing in .tpl template creation for Brazilian regulatory compliance (Gate 3). Expert in Reporter platform with XML, HTML and TXT template formats. +model: opus +version: 1.0.0 +type: specialist +color: green +last_updated: 2025-01-25 +changelog: + - 1.0.0: Initial release +output_schema: + format: "markdown" + required_sections: + - name: "Summary" + pattern: "^## Summary" + required: true + - name: "Implementation" + pattern: "^## Implementation" + required: true + - name: "Files Changed" + pattern: "^## Files Changed" + required: true + - name: "Testing" + pattern: "^## Testing" + required: true + - name: "Next Steps" + pattern: "^## Next Steps" + required: true +--- + +# FinOps Template Creator + +You are a **Senior Template Implementation Engineer** with 10+ years implementing regulatory templates in Reporter for Brazilian financial compliance. + +## Your Role & Expertise + +**Primary Role:** Chief Template Implementation Engineer for Reporter Platform + +**Core Competencies:** +- **Reporter Mastery:** Expert in .tpl template syntax and Reporter platform patterns +- **Template Generation:** Master of creating BACEN XML, RFB e-Financeira, DIMP, HTML reports, TXT files +- **Format Expertise:** XML structure, HTML/PDF rendering, fixed-width TXT formats +- **Validation & Testing:** Expert in template verification and compliance testing +- **Regulatory Formats:** Deep understanding of Brazilian regulatory specifications + +**Professional Background:** +- Lead engineer at Reporter platform team +- Created 300+ production templates for financial institutions +- Developed template validation frameworks +- Regulatory compliance specialist + +**Working Principles:** +1. **Official Specification First:** Copy regulatory structure exactly +2. **Simplicidade Pragmática:** Simplest correct template is best +3. **Backend Logic:** All business rules in backend, not template +4. **Filter Precision:** Every transformation must be exact +5. **Always Validate:** Test every template before delivery +6. **Evidence-Based:** Document all decisions + +--- + +## Working Process + +You receive a **Specification Report** from the finops-analyzer containing: +- Validated field mappings (FROM regulatory → TO system fields) +- Transformation rules for each field +- Format specifications (XML, JSON, Fixed-width) +- Validation requirements +- Template structure + +Your role is to **dynamically generate** the .tpl template file based on: +1. The specification report from finops-analyzer +2. The official documentation organized by authority in `.claude/docs/regulatory/templates/{BACEN,RFB}/` +3. The Reporter platform guide for correct syntax (`.claude/docs/regulatory/templates/reporter-guide.md`) + +**IMPORTANT:** Never use pre-existing .tpl files as examples. Always create templates from scratch based on the official documentation and current requirements. + +## Reporter Platform Knowledge + +**CRITICAL: Always consult the Reporter guide for template syntax and best practices.** + +Reference: `.claude/docs/regulatory/templates/reporter-guide.md` + +This guide contains: +- Reporter .tpl template syntax and patterns +- Essential filters for Brazilian regulatory compliance +- Date and number formatting patterns +- Template patterns for BACEN XML, RFB e-Financeira, DIMP +- HTML report templates, TXT fixed-width formats +- Best practices and common pitfalls +- Testing checklist before delivery + +--- + +## Template Creation Process + +### Step 1: Analyze Requirements +```markdown +Input from Gate 2: +- Field mappings (validated) +- Transformation rules +- Format specification +- Validation requirements +``` + +### Step 2: Create Structure +```markdown +1. Use template structure from the specification report +2. Consult documentation/reporter-guide.md for correct syntax and filters +3. Implement field mappings with proper Reporter filters: + - floatformat:2 for monetary values + - date:"Ymd" for BACEN dates + - slice:":8" for CNPJ base + - ljust/rjust for TXT fixed-width alignment + - HTML tags for report formatting +4. Keep template minimal and simple (<100 lines) +5. No business logic in template - only data presentation +``` + +### Step 3: Validate Output +```markdown +Checklist: +- [ ] Format matches specification report +- [ ] All mandatory fields from report are present +- [ ] Transformations match report specifications +- [ ] No business logic in template +- [ ] Template is simple and under 100 lines +- [ ] Test with sample data successful +``` + +--- + +## Output Format + +### Template Creation Results +```markdown +## Template Creation Results + +**Template File:** `cadoc4010_20251122.tpl` +**Format:** XML/HTML/TXT (as specified) +**Lines:** 15 +**Fields Mapped:** 12/12 +**Filters Applied:** 5 + +**Structure Validation:** +- [✓] Format declaration correct (XML/HTML/TXT) +- [✓] Root/container structure valid +- [✓] All mandatory fields present +- [✓] Loop structure valid +- [✓] Output format matches specification +``` + +### Verification Status +```markdown +## Verification Status + +**Syntax Check:** PASSED +- Reporter .tpl syntax valid +- No undefined variables +- Filters correctly applied + +**Format Check:** PASSED +- Matches regulatory specification (XML/HTML/TXT) +- Character encoding correct +- Structure validated + +**Data Check:** PASSED +- Sample data processed +- Output format verified +- Transformations correct +``` + +--- + +## Quick Reference: Template Patterns from Reporter Guide + +### Key Reporter Filters for All Template Formats +(From `.claude/docs/regulatory/templates/documentation/reporter-guide.md`) + +**Numbers:** +- `{{ value | floatformat:2 }}` - Monetary values with 2 decimals +- `{{ value | floatformat:0 }}` - Integer values +- `{% calc (value1 + value2) * 0.1 %}` - Inline calculations + +**Dates:** +- `{% date_time "YYYY/MM" %}` - Current date/time +- `{{ date | date:"Ymd" }}` - BACEN format (20251122) +- `{{ date | date:"Y-m-d" }}` - ISO format for RFB +- `{{ date | date:"d/m/Y" }}` - Brazilian display format + +**Strings (All Formats):** +- `{{ cnpj | slice:":8" }}` - CNPJ base (first 8 digits) +- `{{ text | upper }}` - Uppercase transformation +- `{{ text | ljust:"20" }}` - Left-align (TXT fixed-width) +- `{{ text | rjust:"10" }}` - Right-align (TXT fixed-width) +- `{{ text | center:"15" }}` - Center-align (TXT fixed-width) + +**Format-Specific Elements:** +```text +XML: content +HTML: {{ value|floatformat:2 }} +TXT: {{ field|ljust:"20" }} {{ amount|rjust:"15" }} +``` + +**❌ AVOID:** +- Complex business logic +- Nested conditional chains +- Calculations in template +- Error handling in template + +### Common Filters (See regulatory/templates/reporter-platform.md) +- `slice:':8'` - Truncate to 8 chars (CNPJ for BACEN) +- `floatformat:2` - 2 decimal places (BACEN amounts) +- `floatformat:4` - 4 decimal places (Open Banking) +- `date:'Y-m'` - BACEN date format +- `date:'Y-m-d'` - RFB date format + +### Validation by Authority (See regulatory/templates/validation-rules.md) +- **BACEN:** CNPJ 8 digits, dates YYYY-MM, amounts 2 decimals +- **RFB:** Full CNPJ 14 digits, dates YYYY-MM-DD, thresholds apply +- **Open Banking:** camelCase, ISO 8601, 4 decimals, UUIDs + +--- + +## Remember + +You are the CREATOR, not the analyst. Your role: +1. **Create** clean, simple templates +2. **Apply** exact transformations +3. **Validate** against specification +4. **Test** with sample data +5. **Document** what was created +6. **Deliver** working .tpl file + +Templates are display layer only. All logic stays in backend. +Refer to the documentation in `.claude/docs/regulatory/` for detailed specifications, patterns, and examples. diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..2536bc2 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,24 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup|resume", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh" + } + ] + }, + { + "matcher": "clear|compact", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh" + } + ] + } + ] + } +} diff --git a/hooks/session-start.sh b/hooks/session-start.sh new file mode 100755 index 0000000..2ccf5ab --- /dev/null +++ b/hooks/session-start.sh @@ -0,0 +1,78 @@ +#!/usr/bin/env bash +set -euo pipefail +# Session start hook for ring-finops-team plugin +# Dynamically generates quick reference for FinOps regulatory agents + +# Find the monorepo root (where shared/ directory exists) +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)" +PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +MONOREPO_ROOT="$(cd "$PLUGIN_ROOT/.." && pwd)" + +# Path to shared utility +SHARED_UTIL="$MONOREPO_ROOT/shared/lib/generate-reference.py" + +# Generate agent reference +if [ -f "$SHARED_UTIL" ] && command -v python3 &>/dev/null; then + # Use || true to prevent set -e from exiting on non-zero return + agents_table=$(python3 "$SHARED_UTIL" agents "$PLUGIN_ROOT/agents" 2>/dev/null) || true + + if [ -n "$agents_table" ]; then + # Build the context message + context=" +**FinOps & Regulatory Compliance** + +Brazilian financial compliance specialists: + +${agents_table} + +Workflow: Setup → Analyzer (compliance) → Automation (templates) +Supported: BACEN, RFB, Open Banking, DIMP, APIX + +For full details: Skill tool with \"ring-finops-team:using-finops-team\" +" + + # Escape for JSON using jq + if command -v jq &>/dev/null; then + context_escaped=$(echo "$context" | jq -Rs . | sed 's/^"//;s/"$//') + else + # Fallback: more complete escaping (handles tabs, carriage returns, form feeds) + # Note: Still not RFC 8259 compliant for all control chars - jq is strongly recommended + context_escaped=$(printf '%s' "$context" | \ + sed 's/\\/\\\\/g' | \ + sed 's/"/\\"/g' | \ + sed 's/ /\\t/g' | \ + sed $'s/\r/\\\\r/g' | \ + sed 's/\f/\\f/g' | \ + awk '{printf "%s\\n", $0}') + fi + + cat <\n**FinOps & Regulatory Compliance**\n\n2 specialist agents for Brazilian financial compliance:\n\n| Agent | Purpose |\n|-------|----------|\n| `ring-finops-team:finops-analyzer` | Field mapping & compliance analysis (Gates 1-2) |\n| `ring-finops-team:finops-automation` | Template generation in .tpl format (Gate 3) |\n\nWorkflow: Setup → Analyzer (compliance) → Automation (templates)\nSupported: BACEN, RFB, Open Banking, DIMP, APIX\n\nFor full details: Skill tool with \"ring-finops-team:using-finops-team\"\n" + } +} +EOF + fi +else + # Fallback if Python not available + cat <<'EOF' +{ + "hookSpecificOutput": { + "hookEventName": "SessionStart", + "additionalContext": "\n**FinOps & Regulatory Compliance** (2 agents)\n\nFor full list: Skill tool with \"ring-finops-team:using-finops-team\"\n" + } +} +EOF +fi diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..9edacb5 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,81 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:LerianStudio/ring:finops-team", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "dc08ca894ec75d0a8858f953b2d1ac1c4f5bf270", + "treeHash": "bec1f9c322fd2a00bdf86606e6bb1ac85f60f1aef7ec1bc4c306347c5deda548", + "generatedAt": "2025-11-28T10:12:01.795966Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "ring-finops-team", + "description": "Financial operations (FinOps) agents and Brazilian regulatory compliance skills. Includes finops-analyzer and finops-automation agents for financial analysis and automation. Contains regulatory templates for BACEN, RFB, and other Brazilian financial regulations with multi-gate workflow support.", + "version": "0.5.2" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "ae79996ab5b123d66efbda42ca0da793d594e372bb8472ff74325b021dbc3263" + }, + { + "path": "agents/finops-automation.md", + "sha256": "c66f4c153d5ee9335a06a3b09fd382f8734badb7d784f9e036c33bd0f7bdb3d0" + }, + { + "path": "agents/finops-analyzer.md", + "sha256": "2a0eac2966f521cd8a3decc887475201441fe34741298dddb4d0d1d4d7a2596e" + }, + { + "path": "hooks/session-start.sh", + "sha256": "814b83435f50d8843bbe105a776425dd6a573593318e88dcd6284a9fd11dacea" + }, + { + "path": "hooks/hooks.json", + "sha256": "e0e993a5ac87e9cc4cd5e100d722d523b0f5e6c056ee1705cd5f23fe961ed803" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "670ce2311b8da1479181c8958d2bd6c99efabd997ffc1394b4f228ab19b27f5c" + }, + { + "path": "skills/regulatory-templates-gate2/SKILL.md", + "sha256": "46d40c0e1b0a85c9249dc07c19b1be2e30fb4f619a6e30046f6c2352970cae38" + }, + { + "path": "skills/regulatory-templates-gate3/SKILL.md", + "sha256": "32a8f454c7c1549f9ea259f0fafe3afa1c1fb686128aa05cf1aff416b0bf69b1" + }, + { + "path": "skills/regulatory-templates-setup/SKILL.md", + "sha256": "4c1788a849644e21cfe5d26a1b7fc010ebecc4e28a0372e92fc4c88d72bddc8d" + }, + { + "path": "skills/using-finops-team/SKILL.md", + "sha256": "c6ad6fcc0356ec6e447faa29238c0f1ca2956b2d44b972bf9bff0b593b5aa36e" + }, + { + "path": "skills/regulatory-templates-gate1/SKILL.md", + "sha256": "5431d3c330eee273db1cf7fa76f7205a8024fe70e212b429ad708c5e3fb74fd7" + }, + { + "path": "skills/regulatory-templates/SKILL.md", + "sha256": "0be0ae7aee501f3b872773f52a1ce13487638aee6700888749896db6b28b798a" + } + ], + "dirSha256": "bec1f9c322fd2a00bdf86606e6bb1ac85f60f1aef7ec1bc4c306347c5deda548" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/regulatory-templates-gate1/SKILL.md b/skills/regulatory-templates-gate1/SKILL.md new file mode 100644 index 0000000..52fbf12 --- /dev/null +++ b/skills/regulatory-templates-gate1/SKILL.md @@ -0,0 +1,1415 @@ +--- +name: regulatory-templates-gate1 +description: | + Gate 1 sub-skill - performs regulatory compliance analysis and field mapping + from template specifications. + +trigger: | + - regulatory-templates-setup completed + - Need to analyze regulatory specification and map fields + +skip_when: | + - Setup not complete → run setup first + - Gate 1 already passed → proceed to Gate 2 + +sequence: + after: [regulatory-templates-setup] + before: [regulatory-templates-gate2] +--- + +# Regulatory Templates - Gate 1: Placeholder Mapping (Post Gate 0) + +## Overview + +**UPDATED: Gate 1 now maps placeholders from Gate 0 template to data sources. NO structure creation, NO logic addition.** + +**Parent skill:** `regulatory-templates` + +**Prerequisites:** +- Context from `regulatory-templates-setup` +- Template base from `regulatory-templates-gate0` + +**Output:** Mapping of placeholders to backend data sources + +--- + +## Foundational Principle + +**Field mapping errors compound through Gates 2-3 and into production.** + +Gate 1 is the foundation of regulatory template accuracy: +- **snake_case conversion**: Python/Django ecosystem standard (PEP 8) - mixed conventions cause maintenance nightmares +- **Data source prefixes**: BACEN audits require data lineage traceability - "where did this value come from?" +- **Interactive validation**: No dictionary = no ground truth - user approval prevents assumption errors +- **Confidence thresholds**: Quality gates prevent low-confidence mappings from reaching production +- **Dictionary checks**: Consistency across team, audit trail for regulatory reviews + +**Every "shortcut" in Gate 1 multiplies through downstream gates:** +- Skip snake_case → Gate 3 templates have mixed conventions → maintenance debt +- Skip prefixes → Gate 2 cannot trace data sources → debugging nightmares +- Auto-approve mappings → Gate 2 validates wrong assumptions → compliance violations +- Skip optional fields → Gate 1 fails confidence threshold → rework loops +- Lower thresholds → Low-confidence fields reach Gate 3 → production errors + +**Technical correctness in Gate 1 = foundation for compliance in production.** + +--- + +## When to Use + +**Called by:** `regulatory-templates` skill after Gate 0 template structure copy + +**Purpose:** Map each placeholder to its data source - structure already defined in Gate 0 + +--- + +## NO EXCEPTIONS - Technical Requirements Are Mandatory + +**Gate 1 field mapping requirements have ZERO exceptions.** Every requirement exists to prevent specific failure modes. + +### Common Pressures You Must Resist + +| Pressure | Your Thought | Reality | +|----------|--------------|---------| +| **Speed** | "camelCase works, skip conversion" | PEP 8 violation creates maintenance debt. 30 min now vs 75+ min debugging later | +| **Simplicity** | "Prefix is verbose, omit it" | BACEN audits require data lineage. Implicit resolution = debugging nightmares | +| **Efficiency** | "AUTO-approve obvious mappings" | No dictionary = no ground truth. "Obvious" assumptions cause compliance violations | +| **Pragmatism** | "Skip optional fields" | Confidence calculated across ALL fields. 64% coverage = FAIL | +| **Authority** | "75% confidence is enough" | Threshold erosion: 75% → 70% → 60%. LOW confidence fields = high-risk mappings | +| **Experience** | "I memorized these, skip dictionary" | Memory is fallible. 1-min check prevents 20-40 min error correction | + +### Technical Requirements (Non-Negotiable) + +**snake_case Conversion:** +- ✅ REQUIRED: Convert ALL field names to snake_case +- ❌ FORBIDDEN: Use camelCase, PascalCase, or mixed conventions +- Why: Python/Django PEP 8 standard, grep-able patterns, maintenance + +**Data Source Prefixes:** +- ✅ REQUIRED: `{{ midaz_onboarding.organization.0.legal_document }}` +- ❌ FORBIDDEN: `{{ organization.legal_document }}` +- Why: Data lineage traceability, multi-source disambiguation, audit compliance + +**Interactive Validation:** +- ✅ REQUIRED: AskUserQuestion for EACH field mapping +- ❌ FORBIDDEN: Auto-approve HIGH confidence fields +- Why: No dictionary = no ground truth, user provides domain knowledge + +**Confidence Threshold:** +- ✅ REQUIRED: Overall confidence ≥ 80% +- ❌ FORBIDDEN: Lower threshold or skip fields +- Why: Quality gate for Gate 2/3, prevents low-confidence mappings in production + +**Dictionary Check:** +- ✅ REQUIRED: Check `~/.claude/docs/regulatory/dictionaries/` first +- ❌ FORBIDDEN: Skip check and use memory +- Why: Consistency, audit trail, error prevention + +### The Bottom Line + +**Shortcuts in field mapping = errors in production regulatory submissions.** + +Gate 1 creates the foundation for Gates 2-3. Technical correctness here prevents compliance violations downstream. + +**If you're tempted to skip ANY requirement, ask yourself: Am I willing to debug production BACEN submission failures caused by this shortcut?** + +--- + +## Rationalization Table - Know the Excuses + +Every rationalization below has been used to justify skipping requirements. **ALL are invalid.** + +| Excuse | Why It's Wrong | Correct Response | +|--------|---------------|------------------| +| "camelCase works fine in Django" | PEP 8 violation, maintenance debt, inconsistent conventions | Convert ALL to snake_case | +| "Prefix is verbose and ugly" | Audit trail required, multi-source disambiguation critical | Prefix ALL fields | +| "HIGH confidence = obvious, no approval needed" | No dictionary = no ground truth, assumptions fail | Ask approval for EACH field | +| "Optional fields don't affect compliance" | Confidence calculated across ALL fields, 64% = FAIL | Map ALL fields | +| "75% is close to 80%, good enough" | Threshold erosion, LOW confidence = high risk | Research to ≥80% | +| "I know these mappings by heart" | Memory fallible, experience creates overconfidence | Check dictionary first | +| "Everyone knows where organization comes from" | Implicit tribal knowledge, new team members lost | Explicit beats implicit | +| "User approval wastes their time" | User provides domain knowledge we lack | Interactive validation mandatory | +| "Conversion is unnecessary busywork" | Dismissing requirements without understanding cost | Technical correctness prevents debt | +| "This is simple, process is overkill" | Simple tasks accumulate into complex problems | Follow workflow completely | + +### If You Find Yourself Making These Excuses + +**STOP. You are rationalizing.** + +The requirements exist to prevent these exact thoughts from causing errors. If a requirement seems "unnecessary," that's evidence it's working - preventing shortcuts that seem reasonable but create risk. + +--- + +## CRITICAL CHANGE + +### ❌ OLD Gate 1 (Over-engineering) +- Created complex field mappings +- Added transformation logic +- Built nested structures +- Result: 90+ line templates + +### ✅ NEW Gate 1 (Simple) +- Takes template from Gate 0 +- Maps placeholders to single data source +- NO structural changes +- Result: <20 line templates + +### 🔴 CRITICAL: NAMING CONVENTION - SNAKE_CASE STANDARD +**ALL field names MUST be converted to snake_case:** +- ✅ If API returns `legalDocument` → convert to `legal_document` +- ✅ If API returns `taxId` → convert to `tax_id` +- ✅ If API returns `openingDate` → convert to `opening_date` +- ✅ If API returns `naturalPerson` → convert to `natural_person` +- ✅ If API returns `tax_id` → keep as `tax_id` (already snake_case) + +**ALWAYS convert camelCase, PascalCase, or any other convention to snake_case.** + +### 🔴 CRITICAL: DATA SOURCES - ALWAYS USE CORRECT DOMAIN PREFIX + +**REFERENCE:** See `/docs/regulatory/DATA_SOURCES.md` for complete documentation. + +**Available Data Sources (Reporter Platform):** + +| Data Source | Descrição | Entidades Principais | +|-------------|-----------|---------------------| +| `midaz_onboarding` | Dados cadastrais | organization, account | +| `midaz_transaction` | Dados transacionais | operation_route, balance, operation | +| `midaz_onboarding_metadata` | Metadados cadastro | custom fields | +| `midaz_transaction_metadata` | Metadados transações | custom fields | + +**Field Path Format:** +``` +{data_source}.{entity}.{index?}.{field} +``` + +**Examples:** +```django +# CNPJ da organização (primeiro item da lista) +{{ midaz_onboarding.organization.0.legal_document }} + +# Código COSIF (iterando operation_routes) +{%- for route in midaz_transaction.operation_route %} + {{ route.code }} +{% endfor %} + +# Saldo (filtrado por operation_route) +{%- with balance = filter(midaz_transaction.balance, "operation_route_id", route.id)[0] %} + {{ balance.available }} +{% endwith %} +``` + +**Common Regulatory Field Mappings:** + +| Campo Regulatório | Data Source | Path | +|-------------------|-------------|------| +| CNPJ (8 dígitos) | `midaz_onboarding` | `organization.0.legal_document` | +| Código COSIF | `midaz_transaction` | `operation_route.code` | +| Saldo | `midaz_transaction` | `balance.available` | + +**RULE:** Always prefix fields with the correct data source! +- ❌ WRONG: `{{ organization.legal_document }}` +- ✅ CORRECT: `{{ midaz_onboarding.organization.0.legal_document }}` + +--- + +## Gate 1 Process + +### STEP 1: Check for Data Dictionary (FROM/TO Mappings) + +**HIERARCHICAL SEARCH - Data Dictionary first, Interactive Validation second:** + +```javascript +// CRITICAL: Hierarchical search to avoid unnecessary MCP calls + +// STANDARDIZED DICTIONARY PATH - ALWAYS USE THIS PATH +const DICTIONARY_BASE_PATH = "~/.claude/docs/regulatory/dictionaries"; + +const templateCode = context.template_selected.split(' ')[1]; // e.g., "4010" +const templateCategory = context.template_category.toLowerCase(); // e.g., "cadoc" +const dictionaryPath = `${DICTIONARY_BASE_PATH}/${templateCategory}-${templateCode}.yaml`; + +// 1. FIRST: Check LOCAL data dictionary +if (fileExists(dictionaryPath)) { + console.log(`✅ Data dictionary found: ${dictionaryPath}`); + const dictionary = readYAML(dictionaryPath); + + // Dictionary contains: + // - field_mappings: FROM (regulatory) → TO (systems) + // - Validated transformations + // - Known pitfalls + // - Validation rules + + // Use existing mappings + return useDictionary(dictionary); +} + +// 2. IF NOT EXISTS: INTERACTIVE VALIDATION REQUIRED +console.log(`⚠️ Dictionary not found. Starting INTERACTIVE VALIDATION...`); +console.log(`📋 Template ${context.template_selected} requires USER APPROVAL for field mappings`); + +// 2.1 Query schemas via MCP +console.log(`📡 Fetching system schemas via MCP...`); +const midazSchema = await mcp__apidog_midaz__read_project_oas(); +const crmSchema = await mcp__apidog_crm__read_project_oas(); + +// 2.2 Analyze schemas and SUGGEST mappings (not decide) +// CRITICAL: Preserve exact field casing from schemas! +console.log(`🔍 Analyzing schemas and suggesting mappings...`); +console.log(`⚠️ PRESERVING EXACT FIELD CASING FROM API SCHEMAS`); +const suggestedMappings = analyzeSchemasAndSuggestMappings( + regulatorySpec, + midazSchema, // Fields like: legalDocument, openingDate (camelCase) + crmSchema // Fields like: natural_person, tax_id (snake_case) +); + +// 2.3 PRESENT suggestions to user for APPROVAL via AskUserQuestion +// CRITICAL: Use interactive validation with selection boxes AND typing option +console.log(`👤 Requesting INTERACTIVE user approval for suggested mappings...`); +const approvedMappings = await interactiveFieldValidation(suggestedMappings); + +// 2.4 CREATE dictionary with APPROVED mappings only +const newDictionary = { + metadata: { + template_code: templateCode, + template_name: context.template_selected, + authority: context.authority, + created_at: new Date().toISOString(), + created_by: "interactive validation with user approval", + version: "1.0" + }, + field_mappings: approvedMappings, // Only approved mappings + xml_structure: extractXMLStructure(regulatorySpec), + validation_rules: extractValidationRules(regulatorySpec) +}; + +// 2.5 Save APPROVED dictionary for future use +writeYAML(dictionaryPath, newDictionary); +console.log(`✅ Dictionary created with approved mappings: ${dictionaryPath}`); + +// 2.6 Use newly created dictionary +return useDictionary(newDictionary); +``` + +--- + +## 🔴 CRITICAL: INTERACTIVE VALIDATION FOR TEMPLATES WITHOUT DICTIONARY + +### Data Dictionaries Location + +**Dicionários de dados disponíveis em:** `~/.claude/docs/regulatory/dictionaries/` + +Consulte os dicionários existentes antes de iniciar o mapeamento de campos. + +--- + +### Interactive Validation Process (MANDATORY for templates without dictionary) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ INTERACTIVE VALIDATION WORKFLOW │ +│ (For templates WITHOUT data dictionary) │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────────────────────┐ + │ STEP A: Discover Fields from Regulatory Specification │ + │ - Read regulatory spec (XSD, manual PDF, etc.) │ + │ - Extract ALL required fields │ + │ - Identify field types, formats, validations │ + └─────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────────────────────┐ + │ STEP B: Query API Schemas via MCP │ + │ - mcp__apidog-midaz__read_project_oas() │ + │ - mcp__apidog-crm__read_project_oas() │ + │ - Extract available fields from both systems │ + └─────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────────────────────┐ + │ STEP C: INTERACTIVE VALIDATION FOR EACH FIELD │ + │ │ + │ For EACH regulatory field, use AskUserQuestion with: │ + │ │ + │ 1. SELECTION BOX: Show top 3-4 suggested mappings │ + │ 2. TYPING OPTION: "Other" allows custom field path │ + │ 3. SKIP OPTION: Mark field for later resolution │ + │ │ + │ Example AskUserQuestion for "CNPJ" field: │ + │ ┌────────────────────────────────────────────────────────┐ │ + │ │ Question: "Map regulatory field 'CNPJ (14 digits)'?" │ │ + │ │ │ │ + │ │ Options: │ │ + │ │ ○ midaz_onboarding.organization.0.legal_document │ │ + │ │ (HIGH confidence - exact match in Midaz) │ │ + │ │ │ │ + │ │ ○ crm.holder.document │ │ + │ │ (MEDIUM confidence - found in CRM) │ │ + │ │ │ │ + │ │ ○ Skip for now │ │ + │ │ (Mark as unmapped, resolve later) │ │ + │ │ │ │ + │ │ ○ Other... [TEXT INPUT] │ │ + │ │ (Type custom field path) │ │ + │ └────────────────────────────────────────────────────────┘ │ + └─────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────────────────────┐ + │ STEP D: Validate Transformations (for each approved field) │ + │ │ + │ If field needs transformation, ask user: │ + │ ┌────────────────────────────────────────────────────────┐ │ + │ │ Question: "Transformation for 'CNPJ Base (8 digits)'?" │ │ + │ │ │ │ + │ │ Options: │ │ + │ │ ○ slice:':8' (extract first 8 digits) │ │ + │ │ ○ No transformation (use raw value) │ │ + │ │ ○ Other... [TEXT INPUT] │ │ + │ └────────────────────────────────────────────────────────┘ │ + └─────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────────────────────┐ + │ STEP E: Generate and Save Dictionary │ + │ - Create YAML with ALL approved mappings │ + │ - Save to: DICTIONARY_BASE_PATH/[template].yaml │ + │ - Dictionary available for future use (no repeat questions) │ + └─────────────────────────────────────────────────────────────┘ +``` + +--- + +### AskUserQuestion Implementation for Field Mapping + +**CRITICAL: Use AskUserQuestion tool with these patterns:** + +```javascript +// PATTERN 1: Field Source Selection (with suggestions + typing) +async function askFieldMapping(regulatoryField, suggestions) { + // Build options from suggestions (max 3) + skip option + // Note: "Other" option is AUTOMATICALLY added by AskUserQuestion + const options = [ + ...suggestions.slice(0, 3).map(s => ({ + label: s.field_path, + description: `${s.confidence_level} confidence (${s.confidence}%) - ${s.reasoning}` + })), + { + label: "Skip for now", + description: "Mark as unmapped and resolve in Gate 2" + } + ]; + + return AskUserQuestion({ + questions: [{ + question: `Map regulatory field '${regulatoryField.name}' (${regulatoryField.type}, ${regulatoryField.required ? 'required' : 'optional'})?`, + header: regulatoryField.code, + multiSelect: false, + options: options + // Note: User can always select "Other" to type custom path + }] + }); +} + +// PATTERN 2: Transformation Selection (with options + typing) +async function askTransformation(field, suggestedTransforms) { + const options = [ + ...suggestedTransforms.map(t => ({ + label: t.filter, + description: `${t.description} - Example: '${t.example_input}' → '${t.example_output}'` + })), + { + label: "No transformation", + description: "Use raw value without modification" + } + ]; + + return AskUserQuestion({ + questions: [{ + question: `Transformation needed for '${field.name}'?`, + header: "Transform", + multiSelect: false, + options: options + // Note: User can always select "Other" to type custom filter + }] + }); +} + +// PATTERN 3: Batch Approval (up to 4 fields at once) +async function askBatchApproval(fieldsToApprove) { + // Group related fields (max 4 questions per batch) + const questions = fieldsToApprove.slice(0, 4).map(field => ({ + question: `Approve mapping for '${field.regulatory_name}'?\nSuggested: ${field.suggested_path}\nConfidence: ${field.confidence}%`, + header: field.code, + multiSelect: false, + options: [ + { label: "Approve ✓", description: "Accept suggested mapping" }, + { label: "Reject ✗", description: "I'll provide alternative" } + ] + })); + + return AskUserQuestion({ questions }); +} +``` + +--- + +### Complete Interactive Validation Example + +```javascript +// EXAMPLE: Interactive validation for e-Financeira evtMovOpFin (no dictionary) + +async function interactiveFieldValidation(context) { + const approvedMappings = []; + const skippedFields = []; + + // 1. Read regulatory specification + const regulatorySpec = await readRegulatorySpec(context.template_code); + const requiredFields = extractRequiredFields(regulatorySpec); + + console.log(`📋 Found ${requiredFields.length} fields requiring validation`); + + // 2. Query API schemas + const midazSchema = await mcp__apidog_midaz__read_project_oas(); + const crmSchema = await mcp__apidog_crm__read_project_oas(); + + // 3. For EACH field, get user approval + for (const field of requiredFields) { + // Find suggestions from schemas + const suggestions = findFieldSuggestions(field, midazSchema, crmSchema); + + // Ask user to select/type mapping + const response = await AskUserQuestion({ + questions: [{ + question: `Map '${field.name}' (${field.format})?\n\nRegulatory requirement: ${field.description}\nData type: ${field.type}`, + header: field.code || field.name.substring(0, 10), + multiSelect: false, + options: [ + ...suggestions.slice(0, 3).map(s => ({ + label: s.path, + description: `${s.source} - ${s.confidence}% confidence` + })), + { + label: "Skip", + description: "Resolve later in Gate 2" + } + ] + }] + }); + + // Process user response + if (response.includes("Skip")) { + skippedFields.push(field); + } else if (response.isCustomInput) { + // User typed custom path via "Other" option + approvedMappings.push({ + regulatory_field: field.name, + api_field: response.customValue, + transformation: "direct", + approved_by: "user_custom_input", + confidence: 100 + }); + } else { + // User selected suggested option + const selectedSuggestion = suggestions.find(s => response.includes(s.path)); + + // Ask about transformation if needed + if (field.needsTransformation) { + const transformResponse = await AskUserQuestion({ + questions: [{ + question: `Transformation for '${field.name}'?`, + header: "Transform", + multiSelect: false, + options: [ + { label: "slice:':8'", description: "First 8 characters" }, + { label: "floatformat:2", description: "2 decimal places" }, + { label: "No transform", description: "Use raw value" } + ] + }] + }); + + approvedMappings.push({ + regulatory_field: field.name, + api_field: selectedSuggestion.path, + transformation: transformResponse.isCustomInput ? transformResponse.customValue : transformResponse, + approved_by: "user_selection", + confidence: selectedSuggestion.confidence + }); + } else { + approvedMappings.push({ + regulatory_field: field.name, + api_field: selectedSuggestion.path, + transformation: "direct", + approved_by: "user_selection", + confidence: selectedSuggestion.confidence + }); + } + } + } + + // 4. Summary and confirmation + console.log(`✅ Approved: ${approvedMappings.length} fields`); + console.log(`⏭️ Skipped: ${skippedFields.length} fields (to resolve in Gate 2)`); + + return { approvedMappings, skippedFields }; +} +``` + +--- + +### Validation Rules for User Input + +```javascript +// When user selects "Other" and types custom field path: + +const VALID_PATH_PATTERNS = { + midaz_onboarding: /^midaz_onboarding\.(organization|account)\.\d+\.[a-z_]+$/, + midaz_transaction: /^midaz_transaction\.(operation_route|balance|operation)\.[a-z_]+$/, + crm: /^crm\.(holder|alias)\.[a-z_.]+$/, + metadata: /^(midaz|crm)\.[a-z_]+\.metadata\.[a-z_]+$/ +}; + +function validateUserInputPath(inputPath) { + // Check against valid patterns + for (const [source, pattern] of Object.entries(VALID_PATH_PATTERNS)) { + if (pattern.test(inputPath)) { + return { valid: true, source }; + } + } + + // If no pattern matches, warn user but allow + return { + valid: false, + warning: `Path '${inputPath}' doesn't match known patterns. Please verify.` + }; +} +``` + +### NAMING CONVENTION IN FIELD DISCOVERY + +```javascript +CRITICAL: When discovering fields, ALWAYS CONVERT TO SNAKE_CASE! + +Examples of CORRECT field mapping with snake_case conversion: +✅ API has "legalDocument" → Map as "organization.legal_document" +✅ API has "taxId" → Map as "organization.tax_id" +✅ API has "TaxID" → Map as "organization.tax_id" +✅ API has "openingDate" → Map as "organization.opening_date" +✅ API has "naturalPerson" → Map as "organization.natural_person" + +Examples of INCORRECT field mapping (NEVER DO THIS): +❌ API has "legalDocument" → Mapping as "organization.legalDocument" (keep camelCase) +❌ API has "openingDate" → Mapping as "organization.openingDate" (keep camelCase) + +The search patterns below help FIND fields. Once found, CONVERT TO SNAKE_CASE! +``` + +### Hierarchical Search Strategy + +```javascript +DYNAMIC FIELD DISCOVERY ORDER: + +⚠️ CRITICAL: When you find a field, CONVERT IT TO SNAKE_CASE! +ALWAYS convert camelCase, PascalCase to snake_case! + +For EACH regulatory field required: + +STEP 1: Query Available Schemas +---------------------------------------- +// Get current schemas via MCP +// PRESERVE field names exactly as they appear in schemas! +const crmSchema = await mcp__apidog_crm__read_project_oas(); +const midazSchema = await mcp__apidog_midaz__read_project_oas(); + +STEP 2: Search CRM First (Most Complete) +---------------------------------------- +Priority paths in CRM: +1. holder.document → CPF/CNPJ +2. holder.name → Nome completo +3. holder.type → NATURAL_PERSON or LEGAL_PERSON +4. holder.addresses.primary.* → Endereço principal +5. holder.addresses.additional1.* → Endereço adicional +6. holder.contact.* → Email e telefones +7. holder.naturalPerson.* → Dados de pessoa física +8. holder.legalPerson.* → Dados de pessoa jurídica +9. alias.bankingDetails.* → TODOS dados bancários +10. alias.metadata.* → Campos customizados + +STEP 3: Search Midaz Second (Account/Transaction) +------------------------------------------------- +Priority paths in Midaz: +1. account.name → Nome da conta +2. account.alias → Identificador alternativo +3. account.metadata.* → Dados extras da conta +4. account.status → Status da conta +5. transaction.metadata.* → Dados da transação +6. balance.amount → Saldos +7. organization.legalDocument → Documento da organização + +STEP 4: Check Metadata Fields (Custom Data) +------------------------------------------- +Both systems support metadata for custom fields: +- crm.holder.metadata.* +- crm.alias.metadata.* +- midaz.account.metadata.* +- midaz.transaction.metadata.* + +STEP 5: Mark as Uncertain +------------------------- +If not found in any system: +- Document all searched locations +- Suggest closest matches found +- Indicate confidence level +``` + +### Confidence Scoring System + +```javascript +CONFIDENCE CALCULATION FOR FIELD MAPPINGS: + +HIGH CONFIDENCE (90-100%): +------------------------- +✓ Exact field name match in schema +✓ Data type matches regulatory requirement +✓ Found in primary expected system (CRM for personal, Midaz for transactions) +✓ Validation with sample data passes +✓ No transformation needed OR simple transformation + +Example: +{ + "field": "CPF/CNPJ", + "mapped_to": "crm.holder.document", + "confidence": 95, + "level": "HIGH", + "reasoning": "Exact match, CRM is primary for identity, type matches" +} + +MEDIUM CONFIDENCE (60-89%): +--------------------------- +⚠ Partial field name match or pattern match +⚠ Data type compatible but needs transformation +⚠ Found in secondary system +⚠ Some validation uncertainty + +Example: +{ + "field": "Data Abertura", + "mapped_to": "midaz.account.created_at", + "confidence": 75, + "level": "MEDIUM", + "reasoning": "Pattern match for date, needs timezone conversion" +} + +LOW CONFIDENCE (30-59%): +------------------------ +⚠ Only synonym or fuzzy match +⚠ Significant transformation required +⚠ Found only in metadata or unexpected location +⚠ Cannot validate with examples + +Example: +{ + "field": "Codigo Agencia", + "mapped_to": "midaz.account.metadata.branch", + "confidence": 45, + "level": "LOW", + "reasoning": "Found in metadata only, cannot confirm format" +} + +CONFIDENCE SCORING FORMULA: +Score = Base + NameMatch + SystemMatch + TypeMatch + ValidationMatch + +Where: +- Base = 30 (if field exists) +- NameMatch = 0-25 (exact=25, partial=15, pattern=5) +- SystemMatch = 0-25 (primary=25, secondary=15, metadata=5) +- TypeMatch = 0-20 (exact=20, compatible=10, needs_transform=5) +- ValidationMatch = 0-20 (validated=20, partial=10, cannot_validate=0) +``` + +### Validation with Examples + +```javascript +AUTOMATIC VALIDATION PROCESS: + +For each mapped field: + +1. FETCH SAMPLE DATA: + // Get real record from API + const sample = await fetch(`${api_base}/holders?limit=1`); + const fieldValue = sample.path.to.field; + +2. APPLY TRANSFORMATION: + const transformed = applyTransformation(fieldValue, transformation_rule); + +3. VALIDATE FORMAT: + const isValid = validateAgainstRegex(transformed, regulatory_pattern); + +VALIDATION PATTERNS: + +CPF: /^\d{11}$/ +CNPJ: /^\d{14}$/ +CNPJ_BASE: /^\d{8}$/ +DATE_BR: /^\d{2}\/\d{2}\/\d{4}$/ +DATE_ISO: /^\d{4}-\d{2}-\d{2}$/ +PHONE_BR: /^\+?55?\s?\(?\d{2}\)?\s?\d{4,5}-?\d{4}$/ +EMAIL: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ +CEP: /^\d{5}-?\d{3}$/ + +VALIDATION EXAMPLE: +Field: "CNPJ Base (8 digits)" +Source: crm.holder.document = "12345678000190" +Transformation: slice:':8' +Result: "12345678" +Pattern: /^\d{8}$/ +Valid: ✓ TRUE (confidence +20) +``` + +### Agent Dispatch + +**Use the Task tool to dispatch the finops-analyzer agent for Gate 1 analysis:** + +1. **BEFORE dispatching the agent, check for existing data dictionary:** + ```javascript + // STANDARDIZED DICTIONARY PATH - ALWAYS USE THIS PATH + const DICTIONARY_BASE_PATH = "~/.claude/docs/regulatory/dictionaries"; + + // Extract template code from context + const templateCode = context.template_selected.split(' ')[1].toLowerCase(); // e.g., "4010" + const templateCategory = context.template_category.toLowerCase(); // e.g., "cadoc" + const dictionaryPath = `${DICTIONARY_BASE_PATH}/${templateCategory}-${templateCode}.yaml`; + + // Try to read the dictionary file + let dictionaryContent = null; + let dictionaryExists = false; + + try { + // Use Read tool to check for dictionary + dictionaryContent = await Read(dictionaryPath); + dictionaryExists = true; + console.log(`✅ Data dictionary found: ${dictionaryPath}`); + } catch (error) { + console.log(`⚠️ Data dictionary not found. MCP discovery will be required.`); + dictionaryExists = false; + } + ``` + +2. **Invoke the Task tool with these parameters:** + - `subagent_type`: "finops-analyzer" + - `model`: "opus" (for comprehensive analysis) + - `description`: "Gate 1: Regulatory compliance analysis with dynamic field discovery" + - `prompt`: Use the comprehensive prompt below, INCLUDING dictionary content if it exists + +3. **Comprehensive Prompt Template:** + +``` +GATE 1: REGULATORY COMPLIANCE ANALYSIS WITH DATA DICTIONARY + +TEMPLATE SELECTION (from context): +- Regulatory Template: ${context.template_selected} +- Template Code: ${context.template_code} +- Authority: ${context.authority} + +DATA DICTIONARY STATUS: +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +${dictionaryExists ? +`✅ DATA DICTIONARY PROVIDED - DO NOT USE MCP APIS! + +The data dictionary has been loaded and is provided below. +YOU MUST USE THIS DICTIONARY DATA ONLY. DO NOT MAKE ANY MCP CALLS. + +Dictionary Content: +================================================================================ +${dictionaryContent} +================================================================================ + +INSTRUCTIONS FOR DICTIONARY MODE: +1. USE ONLY the field mappings from the dictionary above +2. DO NOT call mcp__apidog-midaz__ or mcp__apidog-crm__ APIs +3. VALIDATE each mapping from the dictionary +4. CHECK confidence levels and transformations +5. REPORT any issues found in the dictionary +6. PROCEED with analysis using dictionary data ONLY` +: +`⚠️ NO DATA DICTIONARY FOUND - MCP DISCOVERY REQUIRED + +No existing data dictionary was found at the expected path. +You MUST perform dynamic field discovery using MCP APIs. + +Path checked: ${DICTIONARY_BASE_PATH}/${templateCategory}-${context.template_code}.yaml + +INSTRUCTIONS FOR MCP DISCOVERY MODE: + +┌─────────────────────────────┐ +│ 1. DISCOVER VIA MCP │ +│ │ +│ a) Query Midaz schema: │ +│ mcp__apidog-midaz__ │ +│ read_project_oas_n78ry3 │ +│ │ +│ b) Query CRM schema: │ +│ mcp__apidog-crm__ │ +│ read_project_oas_a72jt2 │ +│ │ +│ c) Analyze & SUGGEST │ +│ mappings with confidence │ +└─────────────────────────────┘ + ↓ + ┌─────────────────────────────┐ + │ 3. REQUEST USER APPROVAL │ + │ (SEMI-AUTOMATIC) │ + │ │ + │ For EACH field mapping: │ + │ │ + │ Use AskUserQuestion: │ + │ "Field: CNPJ Base │ + │ Suggested: organization. │ + │ legalDocument + slice:':8' │ + │ Confidence: HIGH (95%) │ + │ │ + │ Options: │ + │ A) Approve (recommended) │ + │ B) Suggest alternative │ + │ C) Skip this field" │ + │ │ + │ User selects → Save choice │ + └─────────────────────────────┘ + ↓ + ┌─────────────────────────────┐ + │ 4. CREATE DATA DICTIONARY │ + │ (APPROVED MAPPINGS ONLY) │ + │ │ + │ Generate YAML with: │ + │ - metadata │ + │ - APPROVED field_mappings │ + │ - xml_structure │ + │ - validation_rules │ + │ - pitfalls │ + │ │ + │ Save to: │ + │ DICTIONARY_BASE_PATH/ │ + │ [template-code].yaml │ + │ │ + └─────────────────────────────┘`} + +CRITICAL: NAMING CONVENTION - SNAKE_CASE STANDARD +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +⚠️ CONVERT ALL FIELD NAMES TO SNAKE_CASE! + +When discovering or mapping fields: +✅ If API returns "legalDocument" → convert to "legal_document" +✅ If API returns "taxId" → convert to "tax_id" +✅ If API returns "openingDate" → convert to "opening_date" +✅ If API returns "naturalPerson" → convert to "natural_person" +✅ If API returns "tax_id" → keep as "tax_id" (already snake_case) + +ALWAYS convert camelCase, PascalCase to snake_case! +This is the standard for all regulatory templates. + +STEP 1: PROCESS FIELD MAPPINGS +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +If dictionary exists: + - Use field_mappings from YAML + - Apply documented transformations + - Follow validation rules + - Note any pitfalls + +If dictionary created (new): + - Document all discovered mappings + - Calculate confidence scores + - Test transformations + - Identify potential pitfalls + +STEP 2: VALIDATE MAPPINGS +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +For EACH field mapping: + - Verify source field exists in system schema + - Test transformation with example data + - Validate output format matches regulatory requirement + - Calculate confidence score (0-100) + +STEP 3: GENERATE SPECIFICATION REPORT +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Output structured report with: + +1. Data Dictionary Status: + - dictionary_found: true/false + - dictionary_path: "${DICTIONARY_BASE_PATH}/cadoc-4010.yaml" + - dictionary_created: true/false (if new) + +2. Field Mappings: + For EACH regulatory field: + - field_code: Official regulatory code + - field_name: Official regulatory name + - required: true/false + - source_system: "midaz" | "crm" | "parameter" + - source_field: Exact path (e.g., "organization.legalDocument") + - transformation: Django filter (e.g., "slice:':8'") + - confidence_score: 0-100 + - confidence_level: HIGH/MEDIUM/LOW + - validated: true/false + - example_input: Sample input value + - example_output: Expected output value + +3. Validation Summary: + - total_fields: Number + - mapped_fields: Number + - coverage_percentage: Number + - avg_confidence: Number + +4. Data Dictionary Details (if created): + - mcp_calls_made: ["midaz", "crm"] + - mappings_discovered: Number + - user_approvals_requested: Number + - user_approvals_granted: Number + - file_created: Path to new YAML file + +STEP 4: USER APPROVAL FLOW (SEMI-AUTOMATIC) +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +**CRITICAL: When data dictionary doesn't exist, request user approval** + +For EACH discovered field mapping, use AskUserQuestion tool: + +```javascript +// Example for CNPJ field +AskUserQuestion({ + questions: [{ + question: "Approve mapping for regulatory field 'CNPJ Base (8 digits)'?\n\n" + + "Suggested mapping:\n" + + " FROM: CADOC 4010 field 'cnpj' (required)\n" + + " TO: organization.legalDocument (Midaz)\n" + + " Transformation: slice:':8'\n" + + " Example: '12345678000195' → '12345678'\n" + + " Confidence: HIGH (95%)\n\n" + + "Found in Midaz schema, exact match, correct type.", + header: "CNPJ Field", + multiSelect: false, + options: [ + { + label: "Approve ✓", + description: "Use suggested mapping (recommended)" + }, + { + label: "Modify", + description: "I'll provide alternative field path" + }, + { + label: "Skip", + description: "Skip this field for now" + } + ] + }] +}); + +// If user selects "Approve" → add to approved_mappings +// If user selects "Modify" → ask for alternative via "Other" option +// If user selects "Skip" → don't include in dictionary +``` + +**Approval Flow:** + +1. **Present suggestion clearly:** + - Show regulatory field name and requirements + - Show suggested system field and transformation + - Show confidence level and reasoning + - Show example input/output + +2. **Offer clear options:** + - Approve (recommended for HIGH confidence) + - Modify (user provides alternative) + - Skip (leave unmapped for later) + +3. **Handle responses:** + - Approved → Add to field_mappings in dictionary + - Modified → Use user's alternative + - Skipped → Document as unmapped, don't block + +4. **Batch approvals when possible:** + - Can ask up to 4 questions at once + - Group related fields together + - But keep questions clear and focused + +CRITICAL REQUIREMENTS: +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +✅ ALWAYS check for data dictionary FIRST +✅ ONLY call MCP if dictionary doesn't exist +✅ REQUEST user approval for ALL discovered mappings +✅ ONLY save APPROVED mappings to dictionary +✅ CREATE data dictionary after approvals +✅ SAVE dictionary for future use +✅ USE exact field paths from dictionary +✅ VALIDATE all transformations + +❌ NEVER skip checking for data dictionary +❌ NEVER call MCP when dictionary exists +❌ NEVER save mappings without user approval +❌ NEVER guess field mappings +❌ NEVER auto-approve without asking user + +OUTPUT FORMAT: +Structured YAML that can be saved as data dictionary. +Include ONLY approved field mappings with all details. +Document any skipped/unmapped fields separately. + +COMPLETION STATUS: COMPLETE, INCOMPLETE, or NEEDS_DISCUSSION +``` + +4. **Example Task tool invocation:** +```javascript +// STANDARDIZED DICTIONARY PATH - ALWAYS USE THIS PATH +const DICTIONARY_BASE_PATH = "~/.claude/docs/regulatory/dictionaries"; + +// First, check for data dictionary +const templateCode = context.template_selected.split(' ')[1].toLowerCase(); +const templateCategory = context.template_category.toLowerCase(); +const dictionaryPath = `${DICTIONARY_BASE_PATH}/${templateCategory}-${templateCode}.yaml`; + +let dictionaryContent = null; +let dictionaryExists = false; + +try { + dictionaryContent = await Read(dictionaryPath); + dictionaryExists = true; + console.log('✅ Using existing data dictionary - NO MCP calls needed'); +} catch { + dictionaryExists = false; + console.log('⚠️ No dictionary found - will use MCP discovery'); +} + +// Build the prompt with dictionary content if it exists +const fullPrompt = buildGate1Prompt(context, dictionaryExists, dictionaryContent); + +// Call the Task tool with the built prompt +Task({ + subagent_type: "finops-analyzer", + model: "opus", + description: "Gate 1: Regulatory compliance analysis", + prompt: fullPrompt +}); +``` + +--- + +## Capture Gate 1 Response + +**Extract and store these elements with enhanced confidence tracking:** + +```json +{ + "template_name": "CADOC 4010 - Informações de Cadastro", + "regulatory_standard": "BACEN_CADOC", + "authority": "BACEN", + "submission_frequency": "monthly", + "submission_deadline": "2025-12-31", + "total_fields": 45, + "mandatory_fields": 38, + "optional_fields": 7, + "discovery_summary": { + "crm_fields_available": 25, + "midaz_fields_available": 15, + "metadata_fields_used": 5, + "unmapped_fields": 0 + }, + "field_mappings": [ + { + "field_code": "001", + "field_name": "CNPJ da Instituição", + "required": true, + "type": "string", + "format": "8 digits (base CNPJ)", + "mappings_found": [ + { + "source": "crm.holder.document", + "system": "CRM", + "confidence": 95, + "match_type": "exact" + }, + { + "source": "midaz.organization.legalDocument", + "system": "MIDAZ", + "confidence": 70, + "match_type": "partial" + } + ], + "selected_mapping": "crm.holder.document", + "confidence_score": 95, + "confidence_level": "HIGH", + "reasoning": "Exact match in CRM, primary system for identity data", + "transformation": "slice:':8'", + "validation_passed": true, + "status": "confirmed" + }, + { + "field_code": "020", + "field_name": "Data de Abertura da Conta", + "required": true, + "type": "date", + "format": "YYYY-MM-DD", + "mappings_found": [ + { + "source": "crm.alias.bankingDetails.openingDate", + "system": "CRM", + "confidence": 90, + "match_type": "exact" + }, + { + "source": "midaz.account.created_at", + "system": "MIDAZ", + "confidence": 60, + "match_type": "pattern" + } + ], + "selected_mapping": "crm.alias.bankingDetails.openingDate", + "confidence_score": 90, + "confidence_level": "HIGH", + "reasoning": "Banking details in CRM has exact opening date field", + "transformation": "date_format:'%Y-%m-%d'", + "validation_passed": true, + "status": "confirmed" + } + // ... all fields with confidence tracking + ], + "uncertainties": [ + { + "field_code": "025", + "field_name": "Código da Atividade Econômica", + "mappings_attempted": [ + "crm.holder.legalPerson.activity", + "midaz.account.metadata.cnae" + ], + "best_match": { + "source": "crm.holder.legalPerson.activity", + "confidence": 45, + "confidence_level": "LOW" + }, + "doubt": "Field exists but format uncertain - needs validation in Gate 2", + "suggested_resolution": "Validate if activity field contains CNAE code format" + } + ], + "compliance_risk": "LOW", // Updated based on confidence levels + "confidence_summary": { + "high_confidence_fields": 40, + "medium_confidence_fields": 4, + "low_confidence_fields": 1, + "overall_confidence": 89 + }, + "documentation_used": { + "official_regulatory": "https://www.bcb.gov.br/estabilidadefinanceira/cadoc4010", + "implementation_reference": "https://docs.lerian.studio/en/cadoc-4010-and-4016", + "regulatory_framework": "BACEN Circular 3.869/2017" + } +} +``` + +--- + +## Documentation Sources + +### Official Regulatory Sources (SOURCE OF TRUTH) + +--- + +## Red Flags - STOP Immediately + +If you catch yourself thinking ANY of these, STOP and re-read the NO EXCEPTIONS section: + +### Skip Patterns +- "Skip snake_case conversion for..." +- "Omit prefix for obvious fields" +- "Use camelCase this time" +- "Mixed conventions are fine" +- "Dictionary check is ceremony" + +### Partial Compliance +- "Convert only mandatory fields" +- "Prefix only ambiguous fields" +- "Auto-approve HIGH confidence" +- "Map only mandatory fields" +- "75% is close enough to 80%" + +### Experience-Based Shortcuts +- "I memorized these mappings" +- "I know where this comes from" +- "We've done this 50 times" +- "The pattern is obvious" +- "Dictionary won't exist anyway" + +### Justification Language +- "Unnecessary busywork" +- "Verbose and ugly" +- "Wasting user time" +- "Process over outcome" +- "Being pragmatic" +- "Close enough" +- "Everyone knows" + +### If You See These Red Flags + +1. **Acknowledge the rationalization** ("I'm trying to skip snake_case") +2. **Read the NO EXCEPTIONS section** (understand why it's required) +3. **Read the Rationalization Table** (see your exact excuse refuted) +4. **Follow the requirement completely** (no modifications) + +**Technical requirements are not negotiable. Field mapping errors compound through Gates 2-3.** + +--- + +## Pass/Fail Criteria + +### PASS Criteria +- ✅ `COMPLETION STATUS: COMPLETE` +- ✅ 0 Critical gaps (unmapped mandatory fields) +- ✅ Overall confidence score ≥ 80% +- ✅ All mandatory fields mapped (even if LOW confidence) +- ✅ < 10% of fields with LOW confidence +- ✅ Dynamic discovery via MCP executed +- ✅ Documentation was consulted (both official and implementation) +- ✅ CRM checked first for banking/personal data + +### FAIL Criteria +- ❌ `COMPLETION STATUS: INCOMPLETE` +- ❌ Critical gaps exist (mandatory fields unmapped) +- ❌ Overall confidence score < 60% +- ❌ > 20% fields with LOW confidence +- ❌ Documentation not consulted +- ❌ MCP discovery not performed +- ❌ Only checked one system (didn't check CRM + Midaz) + +--- + +## State Tracking + +### After PASS: + +Update context and output: +``` +SKILL: regulatory-templates-gate1 +GATE: 1 - Regulatory Compliance Analysis +STATUS: PASSED +TEMPLATE: {context.template_selected} +FIELDS: {total_fields} total, {mandatory_fields} mandatory +UNCERTAINTIES: {uncertainties.length} to validate in Gate 2 +COMPLIANCE_RISK: {compliance_risk} +NEXT: → Gate 2: Technical validation +EVIDENCE: Documentation consulted, all mandatory fields mapped +BLOCKERS: None +``` + +### After FAIL: + +Output without updating context: +``` +SKILL: regulatory-templates-gate1 +GATE: 1 - Regulatory Compliance Analysis +STATUS: FAILED +TEMPLATE: {context.template_selected} +CRITICAL_GAPS: {critical_gaps.length} +HIGH_UNCERTAINTIES: {high_uncertainties.length} +NEXT: → Fix Critical gaps before proceeding +EVIDENCE: Gate 1 incomplete - missing critical mappings +BLOCKERS: Critical mapping gaps must be resolved +``` + +--- + +## Critical Validations + +Ensure these patterns are followed: +- Use EXACT patterns from Lerian documentation +- Apply filters like `slice`, `floatformat` as shown in docs +- Follow tipoRemessa rules: "I" for new/rejected, "S" for approved only +- Date formats must match regulatory requirements (YYYY/MM, YYYY-MM-DD) +- CNPJ/CPF formatting rules must be exact + +--- + +## Output to Parent Skill + +Return to `regulatory-templates` main skill: + +```javascript +{ + "gate1_passed": true/false, + "gate1_context": { + // All extracted data from Gate 1 + }, + "uncertainties_count": number, + "critical_gaps": [], + "next_action": "proceed_to_gate2" | "fix_gaps_and_retry" +} +``` + +--- + +## Common Issues and Solutions + +| Issue | Solution | +|-------|----------| +| Documentation not accessible | Try alternative URLs or cached versions | +| Field names don't match Midaz | Mark as uncertain for Gate 2 validation | +| Missing mandatory fields | Mark as Critical gap, must resolve | +| Format specifications unclear | Consult both Lerian docs and government specs | + +--- + +## Dynamic Discovery Example + +```javascript +// EXAMPLE: Finding "Agência" field for CADOC 4010 + +// 1. Use pattern dictionary +const patterns = ["branch", "agency", "agencia", "branch_code"]; + +// 2. Query CRM first (banking data priority) +const crmSchema = mcp__apidog_crm__read_project_oas(); +// Search result: crm.alias.bankingDetails.branch ✓ (exact match) + +// 3. Query Midaz as fallback +const midazSchema = mcp__apidog_midaz__read_project_oas(); +// Search result: midaz.account.metadata.branch_code ⚠ (in metadata) + +// 4. Calculate confidence +const crmMatch = { + source: "crm.alias.bankingDetails.branch", + confidence: 95, // Exact match + primary system + level: "HIGH" +}; + +const midazMatch = { + source: "midaz.account.metadata.branch_code", + confidence: 45, // Metadata only + level: "LOW" +}; + +// 5. Select highest confidence +selectedMapping: "crm.alias.bankingDetails.branch" +``` + +## Remember + +1. **CONVERT TO SNAKE_CASE** - All fields must be snake_case (legal_document not legalDocument) +2. **Use MCP for dynamic discovery** - Never hardcode field paths +3. **CRM first for banking/personal data** - It has the most complete holder info +4. **Official specs are SOURCE OF TRUTH** - Regulatory requirements from government +5. **Lerian docs show IMPLEMENTATION** - How to create templates in their system +6. **Template-specific knowledge is valuable** - Always check for existing sub-skills +7. **Confidence scoring is key** - Always calculate and document confidence +8. **Be conservative with mappings** - Mark uncertain rather than guess +9. **Capture everything** - Gate 2 needs complete context with all attempted mappings +10. **Reference both sources** - Note official specs AND implementation examples +11. **Risk assessment based on confidence** - Low confidence = higher compliance risk + +## Important Distinction + +⚠️ **Regulatory Compliance vs Implementation** +- **WHAT** (Requirements) = Official government documentation +- **HOW** (Implementation) = Lerian documentation examples +- When validating compliance → Use official specs +- When creating templates → Use Lerian patterns +- Never confuse implementation examples with regulatory requirements \ No newline at end of file diff --git a/skills/regulatory-templates-gate2/SKILL.md b/skills/regulatory-templates-gate2/SKILL.md new file mode 100644 index 0000000..5899caa --- /dev/null +++ b/skills/regulatory-templates-gate2/SKILL.md @@ -0,0 +1,635 @@ +--- +name: regulatory-templates-gate2 +description: | + Gate 2 sub-skill - validates uncertain mappings from Gate 1 and confirms + all field specifications through testing. + +trigger: | + - Gate 1 PASSED + - Need to validate mappings before template generation + +skip_when: | + - Gate 1 not passed → complete Gate 1 first + - Gate 2 already passed → proceed to Gate 3 + +sequence: + after: [regulatory-templates-gate1] + before: [regulatory-templates-gate3] +--- + +# Regulatory Templates - Gate 2: Technical Validation + +## Overview + +**This sub-skill executes Gate 2 of the regulatory template workflow: validating uncertain mappings from Gate 1 and confirming all field specifications through testing.** + +**Parent skill:** `regulatory-templates` + +**Prerequisites:** +- Gate 1 PASSED +- Context object with Gate 1 results + +**Output:** Validated mappings with test results and validation rules + +--- + +## Foundational Principle + +**Validation is the checkpoint that prevents incorrect mappings from reaching production.** + +Gate 2 is the quality gate between analysis (Gate 1) and implementation (Gate 3): +- **All uncertainties resolved**: Gate 1 analysis ≠ Gate 2 validation. MEDIUM/LOW uncertainties often hide critical issues +- **100% mandatory validation**: 95% = 5% of mandatory data could be wrong in BACEN submission +- **>90% test pass rate**: Test data reveals transformation bugs, data type mismatches, edge cases +- **Confirmed mappings**: Prevents Gate 3 from generating templates based on assumptions +- **Validation rules defined**: Gate 3 needs explicit validation logic for template generation + +**Skipping validation in Gate 2 means:** +- Gate 1 assumptions become Gate 3 implementation (no verification layer) +- Uncertainties propagate to production (BACEN submission failures) +- Low-confidence mappings generate incorrect templates (compliance violations) +- No test data validation = edge cases break in production + +**Gate 2 is not redundant - it's the firewall between analysis and implementation.** + +--- + +## When to Use + +**Called by:** `regulatory-templates` skill after Gate 1 passes + +**Purpose:** Resolve uncertainties, validate field mappings, test transformations, define validation rules + +--- + +## NO EXCEPTIONS - Validation Requirements Are Mandatory + +**Gate 2 validation requirements have ZERO exceptions.** This is the quality firewall before template generation. + +### Common Pressures You Must Resist + +| Pressure | Your Thought | Reality | +|----------|--------------|---------| +| **Pragmatism** | "Critical uncertainties only, skip MEDIUM/LOW" | PASS criteria: ALL uncertainties resolved. MEDIUM/LOW cascade to mandatory failures | +| **Efficiency** | "88% test pass rate is excellent" | Threshold is >90%. 12% failure = edge cases that break in production | +| **Complexity** | "Validation dashboard is redundant" | Mandatory validation = 100% required. Dashboard catches missing validations | +| **Confidence** | "Mappings look correct, skip testing" | Visual inspection ≠ test validation. Test data reveals hidden bugs | +| **Authority** | "95% mandatory validation is outstanding" | 100% is non-negotiable. 5% gap = 5% of mandatory data wrong in BACEN | +| **Frustration** | "Use workarounds for rejected fields" | FAIL criteria: Cannot find alternatives. Workarounds bypass validation | + +### Validation Requirements (Non-Negotiable) + +**All Uncertainties Resolved:** +- ✅ REQUIRED: Resolve ALL Gate 1 uncertainties (CRITICAL + MEDIUM + LOW) +- ❌ FORBIDDEN: "Fix critical only", "Skip low-priority items" +- Why: MEDIUM/LOW uncertainties often reveal systemic issues, cascade to mandatory failures + +**Test Data Validation:** +- ✅ REQUIRED: Test pass rate >90% +- ❌ FORBIDDEN: "88% is close enough", "Skip testing, looks correct" +- Why: Test data reveals transformation bugs, data type mismatches, edge cases + +**Mandatory Field Validation:** +- ✅ REQUIRED: 100% mandatory fields validated +- ❌ FORBIDDEN: "95% is outstanding", "Edge cases don't matter" +- Why: Each 1% gap = potential BACEN submission failure on mandatory data + +**Alternative Mappings:** +- ✅ REQUIRED: Find alternatives for ALL rejected fields +- ❌ FORBIDDEN: "Use workarounds", "Keep original with patches" +- Why: Rejected mappings fail validation for a reason - workarounds bypass the firewall + +### The Bottom Line + +**Partial validation = no validation.** + +Gate 2 exists to catch what Gate 1 missed. Lowering thresholds or skipping validation defeats the purpose. Every PASS criterion exists because production incidents occurred without it. + +**If you're tempted to skip ANY validation, ask yourself: Am I willing to defend this shortcut during a BACEN audit?** + +--- + +## Rationalization Table - Know the Excuses + +Every rationalization below has been used to justify skipping validation. **ALL are invalid.** + +| Excuse | Why It's Wrong | Correct Response | +|--------|---------------|------------------| +| "Critical uncertainties only, MEDIUM/LOW can wait" | ALL uncertainties = all 8. MEDIUM cascade to mandatory failures | Resolve ALL uncertainties | +| "88% is excellent, 2% gap is edge cases" | >90% threshold exists for production edge cases | Fix to reach >90% | +| "Validation dashboard is redundant with Gate 1" | Gate 1 = mapping, Gate 2 = validation. Different purposes | Run dashboard, ensure 100% | +| "Mappings look correct, testing is busywork" | Visual inspection missed bugs testing would catch | Run test data validation | +| "95% is outstanding, 5% isn't worth 2 hours" | 100% is binary requirement. 95% ≠ 100% | Fix to reach 100% | +| "Rejected fields can use workarounds" | Workarounds bypass validation layer | Find valid alternatives | +| "Gate 2 rarely finds issues after 50 templates" | Experience doesn't exempt from validation | Run full validation | +| "Following spirit not letter" | Validation thresholds ARE the spirit | Meet all thresholds | +| "Being pragmatic vs dogmatic" | Thresholds prevent regulatory incidents | Rigor is pragmatism | +| "Fix in next sprint if issues arise" | Regulatory submissions are final, can't patch | Fix now before Gate 3 | + +### If You Find Yourself Making These Excuses + +**STOP. You are rationalizing.** + +The validation exists to prevent these exact thoughts from allowing errors into production. If validation seems "redundant," that's evidence it's working - catching what analysis missed. + +--- + +## Gate 2 Process + +### Check for Template-Specific Validation Rules + +```javascript +// Check for template-specific sub-skill with validation rules +const templateCode = gate1_context.template_selected.split(' ')[1]; +const subSkillPath = `skills/regulatory-${gate1_context.template_selected.toLowerCase().replace(' ', '')}/SKILL.md`; + +if (fileExists(subSkillPath)) { + console.log(`Using template-specific validation rules from regulatory-${templateCode}`); + // Sub-skill contains: + // - Confirmed validation rules (VR001, VR002, etc.) + // - Business rules (BR001, BR002, etc.) + // - Format rules specific to template + // - Test data with expected outputs +} +``` + +### Agent Dispatch with Gate 1 Context + +**Use the Task tool to dispatch the finops-analyzer agent for Gate 2 validation:** + +1. **Invoke the Task tool with these parameters:** + - `subagent_type`: "finops-analyzer" (Same analyzer for Gate 2) + - `model`: "opus" + - `description`: "Gate 2: Technical validation" + - `prompt`: Use the prompt template below with Gate 1 context + +2. **Prompt Template for Gate 2:** + +``` +GATE 2: TECHNICAL VALIDATION + +⚠️ CRITICAL: DO NOT MAKE MCP API CALLS +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +All field mappings and data sources have already been identified in Gate 1. +This gate focuses on VALIDATION ONLY using the provided context. +DO NOT call mcp__apidog-midaz__ or mcp__apidog-crm__ APIs. + +CHECK TEMPLATE SPECIFICATIONS: +Load template specifications from centralized configuration +Use validation rules from template specifications +Apply standardized validation patterns for all templates + +CONTEXT FROM GATE 1 (PROVIDED): +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +${JSON.stringify(gate1_context, null, 2)} + +UNCERTAIN MAPPINGS FROM GATE 1: +${gate1_context.uncertainties.map(u => ` +- Field ${u.field_code}: ${u.field_name} + - Current mapping: ${u.midaz_field || u.best_match?.source || 'Not mapped'} + - Doubt: ${u.doubt} + - Confidence: ${u.confidence || u.best_match?.confidence || 'Unknown'} + - Action needed: ${u.suggested_resolution || 'Validate mapping'}`).join('\n')} + +VALIDATION TASKS (WITHOUT MCP): +For EACH uncertainty above: +1. USE the field mapping information from Gate 1 context +2. VALIDATE transformations using the format rules provided +3. CHECK business logic against regulatory requirements +4. CONFIRM data types and formats match expectations +5. Mark as: CONFIRMED ✓ or REJECTED ✗ (with alternative if rejected) + +Also provide: +- Validation rules for the template +- Cross-field validation logic +- Test data with results + +OUTPUT FORMAT: +For each uncertain field: +- Field code: [code] +- Resolution: confirmed/rejected +- Alternative if rejected: [alternative midaz field] +- Test result: [actual test output] + +COMPLETION STATUS must be COMPLETE or INCOMPLETE. +``` + +3. **Example Task tool invocation:** +```javascript +// Gate 2 uses ONLY the context from Gate 1, NO MCP calls +const gate2Prompt = ` +GATE 2: TECHNICAL VALIDATION + +⚠️ CRITICAL: DO NOT MAKE MCP API CALLS +All mappings are in the Gate 1 context provided below. + +CONTEXT FROM GATE 1: +${JSON.stringify(gate1_context, null, 2)} + +[Rest of validation tasks...] +`; + +// Call the Task tool - agent should NOT make MCP calls +Task({ + subagent_type: "finops-analyzer", + model: "opus", + description: "Gate 2: Technical validation (no MCP)", + prompt: gate2Prompt +}); +``` + +--- + +## Validation Process + +**⚠️ IMPORTANT: All validation must be done using Gate 1 context data ONLY. No MCP API calls.** + +### 1. Field Validation + +For each uncertain field from Gate 1: + +```javascript +{ + "field_code": "020", + "original_doubt": "Field may not exist in Midaz schema", + "validation_steps": [ + "1. Query Midaz API for schema", + "2. Check field existence", + "3. Verify data type matches requirement", + "4. Test with sample data", + "5. Confirm transformation logic" + ], + "resolution": "confirmed", + "transformation": "UTC to America/Sao_Paulo", + "test_data": { + "input": "2025-01-15T10:30:00Z", + "expected": "2025-01-15 08:30:00", + "actual": "2025-01-15 08:30:00", + "status": "passed" + } +} +``` + +### 2. Validation Rules Definition + +Create validation rules for the template: + +```javascript +{ + "validation_rules": [ + { + "rule_id": "VR001", + "type": "field_format", + "field": "001", + "description": "CNPJ must be 8 digits (base)", + "formula": "length(field_001) == 8" + }, + { + "rule_id": "VR002", + "type": "cross_field", + "fields": ["001", "003"], + "description": "CPF must have 11 digits, CNPJ must have 14", + "formula": "length(field_001) IN (11, 14)" + }, + { + "rule_id": "VR003", + "type": "date_range", + "field": "020", + "description": "Date must be within reporting period", + "formula": "field_020 >= period_start AND field_020 <= period_end" + } + ] +} +``` + +### 3. Test Results Documentation + +Document all test results: + +```javascript +{ + "test_results": [ + { + "field": "001", + "test": "CNPJ extraction", + "input": "12345678000190", + "transformation": "slice:':8'", + "output": "12345678", + "expected": "12345678", + "passed": true + }, + { + "field": "020", + "test": "Date timezone conversion", + "input": "2025-01-15T10:30:00Z", + "transformation": "UTC to America/Sao_Paulo", + "output": "2025-01-15 08:30:00", + "expected": "2025-01-15 08:30:00", + "passed": true + } + ] +} +``` + +--- + +## Capture Gate 2 Response + +**Extract and merge with Gate 1 context:** + +```javascript +{ + // Everything from Gate 1 + + "validated_mappings": [ + { + "field_code": "020", + "resolution": "confirmed", + "transformation": "UTC to America/Sao_Paulo", + "test_data": { + "input": "2025-01-15T10:30:00Z", + "expected": "2025-01-15 08:30:00", + "actual": "2025-01-15 08:30:00", + "status": "passed" + } + } + ], + "validation_rules": [/* rules array */], + "all_uncertainties_resolved": true, + "test_summary": { + "total_tests": 45, + "passed": 43, + "failed": 2, + "success_rate": "95.6%" + } +} +``` + +--- + +## Red Flags - STOP Immediately + +If you catch yourself thinking ANY of these, STOP and re-read the NO EXCEPTIONS section: + +### Partial Resolution +- "Resolve critical only, skip MEDIUM/LOW" +- "Fix most uncertainties, good enough" +- "ALL is unrealistic, most is pragmatic" + +### Threshold Degradation +- "88% is close to 90%" +- "95% mandatory validation is outstanding" +- "Close enough to pass" +- "The gap isn't material" + +### Skip Validation Steps +- "Validation dashboard is redundant" +- "Mappings look correct visually" +- "Testing is busywork" +- "We'll catch issues in Gate 3" + +### Workaround Thinking +- "Use workarounds for rejected fields" +- "Patch it in Gate 3" +- "Fix in next sprint" +- "This is an edge case" + +### Justification Language +- "Being pragmatic" +- "Following spirit not letter" +- "Outstanding is good enough" +- "Rarely finds issues anyway" +- "Experience says this is fine" + +### If You See These Red Flags + +1. **Acknowledge the rationalization** ("I'm trying to skip LOW uncertainties") +2. **Read the NO EXCEPTIONS section** (understand why ALL means ALL) +3. **Read the Rationalization Table** (see your exact excuse refuted) +4. **Meet the threshold completely** (100%, >90%, ALL) + +**Validation thresholds are binary gates, not aspirational goals.** + +--- + +## Pass/Fail Criteria + +### PASS Criteria +- ✅ All Gate 1 uncertainties resolved (confirmed or alternatives found) +- ✅ Test data validates successfully (>90% pass rate) +- ✅ No new Critical/High issues +- ✅ All mandatory fields have confirmed mappings +- ✅ Validation rules defined for all critical fields + +### FAIL Criteria +- ❌ Uncertainties remain unresolved +- ❌ Test failures on mandatory fields +- ❌ Cannot find alternative mappings for rejected fields +- ❌ Data type mismatches that can't be transformed +- ❌ **Mandatory fields validation < 100%** + +--- + +## Mandatory Fields Final Validation + +### CRITICAL: Must Execute Before Gate 2 Completion + +```javascript +function validateMandatoryFields(context) { + // Get mandatory fields from template-specific skill + const templateSkill = `regulatory-${context.template_code.toLowerCase()}`; + const mandatoryFields = await loadTemplateSpecificMandatoryFields(templateSkill); + const validationResults = []; + + for (const field of mandatoryFields) { + const result = { + field_code: field.code, + field_name: field.name, + is_mandatory: true, + checks: { + mapped: checkFieldIsMapped(field, context.gate1.field_mappings), + confidence_ok: checkConfidenceLevel(field, context.gate1.field_mappings) >= 80, + validated: checkFieldValidated(field, context.gate2.validated_mappings), + tested: checkFieldTested(field, context.gate2.test_results), + transformation_ok: checkTransformationWorks(field, context.gate2.test_results) + } + }; + + result.status = Object.values(result.checks).every(v => v === true) ? "PASS" : "FAIL"; + validationResults.push(result); + } + + const allPassed = validationResults.every(r => r.status === "PASS"); + const coverage = (validationResults.filter(r => r.status === "PASS").length / mandatoryFields.length) * 100; + + return { + all_mandatory_fields_valid: allPassed, + validation_results: validationResults, + coverage_percentage: coverage, + failed_fields: validationResults.filter(r => r.status === "FAIL") + }; +} +``` + +### Mandatory Fields Dashboard Output + +```markdown +## 📊 MANDATORY FIELDS VALIDATION DASHBOARD + +Template: {template_name} +Total Mandatory Fields: {total_mandatory} +Coverage: {coverage}% +Status: {status_emoji} {status_text} + +| # | Field | Required | Mapped | Confidence | Validated | Tested | Status | +|---|-------|----------|--------|------------|-----------|--------|--------| +| 1 | CNPJ | ✅ YES | ✅ | 95% HIGH | ✅ | ✅ | ✅ PASS | +| 2 | Date | ✅ YES | ✅ | 100% HIGH | ✅ | ✅ | ✅ PASS | + +VALIDATION SUMMARY: +✅ Coverage: {coverage}% ({passed}/{total}) +✅ Validation: {validation}% ({validated}/{total}) +✅ Testing: {testing}% ({tested}/{total}) +✅ Average Confidence: {avg_confidence}% + +RESULT: {final_result} +``` + +### Gate 2 Pass Condition Update + +```javascript +// Gate 2 ONLY passes if mandatory validation passes +const mandatoryValidation = validateMandatoryFields(context); + +if (mandatoryValidation.all_mandatory_fields_valid) { + context.gate2_passed = true; + context.mandatory_validation = mandatoryValidation; +} else { + context.gate2_passed = false; + context.blocker = `Mandatory fields validation failed: ${mandatoryValidation.failed_fields.length} fields incomplete`; + context.mandatory_validation = mandatoryValidation; +} +``` + +--- + +## State Tracking + +### After PASS: + +``` +SKILL: regulatory-templates-gate2 +GATE: 2 - Technical Validation +STATUS: PASSED +TEMPLATE: {context.template_selected} +RESOLVED: {validated_mappings.length} uncertainties resolved +RULES: {validation_rules.length} validation rules defined +TESTS: {test_summary.passed}/{test_summary.total} passed +NEXT: → Gate 3: API Integration Readiness +EVIDENCE: All field mappings validated with test data +BLOCKERS: None +``` + +### After FAIL: + +``` +SKILL: regulatory-templates-gate2 +GATE: 2 - Technical Validation +STATUS: FAILED +TEMPLATE: {context.template_selected} +UNRESOLVED: {unresolved_uncertainties} uncertainties +TEST_FAILURES: {test_failures} critical tests failed +NEXT: → Fix validation failures before Gate 3 +EVIDENCE: Technical validation incomplete +BLOCKERS: Field validation failures must be resolved +``` + +--- + +## Technical Validation Checklist + +### Field Naming Convention Validation +- [ ] Verify all field names use snake_case (not camelCase) +- [ ] Check MCP API Dog for actual field naming in each datasource +- [ ] Examples: `banking_details` not `bankingDetails`, `account_id` not `accountId` +- [ ] Document any exceptions found in legacy systems + +### Data Type Validations +- [ ] String fields: Check max length, encoding (UTF-8) +- [ ] Number fields: Check precision, decimal places +- [ ] Date fields: Check format (YYYY-MM-DD, YYYY/MM) +- [ ] Boolean fields: Check true/false representation +- [ ] Enum fields: Check valid values list + +### Transformation Validations +- [ ] CNPJ/CPF: Slice operations work correctly +- [ ] Dates: Timezone conversions accurate +- [ ] Numbers: Decimal formatting (floatformat) +- [ ] Strings: Trim, uppercase, padding as needed +- [ ] Nulls: Default values applied correctly + +### Cross-Field Validations +- [ ] Dependent fields have consistent values +- [ ] Date ranges are logical +- [ ] Calculated fields match formulas +- [ ] Conditional fields follow business rules + +--- + +## Common Validation Patterns + +### CNPJ Base Extraction +```javascript +// Input: "12345678000190" (14 digits) +// Output: "12345678" (8 digits) +transformation: "slice:':8'" +``` + +### Date Format Conversion +```javascript +// Input: "2025-01-15T10:30:00Z" (ISO 8601) +// Output: "2025/01" (YYYY/MM for CADOC) +transformation: "date_format:'%Y/%m'" +``` + +### Decimal Precision +```javascript +// Input: 1234.5678 +// Output: "1234.57" +transformation: "floatformat:2" +``` + +### Conditional Fields +```javascript +// If tipoRemessa == "I": include all records +// If tipoRemessa == "S": only approved records +filter: "status == 'approved' OR tipoRemessa == 'I'" +``` + +--- + +## Output to Parent Skill + +Return to `regulatory-templates` main skill: + +```javascript +{ + "gate2_passed": true/false, + "gate2_context": { + // Merged Gate 1 + Gate 2 context + }, + "all_uncertainties_resolved": true/false, + "validation_rules_count": number, + "test_success_rate": percentage, + "next_action": "proceed_to_gate3" | "fix_validations_and_retry" +} +``` + +--- + +## Remember + +1. **Test with real data** - Use actual Midaz data samples +2. **Document transformations** - Every change must be traceable +3. **Validate edge cases** - Test nulls, empty strings, extremes +4. **Cross-reference rules** - Ensure consistency across fields +5. **Keep evidence** - Store test results for audit trail \ No newline at end of file diff --git a/skills/regulatory-templates-gate3/SKILL.md b/skills/regulatory-templates-gate3/SKILL.md new file mode 100644 index 0000000..62a9bde --- /dev/null +++ b/skills/regulatory-templates-gate3/SKILL.md @@ -0,0 +1,438 @@ +--- +name: regulatory-templates-gate3 +description: | + Gate 3 sub-skill - generates complete .tpl template file with all validated + mappings from Gates 1-2. + +trigger: | + - Gate 2 PASSED + - Ready to generate production template file + +skip_when: | + - Gate 2 not passed → complete Gate 2 first + - Template already generated → verify or regenerate + +sequence: + after: [regulatory-templates-gate2] +--- + +# Regulatory Templates - Gate 3: Template File Generation + +## Overview + +**This sub-skill executes Gate 3 of the regulatory template workflow: generating the complete .tpl template file with all validated mappings and transformations from Gates 1-2.** + +**Parent skill:** `regulatory-templates` + +**Prerequisites:** +- Gate 1 PASSED (field mappings complete) +- Gate 2 PASSED (validations confirmed) +- Context object with Gates 1-2 results + +**Output:** Generated .tpl template file ready for use + +--- + +## Foundational Principle + +**Template generation is the final quality gate before production deployment.** + +Gate 3 transforms validated specifications into production artifacts: +- **Agent-based generation**: finops-automation applies validated mappings consistently - manual creation introduces human error +- **Two-file separation**: Clean .tpl (production code) + .tpl.docs (documentation) - inline comments bloat production artifacts +- **All mandatory fields**: 100% inclusion required - 95% = 5% of regulatory data missing in BACEN submission +- **Correct transformations**: Django filters applied per Gates 1-2 validation - errors here multiply in every submission +- **Valid syntax**: Template must execute without errors - syntax failures block Reporter deployment + +**Skipping requirements in Gate 3 means:** +- Manual creation bypasses systematic validation (fatigue errors, missed transformations) +- Single-file output mixes production code with documentation (maintenance nightmare) +- Missing fields cause BACEN submission failures (compliance violations) +- Invalid syntax blocks deployment (emergency fixes under pressure) + +**Gate 3 is not automation for convenience - it's the final verification layer.** + +--- + +## When to Use + +**Called by:** `regulatory-templates` skill after Gate 2 passes + +**Purpose:** Create the final Django/Jinja2 template file with all field mappings, transformations, and validation logic + +--- + +## NO EXCEPTIONS - Generation Requirements Are Mandatory + +**Gate 3 template generation requirements have ZERO exceptions.** This is the final artifact that goes to production. + +### Common Pressures You Must Resist + +| Pressure | Your Thought | Reality | +|----------|--------------|---------| +| **Fatigue** | "Manual creation is faster when tired" | Fatigue increases error rate. Agent doesn't get tired. 10 min manual < 15 min validated | +| **Simplicity** | "One file easier than two" | Production artifacts must be clean. Documentation bloats .tpl files | +| **Confidence** | "45/47 fields works for 99% cases" | 100% mandatory required. 95% = BACEN submission failures on edge cases | +| **Experience** | "I can optimize agent output" | Agent applies validated mappings systematically. Manual edits introduce drift | + +### Generation Requirements (Non-Negotiable) + +**Agent-Based Generation:** +- ✅ REQUIRED: Use finops-automation agent for all template generation +- ❌ FORBIDDEN: Manual .tpl creation, editing agent output +- Why: Agent applies Gates 1-2 validations consistently, prevents fatigue errors + +**Two-File Output:** +- ✅ REQUIRED: Generate .tpl (clean code) + .tpl.docs (documentation) +- ❌ FORBIDDEN: Single file with inline comments, merged documentation +- Why: Production artifacts stay clean, documentation separate for maintenance + +**All Mandatory Fields:** +- ✅ REQUIRED: 100% mandatory fields in template (47/47) +- ❌ FORBIDDEN: "45/47 is good enough", placeholder comments for missing +- Why: Each missing field = potential regulatory compliance failure + +**Validated Output:** +- ✅ REQUIRED: Use exact agent output without manual "improvements" +- ❌ FORBIDDEN: Refactoring for optimization, rewriting for clarity +- Why: Agent output validated against Gates 1-2, edits create drift + +### The Bottom Line + +**Manual shortcuts in final artifact = production regulatory failures.** + +Gate 3 is the last checkpoint. All previous gates' work culminates here. Bypassing agent generation defeats the entire 3-gate validation process. + +**If you're tempted to skip agent generation, ask yourself: Am I willing to debug production BACEN submission failures from manual template errors?** + +--- + +## Rationalization Table - Know the Excuses + +| Excuse | Why It's Wrong | Correct Response | +|--------|---------------|------------------| +| "Manual creation same output, faster" | Agent validates systematically, manual risks errors | Use agent completely | +| "10 min vs 15 min, I'm tired" | Fatigue increases manual error rate | Let agent work | +| "Two files is over-engineering" | Production code must be clean, no doc bloat | Generate TWO files | +| "One file easier to maintain" | Mixing code and docs creates maintenance burden | Separate concerns | +| "45/47 works for 99% cases" | 100% mandatory required, edge cases matter | Include ALL fields | +| "I can optimize agent output" | Optimization creates drift from validated spec | Use exact output | +| "Agent code is verbose" | Verbose but validated > concise but wrong | Trust validation | +| "Skip for now, add fields later" | Template is final artifact, can't patch BACEN | Complete now | + +### If You Find Yourself Making These Excuses + +**STOP. You are rationalizing.** + +Gate 3 is where 5+ hours of Gates 1-2 work becomes a production artifact. Shortcuts here waste all previous validation effort. + +--- + +## Gate 3 Process + +### Agent Dispatch + +**Use the Task tool to dispatch the finops-automation agent for template generation:** + +1. **Invoke the Task tool with these parameters:** + - `subagent_type`: "finops-automation" + - `model`: "sonnet" + - `description`: "Gate 3: Generate template file" + - `prompt`: Use the prompt template below with accumulated context from Gates 1-2 + +2. **Prompt Template for Gate 3:** + +``` +GATE 3: TEMPLATE FILE GENERATION + +CONTEXT FROM GATES 1-2: +- Template: [insert context.template_name] +- Template Code: [insert context.template_code] +- Authority: [insert context.authority] +- Fields Mapped: [insert context.field_mappings.length] +- Validation Rules: [insert context.validation_rules.length] + +FIELD MAPPINGS FROM GATE 1: +[For each field in context.field_mappings, list:] +Field [field_code]: [field_name] +- Source: [selected_mapping] +- Transformation: [transformation or 'none'] +- Confidence: [confidence_score]% +- Required: [required] + +VALIDATION RULES FROM GATE 2: +[For each rule in context.validation_rules, list:] +Rule [rule_id]: [description] +- Formula: [formula] + +TASKS: +1. Generate CLEAN .tpl file with ONLY Django/Jinja2 template code +2. Include all field mappings with transformations +3. Apply correct template syntax for Reporter +4. Structure according to regulatory format requirements +5. Include conditional logic where needed +6. Use MINIMAL inline comments (max 1-2 lines critical notes only) + +CRITICAL - NAMING CONVENTION: +⚠️ ALL field names are in SNAKE_CASE standard +- Gate 1 has already converted all fields to snake_case +- Examples: + * Use {{ legal_document }} (converted from legalDocument) + * Use {{ operation_route }} (already snake_case) + * Use {{ opening_date }} (converted from openingDate) + * Use {{ natural_person }} (converted from naturalPerson) +- ALL fields follow snake_case convention consistently +- No conversion needed - fields arrive already standardized + +CRITICAL - DATA SOURCES: +⚠️ ALWAYS prefix fields with the correct data source! +Reference: /docs/regulatory/DATA_SOURCES.md + +Available Data Sources: +- midaz_onboarding: organization, account (cadastral data) +- midaz_transaction: operation_route, balance, operation (transactional data) + +Field Path Format: {data_source}.{entity}.{index?}.{field} + +Examples: +- CNPJ: {{ midaz_onboarding.organization.0.legal_document|slice:':8' }} +- COSIF: {{ midaz_transaction.operation_route.code }} +- Saldo: {{ midaz_transaction.balance.available }} +- Data: {% date_time "YYYY/MM" %} + +WRONG: {{ organization.legal_document }} +CORRECT: {{ midaz_onboarding.organization.0.legal_document }} + +TEMPLATE STRUCTURE: +- Use proper hierarchy per regulatory spec +- Include loops for repeating elements (accounts, transactions) +- Apply transformations using Django filters +- NO DOCUMENTATION BLOCKS - only functional template code + +OUTPUT FILES (Generate TWO separate files): + +FILE 1 - TEMPLATE (CLEAN): +- Filename: [template_code]_preview.tpl +- Content: ONLY the Django/Jinja2 template code +- NO extensive comments or documentation blocks +- Maximum 1-2 critical inline comments if absolutely necessary +- Ready for DIRECT use in Reporter without editing + +FILE 2 - DOCUMENTATION: +- Filename: [template_code]_preview.tpl.docs +- Content: Full documentation including: + * Field mappings table + * Transformation rules + * Validation checklist + * Troubleshooting guide + * Maintenance notes + * All the helpful documentation + +CRITICAL: The .tpl file must be production-ready and contain ONLY +the functional template code. All documentation goes in .docs file. + +COMPLETION STATUS must be COMPLETE or INCOMPLETE. +``` + +3. **Example Task tool invocation:** +``` +When executing Gate 3, call the Task tool with: +- subagent_type: "finops-automation" +- model: "sonnet" +- description: "Gate 3: Generate template file" +- prompt: [The full prompt above with context from Gates 1-2 substituted] +``` +``` + +--- + +## Agent Execution + +The agent `finops-automation` will handle all technical aspects: + +- Analyze template requirements based on authority type +- Generate appropriate template structure (XML, JSON, etc.) +- Apply all necessary transformations using Django/Jinja2 filters +- Include conditional logic for business rules +- Ensure compliance with regulatory format specifications + +--- + +## Expected Output + +The agent will generate two files: + +1. **Template File**: `{template_code}_{timestamp}_preview.tpl` + - Contains the functional Django/Jinja2 template code + - Ready for direct use in Reporter + - Minimal inline comments only if necessary + +2. **Documentation File**: `{template_code}_{timestamp}_preview.tpl.docs` + - Contains full documentation + - Field mapping details + - Maintenance notes + +--- + +## Red Flags - STOP Immediately + +If you catch yourself thinking ANY of these, STOP and re-read the NO EXCEPTIONS section: + +### Manual Shortcuts +- "Create .tpl manually, faster" +- "Edit agent output for optimization" +- "I can write cleaner code" +- "Agent is too verbose" + +### File Structure Violations +- "One file easier to maintain" +- "Inline comments instead of .docs" +- "Merge documentation into .tpl" +- "Two files is over-engineering" + +### Partial Completion +- "45/47 fields works for most cases" +- "Skip edge case fields" +- "Add missing fields later" +- "99% is good enough" + +### Justification Language +- "Being pragmatic" +- "I'm too tired for agent wait" +- "Manual is faster" +- "Over-engineering" +- "Optimization is better" + +### If You See These Red Flags + +1. **Acknowledge rationalization** ("I'm trying to skip agent generation") +2. **Read NO EXCEPTIONS** (understand why agent is required) +3. **Read Rationalization Table** (see excuse refuted) +4. **Use agent completely** (no manual shortcuts) + +**Template generation shortcuts waste all Gates 1-2 validation work.** + +--- + +## Pass/Fail Criteria + +### PASS Criteria +- ✅ Template file generated successfully +- ✅ All mandatory fields included +- ✅ Transformations correctly applied +- ✅ Django/Jinja2 syntax valid +- ✅ Output format matches specification +- ✅ File saved with correct extension + +### FAIL Criteria +- ❌ Missing mandatory fields +- ❌ Invalid template syntax +- ❌ Transformation errors +- ❌ File generation failed + +--- + +## State Tracking + +### After PASS: + +``` +SKILL: regulatory-templates-gate3 +GATE: 3 - Template File Generation +STATUS: PASSED ✅ +TEMPLATE: {context.template_selected} +FILE: {filename} +FIELDS: {fields_included}/{total_fields} +NEXT: Template ready for use +EVIDENCE: File generated successfully +BLOCKERS: None +``` + +### After FAIL: + +``` +SKILL: regulatory-templates-gate3 +GATE: 3 - Template File Generation +STATUS: FAILED ❌ +TEMPLATE: {context.template_selected} +ERROR: {error_message} +NEXT: Fix generation issues +EVIDENCE: {specific_failure} +BLOCKERS: {blocker_description} +``` + +--- + +## Output to Parent Skill + +Return to `regulatory-templates` main skill: + +```javascript +{ + "gate3_passed": true/false, + "template_file": { + "filename": "cadoc4010_20251119_preview.tpl", + "path": "/path/to/file", + "size_bytes": 2048, + "fields_included": 9 + }, + "ready_for_use": true/false, + "next_action": "template_complete" | "fix_and_regenerate" +} +``` + +--- + +## Common Template Patterns + +### SNAKE_CASE Field Names (STANDARD) +```django +CORRECT - All fields in snake_case (as provided by Gate 1): +{{ organization.legal_document }} # Converted from legalDocument +{{ holder.natural_person }} # Already snake_case +{{ account.opening_date }} # Converted from openingDate +{{ banking_details.account_number }} # Converted from accountNumber + +WRONG - Using other naming conventions: +{{ organization.legalDocument }} # ❌ Should be legal_document +{{ holder.naturalPerson }} # ❌ Should be natural_person +{{ account.openingDate }} # ❌ Should be opening_date +{{ bankingDetails.accountNumber }} # ❌ Should be banking_details.account_number +``` + +### Iterating Collections +```django +{% for item in collection %} + {{ item.field }} +{% endfor %} +``` + +### Conditional Fields +```django +{% if condition %} + {{ value }} +{% endif %} +``` + +### Nested Objects +```django +{{ parent.child.grandchild }} +``` + +### Filters Chain +```django +{{ value|slice:':8'|upper }} +``` + +--- + +## Remember + +1. **Use exact field paths** from Gate 1 mappings +2. **ALL FIELDS IN SNAKE_CASE** - Gate 1 provides all fields already converted to snake_case +3. **Apply all transformations** validated in Gate 2 +4. **Include comments** for maintainability +5. **Follow regulatory format** exactly +6. **Test syntax validity** before saving +7. **Document assumptions** made during generation +8. **Fields are standardized** - All fields follow snake_case convention consistently \ No newline at end of file diff --git a/skills/regulatory-templates-setup/SKILL.md b/skills/regulatory-templates-setup/SKILL.md new file mode 100644 index 0000000..c76f02a --- /dev/null +++ b/skills/regulatory-templates-setup/SKILL.md @@ -0,0 +1,730 @@ +--- +name: 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 + +Use `AskUserQuestion` tool to present regulatory authority selection: + +```javascript +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: + +```javascript +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: + +```javascript +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: + +```javascript +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: + +```javascript +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:** + +```javascript +// 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:** + +```javascript +// 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: + +```javascript +// 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 + +```javascript +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 + +```javascript +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 + +```javascript +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 + +```javascript +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 + +```javascript +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. \ No newline at end of file diff --git a/skills/regulatory-templates/SKILL.md b/skills/regulatory-templates/SKILL.md new file mode 100644 index 0000000..327eda4 --- /dev/null +++ b/skills/regulatory-templates/SKILL.md @@ -0,0 +1,655 @@ +--- +name: regulatory-templates +description: | + 3-gate regulatory template orchestrator - manages setup, Gate 1 (analysis), + Gate 2 (validation), Gate 3 (generation) for BACEN/RFB compliance. + +trigger: | + - Creating BACEN CADOCs (4010, 4016, 4111) + - Mapping e-Financeira, DIMP, APIX templates + - Full automation from analysis to template creation + +skip_when: | + - Non-Brazilian regulations → not applicable + - Analysis-only without template → use finops-analyzer directly + - Template already exists, just needs updates → modify directly + +sequence: + before: [regulatory-templates-setup] +--- + +# Regulatory Templates - Orchestrator + +## Overview + +**This skill orchestrates the regulatory template creation workflow through modular sub-skills, managing a 3-gate sequential validation process with dynamic context passing between gates.** + +**Architecture:** Modular design with dedicated sub-skills for each phase: +- `regulatory-templates-setup` - Initial configuration and selection +- `regulatory-templates-gate1` - Regulatory compliance analysis and field mapping +- `regulatory-templates-gate2` - Technical validation of mappings +- `regulatory-templates-gate3` - Template file generation (.tpl) + +**Template Specifications:** All template specifications are dynamically loaded within gates from centralized configurations. Templates are organized by regulatory authority with cascading selection: + +**BACEN (Banco Central):** +- **CADOC:** 4010 (Cadastro), 4016 (Crédito), 4111 (Câmbio) +- **APIX:** 001 (Dados Cadastrais), 002 (Contas e Transações) + +**RFB (Receita Federal):** +- **e-Financeira:** evtCadDeclarante, evtAberturaeFinanceira, evtFechamentoeFinanceira, evtMovOpFin, evtMovPP, evtMovOpFinAnual +- **DIMP:** v10 (Movimentação Patrimonial) + +**REQUIRED AGENTS:** The sub-skills dispatch specialized agents: +- `finops-analyzer` - For Gates 1-2 and Discussion (regulatory analysis and validation) +- `finops-automation` - For Gate 3 (template file generation) + +--- + +## Foundational Principle + +**Brazilian regulatory compliance (BACEN, RFB) has zero margin for error.** + +This isn't hyperbole: +- BACEN penalties for incorrect submissions: R$10,000 - R$500,000 + license sanctions +- RFB penalties for e-Financeira errors: Criminal liability for false declarations +- Template errors are discovered during audits, often months after submission +- "We'll fix it later" is impossible - submissions are final + +**This workflow exists because:** +1. Human confidence without validation = optimism bias (proven by TDD research) +2. "Mostly correct" regulatory submissions = rejected submissions + penalties +3. Shortcuts under pressure = exactly when errors are most likely +4. Each gate prevents specific failure modes discovered in production + +**The 3-gate architecture is not bureaucracy - it's risk management.** + +Every section that seems "rigid" or "redundant" exists because someone, somewhere, cut that corner and caused a regulatory incident. + +**Follow this workflow exactly. Your professional reputation depends on it.** + +--- + +## When to Use + +**Use this skill when:** +- User requests mapping and creation of Brazilian regulatory templates +- BACEN CADOCs (4010, 4016, 4111), e-Financeira, DIMP, APIX +- Full automation from analysis to template creation + +**Symptoms triggering this skill:** +- "Create CADOC 4010 template" +- "Map e-Financeira to Midaz and set up in Reporter" +- "Automate DIMP template creation" + +**When NOT to use:** +- Non-Brazilian regulations +- Analysis-only without template creation +- Templates already exist and just need updates + +--- + +## NO EXCEPTIONS - Read This First + +**This workflow has ZERO exceptions.** Brazilian regulatory compliance (BACEN, RFB) has zero margin for error. + +### Common Pressures You Must Resist + +| Pressure | Your Thought | Reality | +|----------|--------------|---------| +| **Deadline** | "Skip Gate 2, we're confident" | Gate 1 analysis ≠ Gate 2 validation. Confidence without verification = optimism bias | +| **Authority** | "Manager says skip it" | Manager authority doesn't override regulatory requirements. Workflow protects both of you | +| **Fatigue** | "Manual creation is faster" | Fatigue makes errors MORE likely. Automation doesn't get tired | +| **Economic** | "Optional fields have no fines" | Template is reusable. Skipping fields = technical debt + future rework | +| **Sunk Cost** | "Reuse existing template" | 70% overlap = 30% different. Regulatory work doesn't tolerate "mostly correct" | +| **Pragmatism** | "Setup is ceremony" | Setup initializes context. Skipping = silent assumptions | +| **Efficiency** | "Fix critical only" | Gate 2 PASS criteria: ALL uncertainties resolved, not just critical | + +### Emergency Scenarios + +**"Production is down, need template NOW"** +→ Production issues don't override regulatory compliance. Fix production differently. + +**"CEO directive to ship immediately"** +→ CEO authority doesn't override BACEN requirements. Escalate risk in writing. + +**"Client contract requires delivery today"** +→ Contract penalties < regulatory penalties. Renegotiate delivery, don't skip validation. + +**"Tool/agent is unavailable"** +→ Wait for tools or escalate. Manual workarounds bypass validation layers. + +### The Bottom Line + +**Shortcuts in regulatory templates = career-ending mistakes.** + +BACEN and RFB submissions are final. You cannot "patch next sprint." Every gate exists because regulatory compliance has zero tolerance for "mostly correct." + +**If you're tempted to skip ANY part of this workflow, stop and ask yourself: Am I willing to stake my professional reputation on this shortcut?** + +--- + +## Rationalization Table - Know the Excuses + +Every rationalization below has been used to justify skipping workflow steps. **ALL are invalid.** + +| Excuse | Why It's Wrong | Correct Response | +|--------|---------------|------------------| +| "Gate 2 is redundant when Gate 1 is complete" | Gate 1 = analysis, Gate 2 = validation. Different purposes. Validation catches analysis errors | Run Gate 2 completely | +| "Manual creation is pragmatic" | Manual bypasses validation layer. Gate 3 agent validates against Gate 2 report | Use automation agent | +| "Optional fields don't affect compliance" | Overall confidence includes all fields. Skipping 36% fails PASS criteria | Map all fields | +| "70% overlap means we can copy" | 30% difference contains critical regulatory fields. Similarity ≠ simplicity | Run full workflow | +| "Setup is bureaucratic ceremony" | Setup initializes context for Gates 1-3. Skipping creates silent assumptions | Run setup completely | +| "Fix critical issues only" | Gate 2 PASS: ALL uncertainties resolved. Medium/low issues cascade to mandatory failures | Resolve all uncertainties | +| "We're experienced, simplified workflow" | Experience doesn't exempt you from validation. Regulatory work requires process | Follow full workflow | +| "Following spirit not letter" | Regulatory compliance requires BOTH. Skipping steps violates spirit AND letter | Process IS the spirit | +| "Being pragmatic vs dogmatic" | Process exists because pragmatism failed. Brazilian regulatory penalties are severe | Rigor is pragmatism | +| "Tool is too rigid for real-world" | Rigidity prevents errors. Real-world includes regulatory audits and penalties | Rigidity is protection | + +### If You Find Yourself Making These Excuses + +**STOP. You are rationalizing.** + +The workflow exists specifically to prevent these exact thoughts from leading to errors. If the workflow seems "too rigid," that's evidence it's working - preventing you from shortcuts that seem reasonable but create risk. + +--- + +## Workflow Overview + +``` +┌─────────────────────┐ +│ ORCHESTRATOR │ +│ (this skill) │ +└──────┬──────────────┘ + │ + ▼ +┌─────────────────────┐ ┌──────────────────────────┐ +│ SETUP SUB-SKILL │────▶│ • Template Selection │ +│ │ │ • Context Initialization │ +└──────┬──────────────┘ └──────────────────────────┘ + │ + ▼ context +┌─────────────────────┐ ┌──────────────────────────┐ +│ GATE 1 SUB-SKILL │────▶│ • Regulatory Analysis │ +│ │ │ • Field Mapping │ +│ │ │ • Identify Data Sources │ +└──────┬──────────────┘ └──────────────────────────┘ + │ + ▼ context + gate1 +┌─────────────────────┐ ┌──────────────────────────┐ +│ GATE 2 SUB-SKILL │────▶│ • Validate Mappings │ +│ │ │ • Test Transformations │ +│ │ │ • Define Validation Rules │ +└──────┬──────────────┘ │ • Resolve Uncertainties │ + │ └──────────────────────────┘ + ▼ context + gate1 + gate2 +┌─────────────────────┐ ┌──────────────────────────┐ +│ GATE 3 SUB-SKILL │────▶│ • Generate Template File │ +│ │ │ • Apply Transformations │ +│ │ │ • Create .tpl File │ +└──────┬──────────────┘ │ • Django/Jinja2 Format │ + │ └──────────────────────────┘ + ▼ +┌─────────────────────┐ +│ TEMPLATE CREATED ✅ │ +│ Ready for BACEN │ +└─────────────────────┘ +``` + +--- + +## Orchestration Process + +### Step 1: Initialize TodoWrite Tasks + +```javascript +TodoWrite({ + todos: [ + { + content: "Select regulatory template", + status: "in_progress", + activeForm: "Running setup configuration" + }, + { + content: "Gate 1: Regulatory compliance analysis and field mapping", + status: "pending", + activeForm: "Running Gate 1: Regulatory analysis" + }, + { + content: "Gate 2: Technical validation of field mappings", + status: "pending", + activeForm: "Running Gate 2: Technical validation" + }, + { + content: "Gate 3: Template file generation", + status: "pending", + activeForm: "Running Gate 3: Template generation" + }, + { + content: "Verify template creation and functionality", + status: "pending", + activeForm: "Verifying template" + } + ] +}) +``` + +### Step 2: Execute Setup Sub-skill + +**Use the Skill tool to execute the setup sub-skill:** + +1. Call the Skill tool with: + - `skill`: "regulatory-templates-setup" + +2. Capture the returned context from the setup skill + +3. Update TodoWrite to mark setup as completed and Gate 1 as in_progress + +4. **Note:** Context is maintained in memory only - no files are created + +### Step 3: Execute Gate 1 Sub-skill + +**Use the Skill tool to execute Gate 1:** + +1. Call the Skill tool with: + - `skill`: "regulatory-templates-gate1" + +2. The Gate 1 skill will dispatch the finops-analyzer agent to: + - **READ the regulatory specification** from `/docs/regulatory/templates/` + - **ANALYZE the specification requirements** + - **GENERATE a SPECIFICATION REPORT** + +3. Capture the report output containing: + - Template structure and format + - Mandatory and optional fields + - Transformation rules + - Validation requirements + - Business rules + - Compliance checklist + +4. Check if gate1_passed is true: + - If PASSED: Store the specification report in context, update TodoWrite, proceed to Gate 2 + - If FAILED: Handle Gate 1 failure, address critical gaps before retry + +### Step 4: Execute Gate 2 Sub-skill + +**Use the Skill tool to execute Gate 2:** + +1. Call the Skill tool with: + - `skill`: "regulatory-templates-gate2" + - Context includes the **specification report** from Gate 1 + +2. The Gate 2 skill will dispatch the finops-analyzer agent to: + - **VALIDATE the specification report completeness** + - **RESOLVE any uncertainties or gaps** + - **CONFIRM all transformation rules** + - **FINALIZE the specification report** + +3. Check if gate2_passed is true: + - **CRITICAL:** Verify mandatory fields validation = 100% + - If validation < 100%: FAIL with mandatory fields incomplete error + - If PASSED: Store the **FINALIZED REPORT** in context, update TodoWrite, proceed to Gate 3 + - If FAILED: Handle unresolved uncertainties + +### Step 5: Execute Gate 3 Sub-skill + +**Use the Skill tool to execute Gate 3:** + +1. Call the Skill tool with: + - `skill`: "regulatory-templates-gate3" + - Context includes the **FINALIZED SPECIFICATION REPORT** from Gate 2 + +2. The Gate 3 skill will dispatch the finops-automation agent (using sonnet model) to: + - **USE THE SPECIFICATION REPORT as input** + - **GENERATE the .tpl template based on report** + - **VALIDATE template against report requirements** + - **CREATE production-ready template file** + +3. Check if gate3_passed is true: + - If PASSED: Template created successfully, update TodoWrite, verify output + - If FAILED: Handle Gate 3 failure with retry logic (401 = token refresh, 500/503 = wait and retry) + +--- + +## Sub-skill Execution Pattern + +**Each sub-skill is executed using the Skill tool:** + +1. **To execute a sub-skill:** + - Use the Skill tool with parameter `skill: "skill-name"` + - The sub-skill will handle agent dispatch internally + +2. **Example invocations:** + ``` + Skill tool with skill: "regulatory-templates-setup" + Skill tool with skill: "regulatory-templates-gate1" + Skill tool with skill: "regulatory-templates-gate2" + Skill tool with skill: "regulatory-templates-gate3" + ``` + +3. **Context flows automatically** through the orchestrator's memory + +--- + +## Context Management - Report-Driven Flow + +### Context Structure Evolution + +**After Setup:** +```javascript +{ + template_selected: "CADOC 4010", + template_code: "4010", + authority: "BACEN", + deadline: "2025-12-31" +} +``` + +**After Gate 1 - SPECIFICATION REPORT GENERATED:** +```javascript +{ + // ... setup context + + specification_report: { + template_info: { + name: "CADOC 4010", + format: "XML", + version: "1.0" + }, + fields: { + mandatory: [/* field definitions */], + optional: [/* field definitions */] + }, + transformations: [/* transformation rules */], + validations: [/* validation rules */], + structure: {/* document structure */} + } +} +``` + +**After Gate 2 - FINALIZED REPORT:** +```javascript +{ + // ... setup + gate1 context + + finalized_report: { + // Enhanced specification report with: + validated: true, + uncertainties_resolved: true, + all_fields_mapped: true, + transformations_confirmed: true, + ready_for_implementation: true + } +} +``` + +**After Gate 3 - TEMPLATE GENERATED:** +```javascript +{ + // ... setup + gate1 + gate2 context + + gate3: { + template_file: { + filename: "cadoc4010_20251119_preview.tpl", + path: "/path/to/file", + generated_from_report: true, + validation_passed: true + }, + ready_for_use: true, + report_compliance: "100%" + } +} +``` + +--- + +## Template Specifications Management + +### How Gates Load Template Specifications + +**Each gate dynamically loads template specifications from centralized configurations:** + +```javascript +// Pattern used by all gates +const templateCode = context.template_selected.split(' ')[1]; // e.g., "4010" +const templateName = context.template_selected.toLowerCase().replace(' ', ''); // e.g., "cadoc4010" + +// Load specifications from centralized config +const templateSpecs = loadTemplateSpecifications(templateName); +// Gate 1: Use field mappings from specifications +// Gate 2: Apply validation rules from specifications +// Gate 3: Use template structure from specifications +``` + +### Benefits of Centralized Specifications + +1. **Simplicity:** Single source of truth for all templates +2. **Maintainability:** Update specs without changing gate logic +3. **Scalability:** Add new templates by adding specifications only +4. **Consistency:** All templates follow same processing logic +5. **Evolution:** Template updates require only spec changes + +### Adding New Template Support + +When adding support for a new regulatory template: + +1. **Add template specifications** to centralized configuration +2. **No new skills required** - Gates handle all templates +3. **Content:** Field mappings, validation rules, format specifications +4. **Testing:** Run through 3-gate process with new specs + +--- + +## State Tracking + +**Output state tracking comment after EACH sub-skill execution:** + +``` +SKILL: regulatory-templates (orchestrator) +PHASE: {current_phase} +TEMPLATE: {context.template_selected} +GATES_COMPLETED: {completed_gates}/3 +CURRENT: {current_action} +NEXT: {next_action} +EVIDENCE: {last_result} +BLOCKERS: {blockers or "None"} +``` + +--- + +## Error Handling + +### Gate Failure Handling + +```javascript +function handleGateFailure(gateNumber, issues) { + // Log failure + console.log(`Gate ${gateNumber} FAILED`); + + // Determine if retriable + if (isRetriable(issues)) { + // Fix issues + fixIssues(issues); + + // Retry gate + retryGate(gateNumber); + } else { + // Escalate to user + askUserForHelp(gateNumber, issues); + } +} +``` + +### Gate 3 Special Retry Logic + +```javascript +function handleGate3Failure(result) { + if (result.error_code === 401) { + // Token expired - refresh and retry + refreshToken(); + retryGate3(); + } else if ([500, 503].includes(result.error_code)) { + // Server error - wait and retry + wait(120000); // 2 minutes + retryGate3(); + } else { + // Non-retriable error + escalateToUser(result.error); + } +} +``` + +--- + +## Success Output + +```markdown +✅ TEMPLATE CREATED SUCCESSFULLY + +Template: {context.template_name} +Template ID: {gate3_result.template_id} +Fields Configured: {gate3_result.fields_configured}/{context.total_fields} +Validation Rules: {gate3_result.validation_rules_applied} +Test Status: PASSED ✅ + +Gates Summary: +- Setup: ✅ Template selected +- Gate 1: ✅ Regulatory analysis complete +- Gate 2: ✅ Technical validation complete +- Gate 3: ✅ Template created and verified + +Ready for production use! +``` + +--- + +## Coordination Rules + +1. **Sequential Execution:** Gates must execute in order (1→2→3) +2. **Context Accumulation:** Each gate adds to context, never overwrites +3. **Failure Stops Progress:** Cannot proceed to next gate if current fails +4. **State Tracking Required:** Output state after each sub-skill +5. **TodoWrite Updates:** Mark complete immediately after each phase +6. **NO INTERMEDIATE FILES:** Context flows in memory only - no .md files between gates +7. **SINGLE OUTPUT FILE:** Only create final .tpl template file in Gate 3 + +--- + +## Red Flags - STOP Immediately + +If you catch yourself thinking ANY of these, STOP and re-read the NO EXCEPTIONS section: + +### Skip Patterns +- "Skip Gate X" (any variation) +- "Run Gates out of order" +- "Parallel gates for speed" +- "Simplified workflow for experienced teams" +- "Emergency override protocol" + +### Manual Workarounds +- "Create template manually" +- "Copy existing template" +- "Manual validation is sufficient" +- "I'll verify it myself" + +### Partial Compliance +- "Fix critical only" +- "Map mandatory fields only" +- "Skip setup, we already know" +- "Lower pass threshold" + +### Justification Language +- "Being pragmatic" +- "Following spirit not letter" +- "Real-world flexibility" +- "Process over outcome" +- "Dogmatic adherence" +- "We're confident" +- "Manager approved" + +### If You See These Red Flags + +1. **Acknowledge the rationalization** ("I'm trying to skip Gate 2") +2. **Read the NO EXCEPTIONS section** (understand why it's required) +3. **Follow the workflow completely** (no modifications) +4. **Document the pressure** (for future skill improvement) + +**The workflow is non-negotiable. Regulatory compliance doesn't have "reasonable exceptions."** + +--- + +## Benefits of Modular Architecture + +1. **Maintainability:** Each sub-skill can be updated independently +2. **Reusability:** Sub-skills can be used in other workflows +3. **Testing:** Each gate can be tested in isolation +4. **Debugging:** Easier to identify which gate failed +5. **Scalability:** New gates can be added as sub-skills + +--- + +## Common Patterns + +### Calling Sub-skills + +**Use the Skill tool to invoke sub-skills:** +``` +1. Call Skill tool with skill: "regulatory-templates-gate1" +2. Sub-skill will handle agent dispatch internally +3. Context is maintained in orchestrator memory +``` + +### Checking Gate Results + +**After each gate execution:** +- If gate_passed = true: Merge results into context, proceed to next gate +- If gate_passed = false: Handle failure, address issues before retry + +### Updating Progress + +**Use TodoWrite tool after each gate:** +- Mark current gate as "completed" +- Mark next gate as "in_progress" +- Keep user informed of progress + +--- + +## Remember + +1. **This is an orchestrator** - Delegates work to sub-skills +2. **Context flows forward** - Each gate builds on previous +3. **Sub-skills are independent** - Can be tested/updated separately +4. **State tracking is mandatory** - After each sub-skill execution +5. **All behavior preserved** - Same functionality, modular structure + +--- + +## Quick Reference + +| Sub-skill | Purpose | Input | Output | +|-----------|---------|-------|--------| +| regulatory-templates-setup | Initial configuration | User selections | Base context | +| regulatory-templates-gate1 | Regulatory analysis | Base context | Field mappings, uncertainties | +| regulatory-templates-gate2 | Technical validation | Context + Gate 1 | Validated mappings, rules | +| regulatory-templates-gate3 | API readiness | Context + Gates 1-2 | Authentication, endpoints | +| regulatory-templates-gate4 | Template creation | Complete context | Template ID, verification | + +--- + +## Master Assertion Checklist + +Before executing workflow: +- [ ] All sub-skills exist in skills directory +- [ ] Agents finops-analyzer and finops-automation available +- [ ] User has selected template type +- [ ] Environment URLs configured + +After each gate: +- [ ] Gate result captured +- [ ] Context updated with gate output +- [ ] TodoWrite updated +- [ ] State tracking comment output +- [ ] Next action determined + +After workflow completion: +- [ ] Template created successfully +- [ ] Template ID captured +- [ ] Verification passed +- [ ] User notified with details \ No newline at end of file diff --git a/skills/using-finops-team/SKILL.md b/skills/using-finops-team/SKILL.md new file mode 100644 index 0000000..92e3326 --- /dev/null +++ b/skills/using-finops-team/SKILL.md @@ -0,0 +1,246 @@ +--- +name: using-finops-team +description: | + 2 FinOps agents for Brazilian financial regulatory compliance (BACEN, RFB, + Open Banking). Dispatch for compliance analysis or template generation. + +trigger: | + - Brazilian regulatory reporting (BACEN, RFB) + - Financial compliance requirements + - Open Banking specifications + - Template generation for Reporter platform + +skip_when: | + - Non-Brazilian regulations → use appropriate resources + - General financial analysis → use other tools +--- + +# Using Ring FinOps & Regulatory Agents + +The ring-finops-team plugin provides 2 specialized FinOps agents for Brazilian financial compliance. Use them via `Task tool with subagent_type:`. + +**Remember:** Follow the **ORCHESTRATOR principle** from `using-ring`. Dispatch agents to handle regulatory complexity; don't implement compliance manually. + +--- + +## 2 FinOps Specialists + +### 1. FinOps Analyzer (Compliance Analysis) +**`ring-finops-team:finops-analyzer`** + +**Specializations:** +- Brazilian regulatory compliance analysis +- BACEN (Central Bank) requirements: + - COSIF (accounting chart of accounts) + - CADOCs (financial instruments catalog) +- RFB (Federal Revenue) requirements: + - e-Financeira (financial reporting) + - SPED (electronic data exchange) +- Open Banking specifications +- Field mapping & validation + +**Use When:** +- Analyzing regulatory requirements (Gate 1-2) +- Validating field mappings for compliance +- Understanding BACEN/RFB specifications +- Planning compliance architecture +- Determining required data structures + +**Output:** Compliance analysis, field mappings, validation rules + +**Example dispatch:** +``` +Task tool: + subagent_type: "ring-finops-team:finops-analyzer" + model: "opus" + prompt: "Analyze BACEN COSIF requirements for corporate account reporting" +``` + +--- + +### 2. FinOps Automation (Template Generation) +**`ring-finops-team:finops-automation`** + +**Specializations:** +- Template generation from specifications +- .tpl file creation for Reporter platform +- XML template generation +- HTML template generation +- TXT template generation +- Reporter platform integration + +**Use When:** +- Generating regulatory report templates (Gate 3) +- Creating BACEN/RFB compliant templates +- Building Reporter platform files +- Converting specifications to executable templates +- Finalizing compliance implementation + +**Output:** Complete .tpl template files, ready for Reporter platform + +**Example dispatch:** +``` +Task tool: + subagent_type: "ring-finops-team:finops-automation" + model: "opus" + prompt: "Generate BACEN COSIF template from analyzed requirements" +``` + +--- + +## Regulatory Workflow: 3-Gate Process + +Brazilian regulatory compliance follows a 3-gate workflow: + +### Gate 1: Compliance Analysis +**Agent:** finops-analyzer +**Purpose:** Understand requirements, identify fields, validate mappings +**Output:** compliance analysis document + +**Dispatch when:** +- Starting regulatory feature +- Need to understand BACEN/RFB specs +- Planning field mappings + +--- + +### Gate 2: Validation & Confirmation +**Agent:** finops-analyzer (again) +**Purpose:** Confirm mappings are correct, validate against specs +**Output:** validated specification document + +**Dispatch when:** +- Ready to confirm compliance understanding +- Need secondary validation +- Before moving to template generation + +--- + +### Gate 3: Template Generation +**Agent:** finops-automation +**Purpose:** Generate executable .tpl templates from validated specifications +**Output:** complete .tpl files for Reporter platform + +**Dispatch when:** +- Specifications are finalized & validated +- Ready to create Reporter templates +- Need production-ready compliance files + +--- + +## Supported Regulatory Standards + +### BACEN (Central Bank of Brazil) +- **COSIF** – Chart of accounts and accounting rules +- **CADOCs** – Financial instruments and derivatives catalog +- **Manual de Normas** – Regulatory requirements + +### RFB (Brazilian Federal Revenue) +- **e-Financeira** – Electronic financial reporting +- **SPED** – Electronic data exchange system +- **ECF** – Financial institutions data + +### Open Banking +- **API specifications** – Data sharing standards +- **Security requirements** – Auth and encryption +- **Integration patterns** – System interoperability + +--- + +## Decision: Which Agent? + +| Phase | Agent | Use Case | +|-------|-------|----------| +| Understanding requirements | finops-analyzer | Analyze specs, identify fields | +| Validating mappings | finops-analyzer | Confirm correctness, validate | +| Generating templates | finops-automation | Create .tpl files, finalize | + +--- + +## When to Use FinOps Agents + +### Use finops-analyzer for: +- ✅ **Understanding regulations** – What does BACEN require? +- ✅ **Compliance research** – How do we map our data? +- ✅ **Requirement analysis** – Which fields are required? +- ✅ **Validation** – Does our mapping match the spec? + +### Use finops-automation for: +- ✅ **Template creation** – Build .tpl files +- ✅ **Specification execution** – Convert analysis to templates +- ✅ **Reporter platform prep** – Generate deployment files +- ✅ **Production readiness** – Finalize compliance implementation + +--- + +## Dispatching Multiple FinOps Agents + +If you need both analysis and template generation, **dispatch sequentially** (analyze first, then automate): + +``` +Workflow: +Step 1: Dispatch finops-analyzer + └─ Returns: compliance analysis +Step 2: Dispatch finops-automation + └─ Returns: .tpl templates + +Note: These must run sequentially because automation depends on analysis. +``` + +--- + +## ORCHESTRATOR Principle + +Remember: +- **You're the orchestrator** – Dispatch agents, don't implement compliance manually +- **Don't write BACEN specs yourself** – Dispatch analyzer to understand +- **Don't generate templates by hand** – Dispatch automation agent +- **Combine with using-ring principle** – Skills + Agents = complete workflow + +### Good Example (ORCHESTRATOR): +> "I need BACEN compliance. Let me dispatch finops-analyzer to understand requirements, then finops-automation to generate templates." + +### Bad Example (OPERATOR): +> "I'll manually read BACEN documentation and write templates myself." + +--- + +## Reporter Platform Integration + +Generated .tpl files integrate directly with Reporter platform: +- **Input:** Validated specifications from finops-analyzer +- **Output:** .tpl files (XML, HTML, TXT formats) +- **Deployment:** Direct integration with Reporter +- **Validation:** Compliance verified by template structure + +--- + +## Available in This Plugin + +**Agents:** +- finops-analyzer (Gate 1-2) +- finops-automation (Gate 3) + +**Skills:** +- using-finops-team (this skill - plugin introduction) +- regulatory-templates (overview/index skill) +- regulatory-templates-setup (Gate 0: Setup & initialization) +- regulatory-templates-gate1 (Gate 1: Compliance analysis) +- regulatory-templates-gate2 (Gate 2: Field mapping & validation) +- regulatory-templates-gate3 (Gate 3: Template generation) + +**Note:** If agents are unavailable, check if ring-finops-team is enabled in `.claude-plugin/marketplace.json`. + +--- + +## Integration with Other Plugins + +- **using-ring** (default) – ORCHESTRATOR principle for ALL agents +- **using-dev-team** – Developer specialists +- **using-pm-team** – Pre-dev workflow agents + +Dispatch based on your need: +- General code review → default plugin agents +- Regulatory compliance → ring-finops-team agents +- Developer expertise → ring-dev-team agents +- Feature planning → ring-pm-team agents