Initial commit

2025-11-30 08:37:17 +08:00
commit ccb6e73621
13 changed files with 4816 additions and 0 deletions
--- a/skills/regulatory-templates/SKILL.md
+++ 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