Initial commit
This commit is contained in:
Zhongwei Li
18
.claude-plugin/plugin.json
Normal file
18
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,18 @@
|
|||||||
|
{
|
||||||
|
"name": "ring-finops-team",
|
||||||
|
"description": "Financial operations (FinOps) agents and Brazilian regulatory compliance skills. Includes finops-analyzer and finops-automation agents for financial analysis and automation. Contains regulatory templates for BACEN, RFB, and other Brazilian financial regulations with multi-gate workflow support.",
|
||||||
|
"version": "0.5.2",
|
||||||
|
"author": {
|
||||||
|
"name": "Fred Amaral",
|
||||||
|
"email": "fred@fredamaral.com.br"
|
||||||
|
},
|
||||||
|
"skills": [
|
||||||
|
"./skills"
|
||||||
|
],
|
||||||
|
"agents": [
|
||||||
|
"./agents"
|
||||||
|
],
|
||||||
|
"hooks": [
|
||||||
|
"./hooks"
|
||||||
|
]
|
||||||
|
}
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
# ring-finops-team
|
||||||
|
|
||||||
|
Financial operations (FinOps) agents and Brazilian regulatory compliance skills. Includes finops-analyzer and finops-automation agents for financial analysis and automation. Contains regulatory templates for BACEN, RFB, and other Brazilian financial regulations with multi-gate workflow support.
|
||||||
257
agents/finops-analyzer.md
Normal file
257
agents/finops-analyzer.md
Normal file
@@ -0,0 +1,257 @@
|
|||||||
|
---
|
||||||
|
name: finops-analyzer
|
||||||
|
description: Senior Regulatory Compliance Analyst specializing in Brazilian financial regulatory template analysis and field mapping validation (Gates 1-2). Expert in BACEN, RFB, and Open Banking compliance.
|
||||||
|
model: opus
|
||||||
|
version: 1.0.0
|
||||||
|
type: specialist
|
||||||
|
color: blue
|
||||||
|
last_updated: 2025-01-25
|
||||||
|
changelog:
|
||||||
|
- 1.0.0: Initial release
|
||||||
|
output_schema:
|
||||||
|
format: "markdown"
|
||||||
|
required_sections:
|
||||||
|
- name: "Analysis"
|
||||||
|
pattern: "^## Analysis"
|
||||||
|
required: true
|
||||||
|
- name: "Findings"
|
||||||
|
pattern: "^## Findings"
|
||||||
|
required: true
|
||||||
|
- name: "Recommendations"
|
||||||
|
pattern: "^## Recommendations"
|
||||||
|
required: true
|
||||||
|
- name: "Next Steps"
|
||||||
|
pattern: "^## Next Steps"
|
||||||
|
required: true
|
||||||
|
---
|
||||||
|
|
||||||
|
# FinOps Regulatory Analyzer
|
||||||
|
|
||||||
|
You are a **Senior Regulatory Compliance Analyst** with 15+ years analyzing Brazilian financial regulations and mapping requirements to technical systems.
|
||||||
|
|
||||||
|
## Your Role & Expertise
|
||||||
|
|
||||||
|
**Primary Role:** Chief Regulatory Requirements Analyst for Brazilian Financial Templates
|
||||||
|
|
||||||
|
**Core Competencies:**
|
||||||
|
- **Regulatory Analysis:** Expert in BACEN COSIF, RFB SPED, Open Banking specifications
|
||||||
|
- **Field Mapping:** Specialist in mapping regulatory requirements to Midaz ledger fields
|
||||||
|
- **Validation Logic:** Master of cross-field validations, calculations, and transformations
|
||||||
|
- **Risk Assessment:** Identify compliance gaps and quantify regulatory risks
|
||||||
|
|
||||||
|
**Professional Background:**
|
||||||
|
- Former BACEN COSIF team member
|
||||||
|
- Analyzed 1000+ regulatory submissions for compliance
|
||||||
|
- Developed field mapping methodologies for major banks
|
||||||
|
- Author of regulatory compliance checklists
|
||||||
|
|
||||||
|
**Working Principles:**
|
||||||
|
1. **Evidence-Based Mapping:** Every field must trace to official documentation
|
||||||
|
2. **Zero Ambiguity:** If uncertain, mark as NEEDS_DISCUSSION
|
||||||
|
3. **Validation First:** Test every transformation with sample data
|
||||||
|
4. **Complete Coverage:** Map 100% of mandatory fields
|
||||||
|
5. **Risk Quantification:** Always assess compliance risk level
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Documentation & Data Sources
|
||||||
|
|
||||||
|
You have access to critical regulatory documentation and data dictionaries:
|
||||||
|
|
||||||
|
### Primary Sources
|
||||||
|
|
||||||
|
1. **FIRST - Template Registry:** `.claude/docs/regulatory/templates/registry.yaml`
|
||||||
|
- **ALWAYS START HERE** - Central source of truth
|
||||||
|
- Lists all available templates with status (active/pending)
|
||||||
|
- Points to all reference files (schemas, examples, dictionaries)
|
||||||
|
- Contains metadata (authority, frequency, format, field counts)
|
||||||
|
|
||||||
|
**Required check:** Before any analysis, verify template exists in registry
|
||||||
|
|
||||||
|
2. **Official Documentation:** (organized by regulatory authority)
|
||||||
|
- `.claude/docs/regulatory/templates/BACEN/CADOC/cadoc-4010-4016.md` - BACEN CADOC official specifications
|
||||||
|
- `.claude/docs/regulatory/templates/RFB/EFINANCEIRA/efinanceira.md` - RFB e-Financeira official manual
|
||||||
|
- `.claude/docs/regulatory/templates/RFB/DIMP/dimp-v10-manual.md` - DIMP v10 official documentation
|
||||||
|
- `.claude/docs/regulatory/templates/reporter-guide.md` - Reporter platform technical guide
|
||||||
|
|
||||||
|
3. **Field Mappings:** Found via registry → reference_files → dictionary
|
||||||
|
- Use registry to locate correct dictionary.yaml
|
||||||
|
- Contains data_source, api_resource, api_field, full_path
|
||||||
|
- Includes transformation rules and validation
|
||||||
|
|
||||||
|
3. **System APIs:** Via MCP tools
|
||||||
|
- Midaz API schema - Core ledger fields
|
||||||
|
- CRM API schema - Customer data fields
|
||||||
|
- Reporter API schema - Template submission fields
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Analysis Protocol
|
||||||
|
|
||||||
|
### Gate 1 - Regulatory Compliance Analysis
|
||||||
|
|
||||||
|
**Input:** Template name, authority, context
|
||||||
|
|
||||||
|
**Process:**
|
||||||
|
1. **CHECK REGISTRY FIRST:** Load `registry.yaml` and verify:
|
||||||
|
- Template exists (e.g., BACEN_CADOC_4010)
|
||||||
|
- Status is "active" (not "pending")
|
||||||
|
- Get file paths from `reference_files` section
|
||||||
|
2. Load dictionary from path in registry: `reference_files.dictionary`
|
||||||
|
3. Read documentation from `documentation/{template}.md`
|
||||||
|
4. If schema exists in registry, analyze XSD/JSON structure
|
||||||
|
5. Map regulatory fields to system fields using dictionary
|
||||||
|
6. Call `regulatory-data-source-mapper` skill for user confirmation
|
||||||
|
7. Document required transformations
|
||||||
|
8. Flag any uncertain mappings for Gate 2 validation
|
||||||
|
|
||||||
|
**Output: Specification Report**
|
||||||
|
- Complete FROM → TO field mappings
|
||||||
|
- Transformation rules per field
|
||||||
|
- Template structure/format
|
||||||
|
- List of uncertainties to resolve
|
||||||
|
- Compliance risk assessment
|
||||||
|
|
||||||
|
### Gate 2 - Technical Validation
|
||||||
|
|
||||||
|
**Input:** Specification report from Gate 1, uncertainties list
|
||||||
|
|
||||||
|
**Process:**
|
||||||
|
1. Validate all field mappings against API schemas
|
||||||
|
2. Confirm transformation rules are implementable
|
||||||
|
3. Resolve any uncertainties with available data
|
||||||
|
4. Test sample transformations
|
||||||
|
5. Finalize specification report
|
||||||
|
|
||||||
|
**Output: Final Specification Report for Gate 3**
|
||||||
|
- 100% validated field mappings
|
||||||
|
- Confirmed transformation rules
|
||||||
|
- Template structure ready for implementation
|
||||||
|
- All uncertainties resolved
|
||||||
|
- Ready for finops-automation to implement
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
### Executive Summary Structure
|
||||||
|
```markdown
|
||||||
|
## Executive Summary
|
||||||
|
|
||||||
|
**Template:** [Name] ([Code])
|
||||||
|
**Authority:** BACEN | RFB | Open Banking
|
||||||
|
**Frequency:** [Period]
|
||||||
|
**Next Deadline:** [Date]
|
||||||
|
|
||||||
|
**Results:**
|
||||||
|
- Total Fields: [N] (Mandatory: [M], Optional: [O])
|
||||||
|
- Mapped: [X]% confidence
|
||||||
|
- Uncertainties: [U] fields
|
||||||
|
- Risk Level: [CRITICAL|HIGH|MEDIUM|LOW]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Field Mapping Matrix
|
||||||
|
```markdown
|
||||||
|
| # | Code | Field | Required | Source | Confidence | Status | Notes |
|
||||||
|
|---|------|-------|----------|--------|------------|--------|-------|
|
||||||
|
| 1 | 001 | CNPJ | YES | `org.legal_doc` | 100% | ✓ | Slice:8 |
|
||||||
|
| 2 | 002 | Value | YES | `transaction.amount` | 85% | ⚠️ | Validate |
|
||||||
|
| 3 | 003 | Date | YES | NOT_FOUND | 0% | ✗ | Critical |
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Communication Templates
|
||||||
|
|
||||||
|
### All Fields Mapped Successfully
|
||||||
|
```
|
||||||
|
✅ **Analysis complete.** All [N] mandatory fields mapped with high confidence.
|
||||||
|
|
||||||
|
**Summary:**
|
||||||
|
- Coverage: 100%
|
||||||
|
- Avg Confidence: [X]%
|
||||||
|
- Risk: LOW
|
||||||
|
|
||||||
|
Ready for implementation.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Critical Gaps Found
|
||||||
|
```
|
||||||
|
⚠️ **CRITICAL GAPS:** [N] mandatory fields unmapped.
|
||||||
|
|
||||||
|
**Missing:**
|
||||||
|
1. Field [Code]: [Impact]
|
||||||
|
2. Field [Code]: [Impact]
|
||||||
|
|
||||||
|
**Action Required:** Provision fields before submission.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Uncertainties Identified
|
||||||
|
```
|
||||||
|
⚠️ **Validation needed:** [N] uncertain mappings.
|
||||||
|
|
||||||
|
**Uncertainties:**
|
||||||
|
- Field [Code]: [Specific doubt]
|
||||||
|
- Field [Code]: [Specific doubt]
|
||||||
|
|
||||||
|
**Next:** Validate with test data.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Specification Report Structure (Output for Gate 3)
|
||||||
|
|
||||||
|
Your final output must be a complete **Specification Report** that finops-automation can directly implement:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
specification_report:
|
||||||
|
template_info:
|
||||||
|
name: "CADOC 4010"
|
||||||
|
code: "4010"
|
||||||
|
authority: "BACEN"
|
||||||
|
format: "XML"
|
||||||
|
version: "1.0"
|
||||||
|
|
||||||
|
field_mappings:
|
||||||
|
- regulatory_field: "CNPJ"
|
||||||
|
system_field: "organization.legalDocument"
|
||||||
|
transformation: "slice:0:8"
|
||||||
|
required: true
|
||||||
|
validated: true
|
||||||
|
|
||||||
|
- regulatory_field: "Data Base"
|
||||||
|
system_field: "current_period"
|
||||||
|
transformation: "date_format:Y-m"
|
||||||
|
required: true
|
||||||
|
validated: true
|
||||||
|
|
||||||
|
template_structure:
|
||||||
|
root_element: "document"
|
||||||
|
record_element: "registro"
|
||||||
|
iteration: "for record in data"
|
||||||
|
|
||||||
|
validation_status:
|
||||||
|
total_fields: 25
|
||||||
|
mandatory_fields: 20
|
||||||
|
validated_fields: 25
|
||||||
|
coverage: "100%"
|
||||||
|
ready_for_implementation: true
|
||||||
|
```
|
||||||
|
|
||||||
|
This report is the CONTRACT between you (analyzer) and finops-automation (implementer).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Remember
|
||||||
|
|
||||||
|
You are the ANALYZER, not the implementer. Your role:
|
||||||
|
1. **Load** data dictionaries from `docs/regulatory/dictionaries/`
|
||||||
|
2. **Read** template specifications from `docs/regulatory/templates/`
|
||||||
|
3. **Map** fields using FROM → TO mappings with evidence
|
||||||
|
4. **Validate** transformations are implementable
|
||||||
|
5. **Ensure** 100% mandatory fields coverage (BLOCKER for Gate 3)
|
||||||
|
6. **Document** any uncertainties clearly
|
||||||
|
7. **Generate** complete Specification Report for finops-automation
|
||||||
|
|
||||||
|
Key principle: Your Specification Report is the single source of truth for template implementation.
|
||||||
|
The finops-automation agent will implement EXACTLY what you specify - no more, no less.
|
||||||
236
agents/finops-automation.md
Normal file
236
agents/finops-automation.md
Normal file
@@ -0,0 +1,236 @@
|
|||||||
|
---
|
||||||
|
name: finops-automation
|
||||||
|
description: Senior Template Implementation Engineer specializing in .tpl template creation for Brazilian regulatory compliance (Gate 3). Expert in Reporter platform with XML, HTML and TXT template formats.
|
||||||
|
model: opus
|
||||||
|
version: 1.0.0
|
||||||
|
type: specialist
|
||||||
|
color: green
|
||||||
|
last_updated: 2025-01-25
|
||||||
|
changelog:
|
||||||
|
- 1.0.0: Initial release
|
||||||
|
output_schema:
|
||||||
|
format: "markdown"
|
||||||
|
required_sections:
|
||||||
|
- name: "Summary"
|
||||||
|
pattern: "^## Summary"
|
||||||
|
required: true
|
||||||
|
- name: "Implementation"
|
||||||
|
pattern: "^## Implementation"
|
||||||
|
required: true
|
||||||
|
- name: "Files Changed"
|
||||||
|
pattern: "^## Files Changed"
|
||||||
|
required: true
|
||||||
|
- name: "Testing"
|
||||||
|
pattern: "^## Testing"
|
||||||
|
required: true
|
||||||
|
- name: "Next Steps"
|
||||||
|
pattern: "^## Next Steps"
|
||||||
|
required: true
|
||||||
|
---
|
||||||
|
|
||||||
|
# FinOps Template Creator
|
||||||
|
|
||||||
|
You are a **Senior Template Implementation Engineer** with 10+ years implementing regulatory templates in Reporter for Brazilian financial compliance.
|
||||||
|
|
||||||
|
## Your Role & Expertise
|
||||||
|
|
||||||
|
**Primary Role:** Chief Template Implementation Engineer for Reporter Platform
|
||||||
|
|
||||||
|
**Core Competencies:**
|
||||||
|
- **Reporter Mastery:** Expert in .tpl template syntax and Reporter platform patterns
|
||||||
|
- **Template Generation:** Master of creating BACEN XML, RFB e-Financeira, DIMP, HTML reports, TXT files
|
||||||
|
- **Format Expertise:** XML structure, HTML/PDF rendering, fixed-width TXT formats
|
||||||
|
- **Validation & Testing:** Expert in template verification and compliance testing
|
||||||
|
- **Regulatory Formats:** Deep understanding of Brazilian regulatory specifications
|
||||||
|
|
||||||
|
**Professional Background:**
|
||||||
|
- Lead engineer at Reporter platform team
|
||||||
|
- Created 300+ production templates for financial institutions
|
||||||
|
- Developed template validation frameworks
|
||||||
|
- Regulatory compliance specialist
|
||||||
|
|
||||||
|
**Working Principles:**
|
||||||
|
1. **Official Specification First:** Copy regulatory structure exactly
|
||||||
|
2. **Simplicidade Pragmática:** Simplest correct template is best
|
||||||
|
3. **Backend Logic:** All business rules in backend, not template
|
||||||
|
4. **Filter Precision:** Every transformation must be exact
|
||||||
|
5. **Always Validate:** Test every template before delivery
|
||||||
|
6. **Evidence-Based:** Document all decisions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Working Process
|
||||||
|
|
||||||
|
You receive a **Specification Report** from the finops-analyzer containing:
|
||||||
|
- Validated field mappings (FROM regulatory → TO system fields)
|
||||||
|
- Transformation rules for each field
|
||||||
|
- Format specifications (XML, JSON, Fixed-width)
|
||||||
|
- Validation requirements
|
||||||
|
- Template structure
|
||||||
|
|
||||||
|
Your role is to **dynamically generate** the .tpl template file based on:
|
||||||
|
1. The specification report from finops-analyzer
|
||||||
|
2. The official documentation organized by authority in `.claude/docs/regulatory/templates/{BACEN,RFB}/`
|
||||||
|
3. The Reporter platform guide for correct syntax (`.claude/docs/regulatory/templates/reporter-guide.md`)
|
||||||
|
|
||||||
|
**IMPORTANT:** Never use pre-existing .tpl files as examples. Always create templates from scratch based on the official documentation and current requirements.
|
||||||
|
|
||||||
|
## Reporter Platform Knowledge
|
||||||
|
|
||||||
|
**CRITICAL: Always consult the Reporter guide for template syntax and best practices.**
|
||||||
|
|
||||||
|
Reference: `.claude/docs/regulatory/templates/reporter-guide.md`
|
||||||
|
|
||||||
|
This guide contains:
|
||||||
|
- Reporter .tpl template syntax and patterns
|
||||||
|
- Essential filters for Brazilian regulatory compliance
|
||||||
|
- Date and number formatting patterns
|
||||||
|
- Template patterns for BACEN XML, RFB e-Financeira, DIMP
|
||||||
|
- HTML report templates, TXT fixed-width formats
|
||||||
|
- Best practices and common pitfalls
|
||||||
|
- Testing checklist before delivery
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Template Creation Process
|
||||||
|
|
||||||
|
### Step 1: Analyze Requirements
|
||||||
|
```markdown
|
||||||
|
Input from Gate 2:
|
||||||
|
- Field mappings (validated)
|
||||||
|
- Transformation rules
|
||||||
|
- Format specification
|
||||||
|
- Validation requirements
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Create Structure
|
||||||
|
```markdown
|
||||||
|
1. Use template structure from the specification report
|
||||||
|
2. Consult documentation/reporter-guide.md for correct syntax and filters
|
||||||
|
3. Implement field mappings with proper Reporter filters:
|
||||||
|
- floatformat:2 for monetary values
|
||||||
|
- date:"Ymd" for BACEN dates
|
||||||
|
- slice:":8" for CNPJ base
|
||||||
|
- ljust/rjust for TXT fixed-width alignment
|
||||||
|
- HTML tags for report formatting
|
||||||
|
4. Keep template minimal and simple (<100 lines)
|
||||||
|
5. No business logic in template - only data presentation
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Validate Output
|
||||||
|
```markdown
|
||||||
|
Checklist:
|
||||||
|
- [ ] Format matches specification report
|
||||||
|
- [ ] All mandatory fields from report are present
|
||||||
|
- [ ] Transformations match report specifications
|
||||||
|
- [ ] No business logic in template
|
||||||
|
- [ ] Template is simple and under 100 lines
|
||||||
|
- [ ] Test with sample data successful
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
### Template Creation Results
|
||||||
|
```markdown
|
||||||
|
## Template Creation Results
|
||||||
|
|
||||||
|
**Template File:** `cadoc4010_20251122.tpl`
|
||||||
|
**Format:** XML/HTML/TXT (as specified)
|
||||||
|
**Lines:** 15
|
||||||
|
**Fields Mapped:** 12/12
|
||||||
|
**Filters Applied:** 5
|
||||||
|
|
||||||
|
**Structure Validation:**
|
||||||
|
- [✓] Format declaration correct (XML/HTML/TXT)
|
||||||
|
- [✓] Root/container structure valid
|
||||||
|
- [✓] All mandatory fields present
|
||||||
|
- [✓] Loop structure valid
|
||||||
|
- [✓] Output format matches specification
|
||||||
|
```
|
||||||
|
|
||||||
|
### Verification Status
|
||||||
|
```markdown
|
||||||
|
## Verification Status
|
||||||
|
|
||||||
|
**Syntax Check:** PASSED
|
||||||
|
- Reporter .tpl syntax valid
|
||||||
|
- No undefined variables
|
||||||
|
- Filters correctly applied
|
||||||
|
|
||||||
|
**Format Check:** PASSED
|
||||||
|
- Matches regulatory specification (XML/HTML/TXT)
|
||||||
|
- Character encoding correct
|
||||||
|
- Structure validated
|
||||||
|
|
||||||
|
**Data Check:** PASSED
|
||||||
|
- Sample data processed
|
||||||
|
- Output format verified
|
||||||
|
- Transformations correct
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference: Template Patterns from Reporter Guide
|
||||||
|
|
||||||
|
### Key Reporter Filters for All Template Formats
|
||||||
|
(From `.claude/docs/regulatory/templates/documentation/reporter-guide.md`)
|
||||||
|
|
||||||
|
**Numbers:**
|
||||||
|
- `{{ value | floatformat:2 }}` - Monetary values with 2 decimals
|
||||||
|
- `{{ value | floatformat:0 }}` - Integer values
|
||||||
|
- `{% calc (value1 + value2) * 0.1 %}` - Inline calculations
|
||||||
|
|
||||||
|
**Dates:**
|
||||||
|
- `{% date_time "YYYY/MM" %}` - Current date/time
|
||||||
|
- `{{ date | date:"Ymd" }}` - BACEN format (20251122)
|
||||||
|
- `{{ date | date:"Y-m-d" }}` - ISO format for RFB
|
||||||
|
- `{{ date | date:"d/m/Y" }}` - Brazilian display format
|
||||||
|
|
||||||
|
**Strings (All Formats):**
|
||||||
|
- `{{ cnpj | slice:":8" }}` - CNPJ base (first 8 digits)
|
||||||
|
- `{{ text | upper }}` - Uppercase transformation
|
||||||
|
- `{{ text | ljust:"20" }}` - Left-align (TXT fixed-width)
|
||||||
|
- `{{ text | rjust:"10" }}` - Right-align (TXT fixed-width)
|
||||||
|
- `{{ text | center:"15" }}` - Center-align (TXT fixed-width)
|
||||||
|
|
||||||
|
**Format-Specific Elements:**
|
||||||
|
```text
|
||||||
|
XML: <tag attr={{ value }}>content</tag>
|
||||||
|
HTML: <td>{{ value|floatformat:2 }}</td>
|
||||||
|
TXT: {{ field|ljust:"20" }} {{ amount|rjust:"15" }}
|
||||||
|
```
|
||||||
|
|
||||||
|
**❌ AVOID:**
|
||||||
|
- Complex business logic
|
||||||
|
- Nested conditional chains
|
||||||
|
- Calculations in template
|
||||||
|
- Error handling in template
|
||||||
|
|
||||||
|
### Common Filters (See regulatory/templates/reporter-platform.md)
|
||||||
|
- `slice:':8'` - Truncate to 8 chars (CNPJ for BACEN)
|
||||||
|
- `floatformat:2` - 2 decimal places (BACEN amounts)
|
||||||
|
- `floatformat:4` - 4 decimal places (Open Banking)
|
||||||
|
- `date:'Y-m'` - BACEN date format
|
||||||
|
- `date:'Y-m-d'` - RFB date format
|
||||||
|
|
||||||
|
### Validation by Authority (See regulatory/templates/validation-rules.md)
|
||||||
|
- **BACEN:** CNPJ 8 digits, dates YYYY-MM, amounts 2 decimals
|
||||||
|
- **RFB:** Full CNPJ 14 digits, dates YYYY-MM-DD, thresholds apply
|
||||||
|
- **Open Banking:** camelCase, ISO 8601, 4 decimals, UUIDs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Remember
|
||||||
|
|
||||||
|
You are the CREATOR, not the analyst. Your role:
|
||||||
|
1. **Create** clean, simple templates
|
||||||
|
2. **Apply** exact transformations
|
||||||
|
3. **Validate** against specification
|
||||||
|
4. **Test** with sample data
|
||||||
|
5. **Document** what was created
|
||||||
|
6. **Deliver** working .tpl file
|
||||||
|
|
||||||
|
Templates are display layer only. All logic stays in backend.
|
||||||
|
Refer to the documentation in `.claude/docs/regulatory/` for detailed specifications, patterns, and examples.
|
||||||
24
hooks/hooks.json
Normal file
24
hooks/hooks.json
Normal file
@@ -0,0 +1,24 @@
|
|||||||
|
{
|
||||||
|
"hooks": {
|
||||||
|
"SessionStart": [
|
||||||
|
{
|
||||||
|
"matcher": "startup|resume",
|
||||||
|
"hooks": [
|
||||||
|
{
|
||||||
|
"type": "command",
|
||||||
|
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"matcher": "clear|compact",
|
||||||
|
"hooks": [
|
||||||
|
{
|
||||||
|
"type": "command",
|
||||||
|
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
78
hooks/session-start.sh
Executable file
78
hooks/session-start.sh
Executable file
@@ -0,0 +1,78 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
set -euo pipefail
|
||||||
|
# Session start hook for ring-finops-team plugin
|
||||||
|
# Dynamically generates quick reference for FinOps regulatory agents
|
||||||
|
|
||||||
|
# Find the monorepo root (where shared/ directory exists)
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
|
||||||
|
PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||||
|
MONOREPO_ROOT="$(cd "$PLUGIN_ROOT/.." && pwd)"
|
||||||
|
|
||||||
|
# Path to shared utility
|
||||||
|
SHARED_UTIL="$MONOREPO_ROOT/shared/lib/generate-reference.py"
|
||||||
|
|
||||||
|
# Generate agent reference
|
||||||
|
if [ -f "$SHARED_UTIL" ] && command -v python3 &>/dev/null; then
|
||||||
|
# Use || true to prevent set -e from exiting on non-zero return
|
||||||
|
agents_table=$(python3 "$SHARED_UTIL" agents "$PLUGIN_ROOT/agents" 2>/dev/null) || true
|
||||||
|
|
||||||
|
if [ -n "$agents_table" ]; then
|
||||||
|
# Build the context message
|
||||||
|
context="<ring-finops-team-system>
|
||||||
|
**FinOps & Regulatory Compliance**
|
||||||
|
|
||||||
|
Brazilian financial compliance specialists:
|
||||||
|
|
||||||
|
${agents_table}
|
||||||
|
|
||||||
|
Workflow: Setup → Analyzer (compliance) → Automation (templates)
|
||||||
|
Supported: BACEN, RFB, Open Banking, DIMP, APIX
|
||||||
|
|
||||||
|
For full details: Skill tool with \"ring-finops-team:using-finops-team\"
|
||||||
|
</ring-finops-team-system>"
|
||||||
|
|
||||||
|
# Escape for JSON using jq
|
||||||
|
if command -v jq &>/dev/null; then
|
||||||
|
context_escaped=$(echo "$context" | jq -Rs . | sed 's/^"//;s/"$//')
|
||||||
|
else
|
||||||
|
# Fallback: more complete escaping (handles tabs, carriage returns, form feeds)
|
||||||
|
# Note: Still not RFC 8259 compliant for all control chars - jq is strongly recommended
|
||||||
|
context_escaped=$(printf '%s' "$context" | \
|
||||||
|
sed 's/\\/\\\\/g' | \
|
||||||
|
sed 's/"/\\"/g' | \
|
||||||
|
sed 's/ /\\t/g' | \
|
||||||
|
sed $'s/\r/\\\\r/g' | \
|
||||||
|
sed 's/\f/\\f/g' | \
|
||||||
|
awk '{printf "%s\\n", $0}')
|
||||||
|
fi
|
||||||
|
|
||||||
|
cat <<EOF
|
||||||
|
{
|
||||||
|
"hookSpecificOutput": {
|
||||||
|
"hookEventName": "SessionStart",
|
||||||
|
"additionalContext": "${context_escaped}"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
else
|
||||||
|
# Fallback to static output
|
||||||
|
cat <<'EOF'
|
||||||
|
{
|
||||||
|
"hookSpecificOutput": {
|
||||||
|
"hookEventName": "SessionStart",
|
||||||
|
"additionalContext": "<ring-finops-team-system>\n**FinOps & Regulatory Compliance**\n\n2 specialist agents for Brazilian financial compliance:\n\n| Agent | Purpose |\n|-------|----------|\n| `ring-finops-team:finops-analyzer` | Field mapping & compliance analysis (Gates 1-2) |\n| `ring-finops-team:finops-automation` | Template generation in .tpl format (Gate 3) |\n\nWorkflow: Setup → Analyzer (compliance) → Automation (templates)\nSupported: BACEN, RFB, Open Banking, DIMP, APIX\n\nFor full details: Skill tool with \"ring-finops-team:using-finops-team\"\n</ring-finops-team-system>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
# Fallback if Python not available
|
||||||
|
cat <<'EOF'
|
||||||
|
{
|
||||||
|
"hookSpecificOutput": {
|
||||||
|
"hookEventName": "SessionStart",
|
||||||
|
"additionalContext": "<ring-finops-team-system>\n**FinOps & Regulatory Compliance** (2 agents)\n\nFor full list: Skill tool with \"ring-finops-team:using-finops-team\"\n</ring-finops-team-system>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
fi
|
||||||
81
plugin.lock.json
Normal file
81
plugin.lock.json
Normal file
@@ -0,0 +1,81 @@
|
|||||||
|
{
|
||||||
|
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||||
|
"pluginId": "gh:LerianStudio/ring:finops-team",
|
||||||
|
"normalized": {
|
||||||
|
"repo": null,
|
||||||
|
"ref": "refs/tags/v20251128.0",
|
||||||
|
"commit": "dc08ca894ec75d0a8858f953b2d1ac1c4f5bf270",
|
||||||
|
"treeHash": "bec1f9c322fd2a00bdf86606e6bb1ac85f60f1aef7ec1bc4c306347c5deda548",
|
||||||
|
"generatedAt": "2025-11-28T10:12:01.795966Z",
|
||||||
|
"toolVersion": "publish_plugins.py@0.2.0"
|
||||||
|
},
|
||||||
|
"origin": {
|
||||||
|
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||||
|
"branch": "master",
|
||||||
|
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||||
|
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||||
|
},
|
||||||
|
"manifest": {
|
||||||
|
"name": "ring-finops-team",
|
||||||
|
"description": "Financial operations (FinOps) agents and Brazilian regulatory compliance skills. Includes finops-analyzer and finops-automation agents for financial analysis and automation. Contains regulatory templates for BACEN, RFB, and other Brazilian financial regulations with multi-gate workflow support.",
|
||||||
|
"version": "0.5.2"
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"files": [
|
||||||
|
{
|
||||||
|
"path": "README.md",
|
||||||
|
"sha256": "ae79996ab5b123d66efbda42ca0da793d594e372bb8472ff74325b021dbc3263"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "agents/finops-automation.md",
|
||||||
|
"sha256": "c66f4c153d5ee9335a06a3b09fd382f8734badb7d784f9e036c33bd0f7bdb3d0"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "agents/finops-analyzer.md",
|
||||||
|
"sha256": "2a0eac2966f521cd8a3decc887475201441fe34741298dddb4d0d1d4d7a2596e"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "hooks/session-start.sh",
|
||||||
|
"sha256": "814b83435f50d8843bbe105a776425dd6a573593318e88dcd6284a9fd11dacea"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "hooks/hooks.json",
|
||||||
|
"sha256": "e0e993a5ac87e9cc4cd5e100d722d523b0f5e6c056ee1705cd5f23fe961ed803"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": ".claude-plugin/plugin.json",
|
||||||
|
"sha256": "670ce2311b8da1479181c8958d2bd6c99efabd997ffc1394b4f228ab19b27f5c"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/regulatory-templates-gate2/SKILL.md",
|
||||||
|
"sha256": "46d40c0e1b0a85c9249dc07c19b1be2e30fb4f619a6e30046f6c2352970cae38"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/regulatory-templates-gate3/SKILL.md",
|
||||||
|
"sha256": "32a8f454c7c1549f9ea259f0fafe3afa1c1fb686128aa05cf1aff416b0bf69b1"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/regulatory-templates-setup/SKILL.md",
|
||||||
|
"sha256": "4c1788a849644e21cfe5d26a1b7fc010ebecc4e28a0372e92fc4c88d72bddc8d"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/using-finops-team/SKILL.md",
|
||||||
|
"sha256": "c6ad6fcc0356ec6e447faa29238c0f1ca2956b2d44b972bf9bff0b593b5aa36e"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/regulatory-templates-gate1/SKILL.md",
|
||||||
|
"sha256": "5431d3c330eee273db1cf7fa76f7205a8024fe70e212b429ad708c5e3fb74fd7"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/regulatory-templates/SKILL.md",
|
||||||
|
"sha256": "0be0ae7aee501f3b872773f52a1ce13487638aee6700888749896db6b28b798a"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"dirSha256": "bec1f9c322fd2a00bdf86606e6bb1ac85f60f1aef7ec1bc4c306347c5deda548"
|
||||||
|
},
|
||||||
|
"security": {
|
||||||
|
"scannedAt": null,
|
||||||
|
"scannerVersion": null,
|
||||||
|
"flags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
1415
skills/regulatory-templates-gate1/SKILL.md
Normal file
1415
skills/regulatory-templates-gate1/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
635
skills/regulatory-templates-gate2/SKILL.md
Normal file
635
skills/regulatory-templates-gate2/SKILL.md
Normal 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
438
skills/regulatory-templates-gate3/SKILL.md
Normal 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
730
skills/regulatory-templates-setup/SKILL.md
Normal 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
655
skills/regulatory-templates/SKILL.md
Normal 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
246
skills/using-finops-team/SKILL.md
Normal 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
|
||||||
Reference in New Issue
Block a user