zhongwei/gh-lerianstudio-ring-finops-team
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:37:17 +08:00
commit ccb6e73621
13 changed files with 4816 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1415
skills/regulatory-templates-gate1/SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff

635
skills/regulatory-templates-gate2/SKILL.md Normal file
View File

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

438
skills/regulatory-templates-gate3/SKILL.md Normal file
View File

@@ -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 %}
<field>{{ value }}</field>
{% 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

730
skills/regulatory-templates-setup/SKILL.md Normal file
View File

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

655
skills/regulatory-templates/SKILL.md Normal file
View File

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

246
skills/using-finops-team/SKILL.md Normal file
View File

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