REASONING-FRAMEWORK.md - Reasoning Chains Visíveis¶
Transparência total no raciocínio dos agentes.
Visão Geral¶
O Reasoning Framework garante que todo raciocínio dos agentes
seja VISÍVEL e EXPLICÁVEL.
"Se você não consegue explicar, você não entende."
- Richard Feynman
Isso cria:
1. Transparência - usuário vê como chegamos à conclusão
2. Confiança - mostramos o trabalho, não só a resposta
3. Verificabilidade - usuário pode checar cada passo
4. Aprendizado - erros de reasoning são identificáveis
Arquitetura de Reasoning¶
┌─────────────────────────────────────────────────────────────────┐
│ REASONING FRAMEWORK │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ REASONING CHAIN │ │
│ │ │ │
│ │ Input → Parse → Analyze → Synthesize → Conclude → Output │ │
│ │ ↓ ↓ ↓ ↓ ↓ ↓ │ │
│ │ [Log] [Log] [Log] [Log] [Log] [Log] │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ REASONING │ │ CONFIDENCE │ │ EXPLANATION │ │
│ │ STEPS │ │ TRACKER │ │ GENERATOR │ │
│ │ │ │ │ │ │ │
│ │ Cada passo │ │ Quão certo │ │ Traduz para │ │
│ │ documentado │ │ estamos? │ │ linguagem clara │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ ASSUMPTION TRACKER │ │
│ │ │ │
│ │ Todas as premissas explícitas e verificáveis │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
1. Reasoning Chain¶
Estrutura de uma Chain¶
REASONING_CHAIN:
id: "rc_2025-12-28_001"
query: "[Pergunta original]"
timestamp: "2025-12-28T14:30:00Z"
steps:
- step: 1
name: "PARSE"
input: "[Query do usuário]"
action: "Interpretar intenção"
output: "Intent: DECISION, Keywords: [pricing, tier]"
confidence: 0.95
time_ms: 50
- step: 2
name: "CONTEXT"
input: "[Intent parsed]"
action: "Buscar contexto relevante"
output: "Encontrados: 3 episódios, 5 fatos, 1 workflow"
confidence: 0.90
time_ms: 200
- step: 3
name: "SQUAD"
input: "[Context + Intent]"
action: "Selecionar agentes"
output: "Squad: CRO (Lead), CFO (Specialist), Pre-Mortem (Validator)"
confidence: 0.85
reasoning: "Pricing → CRO; Financeiro → CFO; Decisão → Pre-Mortem"
time_ms: 100
- step: 4
name: "ANALYZE"
input: "[Context + Squad inputs]"
action: "Cada agente analisa"
outputs:
CRO: "Preço deve refletir valor entregue..."
CFO: "Margem mínima necessária é..."
Pre-Mortem: "Riscos: [lista]"
confidence: 0.80
time_ms: 1500
- step: 5
name: "SYNTHESIZE"
input: "[Todos os outputs]"
action: "Integrar perspectivas"
output: "Consenso em X, Divergência em Y"
confidence: 0.82
time_ms: 300
- step: 6
name: "CONCLUDE"
input: "[Síntese]"
action: "Formular recomendação"
output: "Recomendo Z porque..."
confidence: 0.78
reasoning: "Baseado em consenso + peso de CRO"
time_ms: 200
totals:
steps: 6
total_time_ms: 2350
final_confidence: 0.78
agents_used: 3
Step Types¶
STEP_TYPES:
PARSE:
Purpose: Entender o que usuário quer
Outputs: Intent, keywords, entities
Confidence Source: Keyword match strength
CONTEXT:
Purpose: Buscar informação relevante
Outputs: Episódios, fatos, procedures
Confidence Source: Relevance scores
SQUAD:
Purpose: Montar time de agentes
Outputs: Agentes selecionados, roles
Confidence Source: Match entre intent e agentes
ANALYZE:
Purpose: Cada agente contribui
Outputs: Perspectivas individuais
Confidence Source: Qualidade do input
SYNTHESIZE:
Purpose: Combinar perspectivas
Outputs: Consensos, divergências
Confidence Source: Agreement level
CONCLUDE:
Purpose: Chegar a recomendação
Outputs: Recomendação final
Confidence Source: Síntese + reasoning strength
VALIDATE:
Purpose: Checar consistência
Outputs: Confirmações, warnings
Confidence Source: Validation results
Mapeamento para ORCHESTRATOR¶
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
HARMONIZAÇÃO REASONING-FRAMEWORK ↔ ORCHESTRATOR
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Os steps do Reasoning Framework mapeiam diretamente para os
componentes do ORCHESTRATOR.md:
| REASONING Step | ORCHESTRATOR Component | Descrição |
|----------------|------------------------|-----------|
| PARSE | Intent Classifier | Interpretar query do usuário |
| CONTEXT | Context Analyzer | Buscar informação relevante |
| SQUAD | Squad Selector | Montar time de agentes |
| ANALYZE | Execution Engine | Agentes processam em paralelo |
| SYNTHESIZE | Synthesis Engine | Integrar perspectivas |
| CONCLUDE | Synthesis Engine | Formular recomendação final |
| VALIDATE | (Implícito) | Checagem de consistência |
NOTA:
- REASONING é mais granular sobre o processo de raciocínio
- ORCHESTRATOR é mais focado na execução e fluxo
- Ambos são complementares: ORCHESTRATOR "faz", REASONING "explica"
- Confidence é calculado identicamente em ambos (escala 0-1)
Referência: ORCHESTRATOR.md Seção 4 (Execution Engine)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2. Confidence Tracking¶
Confidence Model¶
CONFIDENCE_MODEL:
Description: >
Confidence representa quão certos estamos em cada passo.
É propagado através da chain e combinado para confidence final.
Scale:
0.95-1.00: Muito Alta (fatos conhecidos, alta evidência)
0.80-0.94: Alta (boa evidência, poucos gaps)
0.60-0.79: Média (evidência mista, incertezas)
0.40-0.59: Baixa (pouca evidência, muitas assumptions)
0.00-0.39: Muito Baixa (especulação, palpite)
Propagation:
- Confidence diminui a cada step (incerteza acumula)
- Conflitos entre agentes reduzem confidence
- Validação bem-sucedida aumenta confidence
- Assumptions não verificadas reduzem confidence
Confidence Calculation¶
def calculate_chain_confidence(steps):
"""
Calcula confidence final da reasoning chain.
"""
# Base confidence from each step
step_confidences = [s.confidence for s in steps]
# Multiplicative (incerteza acumula)
base_confidence = reduce(lambda a, b: a * b, step_confidences)
# Adjustments
adjustments = 0
# + Se há consenso entre agentes
if steps.synthesis.has_consensus:
adjustments += 0.05
# - Se há divergências não resolvidas
if steps.synthesis.has_unresolved_divergence:
adjustments -= 0.10
# - Se há assumptions críticas não verificadas
unverified = count_unverified_assumptions(steps)
adjustments -= unverified * 0.03
# + Se foi validado contra conhecimento existente
if steps.validate and steps.validate.passed:
adjustments += 0.05
final_confidence = min(0.99, max(0.01, base_confidence + adjustments))
return final_confidence
Confidence Display¶
## Confiança da Análise
**Nível: ALTA (82%)**
### Breakdown por Etapa
| Etapa | Confiança | Nota |
|-------|-----------|------|
| Interpretação | 95% | Keywords claros |
| Contexto | 90% | Boa cobertura |
| Squad Selection | 85% | Match forte |
| Análise | 80% | 3 perspectivas |
| Síntese | 82% | Consenso em 2/3 |
| Conclusão | 78% | 1 assumption |
### Fatores
- ✅ Consenso entre CRO e CFO (+5%)
- ⚠️ 1 assumption não verificada (-3%)
- ✅ Validação passou (+5%)
### Interpretação
Com 82% de confiança, esta é uma recomendação sólida.
Considere validar a assumption sobre [X] antes de implementar.
3. Assumption Tracking¶
O que são Assumptions¶
ASSUMPTIONS:
Definition: >
Premissas que assumimos ser verdade para chegar à conclusão,
mas que não foram explicitamente verificadas.
Types:
EXPLICIT:
Description: Declaradas intencionalmente
Example: "Assumindo que o mercado cresce 10%/ano"
Visibility: Alta
IMPLICIT:
Description: Não declaradas mas usadas
Example: Usar benchmark de SaaS para ML
Visibility: Média (detectável)
HIDDEN:
Description: Nem percebemos que assumimos
Example: "Usuários se comportam racionalmente"
Visibility: Baixa (difícil detectar)
Risk:
- Assumptions erradas invalidam conclusão
- Quanto mais assumptions, menor confiança
- Assumptions críticas devem ser validadas
Assumption Schema¶
ASSUMPTION_SCHEMA:
id: "asm_001"
statement: "[O que estamos assumindo]"
type: "EXPLICIT" | "IMPLICIT" | "HIDDEN"
criticality: "HIGH" | "MEDIUM" | "LOW"
in_step: "ANALYZE" # Onde foi feita
affects: ["CONCLUDE"] # O que afeta
basis:
source: "De onde veio esta assumption"
evidence: "Que evidência suporta"
alternative: "O que acontece se for falsa"
verification:
status: "verified" | "unverified" | "invalidated"
method: "Como verificar"
result: null | "[Resultado da verificação]"
impact_if_wrong:
on_conclusion: "Muda recomendação para X"
on_confidence: -0.15
severity: "HIGH"
Assumption Detection¶
def detect_assumptions(reasoning_chain):
"""
Detecta assumptions feitas durante o raciocínio.
"""
assumptions = []
# 1. Explicit assumptions (declaradas)
for step in reasoning_chain.steps:
if "assumindo" in step.reasoning.lower():
assumptions.append(extract_explicit_assumption(step))
if "se" in step.reasoning.lower() and "então" in step.reasoning.lower():
assumptions.append(extract_conditional_assumption(step))
# 2. Implicit assumptions (benchmarks, comparações)
for step in reasoning_chain.steps:
if uses_external_benchmark(step):
assumptions.append(Assumption(
statement=f"Benchmark de {step.benchmark_source} se aplica",
type="IMPLICIT",
criticality=assess_benchmark_criticality(step)
))
# 3. Agent-specific assumptions
for agent_output in reasoning_chain.agent_outputs:
agent_assumptions = agent_output.agent.get_assumptions(agent_output)
assumptions.extend(agent_assumptions)
# 4. Synthesis assumptions
if reasoning_chain.synthesis.has_divergence:
assumptions.append(Assumption(
statement=f"Resolução de divergência favorecendo {synthesis.winner}",
type="EXPLICIT",
criticality="MEDIUM"
))
return assumptions
Assumption Display¶
## Premissas Utilizadas
### Premissas Críticas (Verificar antes de agir)
| # | Premissa | Status | Impacto se errada |
|---|----------|--------|-------------------|
| 1 | Mercado ML cresce 15%/ano | ⚠️ Não verificada | Muda projeção de receita |
| 2 | CAC se mantém estável | ⚠️ Não verificada | Afeta viabilidade |
### Premissas de Suporte (Menor risco)
| # | Premissa | Status | Base |
|---|----------|--------|------|
| 3 | Personas definidas estão corretas | ✅ Verificada | buyer-personas.md |
| 4 | Pricing está alinhado | ✅ Verificada | pricing-strategy.md |
### Nota
Esta análise usa 4 premissas, sendo 2 críticas não verificadas.
Recomendo validar premissas 1 e 2 antes de implementar.
4. Explanation Generator¶
Níveis de Explicação¶
EXPLANATION_LEVELS:
SUMMARY:
For: Usuário quer resposta rápida
Length: 1-3 frases
Includes: Conclusão + principal razão
Example: "Recomendo preço X porque maximiza valor percebido enquanto mantém margem adequada."
STANDARD:
For: Usuário quer entender
Length: 1-2 parágrafos
Includes: Conclusão + principais razões + riscos
Example: Template padrão de resposta multi-agente
DETAILED:
For: Usuário quer verificar
Length: Completo
Includes: Toda reasoning chain + assumptions + confidence
Example: Debugging mode, auditoria
EXPERT:
For: Análise técnica
Length: Técnico
Includes: Logs, metrics, raw data
Example: Desenvolvimento, troubleshooting
Explanation Templates¶
SUMMARY_TEMPLATE: |
**Recomendação:** [Conclusão]
**Razão principal:** [Key reason]
**Confiança:** [HIGH/MEDIUM/LOW]
STANDARD_TEMPLATE: |
## Análise: [Tema]
### Perspectivas Consultadas
[Lista de agentes e suas visões]
### Síntese
[Integração das perspectivas]
### Recomendação
[Conclusão com justificativa]
### Riscos
[Principais riscos identificados]
### Próximos Passos
[Ações recomendadas]
DETAILED_TEMPLATE: |
## Análise Detalhada: [Tema]
### 1. Interpretação da Pergunta
[Como entendemos a query]
### 2. Contexto Utilizado
[Que informações foram buscadas]
### 3. Squad Selecionado
[Quais agentes e por quê]
### 4. Análise por Agente
[Output de cada agente]
### 5. Síntese
[Como chegamos ao consenso]
### 6. Premissas
[Assumptions feitas]
### 7. Confiança
[Breakdown de confidence]
### 8. Recomendação Final
[Conclusão completa]
### 9. Próximos Passos
[Ações com responsáveis]
5. Reasoning Patterns¶
Padrões de Raciocínio¶
REASONING_PATTERNS:
DEDUCTIVE:
Description: De princípios gerais para conclusão específica
Pattern: "Se A (geral) e B (específico), então C"
Use When: Regras claras existem
Example: "CAC < LTV é regra. Nosso CAC é 100, LTV é 300. Logo, OK."
INDUCTIVE:
Description: De exemplos específicos para regra geral
Pattern: "A1, A2, A3 todos mostram X, logo X é padrão"
Use When: Identificando padrões
Example: "3 features com CFO tiveram sucesso. Logo, incluir CFO ajuda."
ABDUCTIVE:
Description: Da observação para melhor explicação
Pattern: "Observamos X. Melhor explicação é Y"
Use When: Diagnosticando problemas
Example: "Churn subiu. Melhor explicação: onboarding ruim."
ANALOGICAL:
Description: De caso similar para conclusão
Pattern: "Caso A teve resultado R. Caso B é similar. Logo, R para B."
Use When: Sem dados diretos
Example: "GoBots cobra X e funciona. Podemos cobrar similar."
COUNTERFACTUAL:
Description: "E se não fizéssemos isso?"
Pattern: "Se não X, então Y (pior)"
Use When: Justificando ação
Example: "Se não ajustar preço, perderemos margem em 6 meses."
Pattern Application¶
PATTERN_APPLICATION:
For "DECISION" Intent:
Primary: DEDUCTIVE (aplicar regras)
Secondary: COUNTERFACTUAL (mostrar alternativa)
Support: ANALOGICAL (benchmarks)
For "TROUBLESHOOTING" Intent:
Primary: ABDUCTIVE (diagnosticar)
Secondary: DEDUCTIVE (aplicar solução)
Support: INDUCTIVE (padrões de erro)
For "PLANNING" Intent:
Primary: DEDUCTIVE (de estratégia para tática)
Secondary: INDUCTIVE (de exemplos para padrão)
Support: ANALOGICAL (casos similares)
For "VALIDATION" Intent:
Primary: DEDUCTIVE (testar contra regras)
Secondary: COUNTERFACTUAL (explorar falha)
Support: INDUCTIVE (verificar padrões)
6. Reasoning Quality Checks¶
Quality Criteria¶
QUALITY_CRITERIA:
COMPLETENESS:
Description: Todas perspectivas relevantes foram consideradas?
Check:
- Pelo menos 2 agentes consultados
- Protection tier incluído
- Contexto relevante buscado
Score: 0-100%
CONSISTENCY:
Description: Raciocínio é internamente consistente?
Check:
- Não contradiz fatos conhecidos
- Steps seguem logicamente
- Conclusão segue das premissas
Score: 0-100%
SOUNDNESS:
Description: Assumptions são razoáveis?
Check:
- Assumptions explícitas
- Base factual quando possível
- Alternativas consideradas
Score: 0-100%
RELEVANCE:
Description: Análise é relevante para a pergunta?
Check:
- Responde a pergunta original
- Não tangencia demais
- Prioriza o importante
Score: 0-100%
ACTIONABILITY:
Description: Conclusão é acionável?
Check:
- Próximos passos claros
- Responsáveis quando aplicável
- Timeline quando relevante
Score: 0-100%
Quality Score¶
def calculate_reasoning_quality(chain):
"""
Calcula qualidade geral do raciocínio.
"""
scores = {
'completeness': assess_completeness(chain),
'consistency': assess_consistency(chain),
'soundness': assess_soundness(chain),
'relevance': assess_relevance(chain),
'actionability': assess_actionability(chain)
}
# Weighted average
weights = {
'completeness': 0.20,
'consistency': 0.25,
'soundness': 0.25,
'relevance': 0.15,
'actionability': 0.15
}
overall = sum(scores[k] * weights[k] for k in scores)
return QualityScore(
overall=overall,
breakdown=scores,
grade=get_grade(overall) # A/B/C/D/F
)
Quality Display¶
## Qualidade do Raciocínio
**Grade: A (92%)**
| Critério | Score | Nota |
|----------|-------|------|
| Completude | 95% | 4 agentes, contexto completo |
| Consistência | 90% | Alinhado com decisões |
| Solidez | 88% | 1 assumption não verificada |
| Relevância | 95% | Foco na pergunta |
| Acionabilidade | 90% | 3 próximos passos claros |
### Pontos Fortes
- ✅ Múltiplas perspectivas
- ✅ Riscos bem identificados
- ✅ Conclusão clara
### Áreas para Melhorar
- ⚠️ Verificar assumption sobre mercado
7. Debugging Mode¶
Debug Output¶
DEBUG_MODE:
Activation: /reasoning debug on
Shows:
- Full reasoning chain com timings
- Todas assumptions (incluindo hidden)
- Confidence em cada step
- Conflitos internos
- Alternativas consideradas
- Memory consultada
- Patterns aplicados
Format: Técnico, detalhado
Use Cases:
- Entender resposta inesperada
- Identificar gaps no reasoning
- Melhorar sistema
- Auditoria
Debug Template¶
Query: "[Query original]" Timestamp: 2025-12-28T14:30:00Z Session: sess_abc123 Input: "[Query]" Processing: - Tokenization: [tokens] - Intent Detection: DECISION (0.95) - Keywords: [pricing, tier, basic] - Entities: [pricing, tier] Output: Intent(type=DECISION, confidence=0.95) Memory Queries: - Episodic: "pricing decisions" → 3 results - Semantic: "pricing facts" → 5 results - Procedural: "pricing workflow" → 1 match Retrieved: - ep_001: "Decisão pricing Dez/25" - fact_pricing_001: "Basic = R$ 297" - proc_pricing: "Pricing Decision Workflow" Selection Algorithm: - Intent → Default: [CRO, Pre-Mortem] - Keywords → Add: [CFO] - Context → Add: [Focus Guardian] - Check Protection: ✅ Pre-Mortem present - Check Size: 4 <= 5 ✅ Final Squad: - CRO (Lead): Pricing expertise - CFO (Specialist): Financial validation - Pre-Mortem (Validator): Risk assessment - Focus Guardian (Advisor): Priority check Parallel Execution: CRO (400ms): Input: [context + query] Reasoning: "Pricing deve refletir valor..." Output: "Recomendar R$ 297 porque..." Confidence: 0.85CFO (350ms): Input: [context + query] Reasoning: "Margem mínima..." Output: "R$ 297 dá margem de 65%..." Confidence: 0.90
Pre-Mortem (450ms): Input: [context + query] Reasoning: "Cenários de falha..." Output: "Riscos: [churn se muito alto]..." Confidence: 0.80
Focus Guardian (300ms): Input: [context + query] Reasoning: "Prioridade atual..." Output: "Alinhado com Q1 goals ✅" Confidence: 0.95
Consensus Detection: - CRO + CFO: Concordam em R$ 297 ✅ - Pre-Mortem: Alerta sobre churn - Focus: Confirma prioridade Divergences: - None major Synthesis: - Consenso: Manter R$ 297 - Risco: Monitorar churn - Prioridade: Confirmada Recommendation Formation: - Base: Consenso CRO+CFO - Adjusted by: Pre-Mortem warning - Validated by: Focus Guardian Final: - Action: Manter pricing R$ 297 - Confidence: 0.82 - Risks: [churn if too high] - Next: Monitor churn 30 days | # | Assumption | Type | Critical | Verified | |---|------------|------|----------|----------| | 1 | Mercado estável | IMPLICIT | YES | NO | | 2 | Personas corretas | EXPLICIT | NO | YES | Completeness: 95% Consistency: 90% Soundness: 85% (-5% for unverified assumption) Relevance: 95% Actionability: 90% Overall: 91% (A) Total Time: 2350ms Agents Used: 4 Memory Queries: 3 Confidence: 82% Quality: A8. Comandos de Reasoning¶
# Ver reasoning da última resposta
/reasoning show
# Debug mode
/reasoning debug on
/reasoning debug off
# Ver chain específica
/reasoning chain rc_2025-12-28_001
# Ver assumptions
/reasoning assumptions
# Ver confidence breakdown
/reasoning confidence
# Ver quality score
/reasoning quality
# Forçar level de explicação
/reasoning level summary
/reasoning level standard
/reasoning level detailed
/reasoning level expert
# Exportar chain para análise
/reasoning export --format yaml
9. Integração com Sistema APEX¶
APEX_INTEGRATION:
ORCHESTRATOR.md:
- Orchestrator gera reasoning chain
- Cada step é documentado
- Confidence é calculado
MEMORY-SYSTEM.md:
- Reasoning chains são armazenadas
- Assumptions viram conhecimento
- Patterns de reasoning são aprendidos
LEARNING-SYSTEM.md:
- Erros de reasoning alimentam learning
- Patterns de sucesso são reforçados
- Quality scores são trackados
AGENT-INTERFACES.md:
- Cada agente contribui com reasoning
- Outputs seguem formato padrão
- Confidence é por agente
WORKFLOWS.md:
- Workflows geram chains específicas
- Handoffs são parte do reasoning
- Checkpoints são steps
10. Anti-Patterns de Reasoning¶
ANTI_PATTERNS:
CONFIRMATION_BIAS:
Description: Buscar só evidência que confirma
Detection: Só perspectives concordantes
Mitigation: Sempre incluir Contrarian
AUTHORITY_BIAS:
Description: Aceitar porque "agente X disse"
Detection: Baixo reasoning próprio
Mitigation: Exigir justificativa
PREMATURE_CONCLUSION:
Description: Concluir antes de analisar
Detection: Steps de análise muito rápidos
Mitigation: Mínimo de contexto obrigatório
ASSUMPTION_CREEP:
Description: Muitas assumptions implícitas
Detection: Baixo confidence sem explicação
Mitigation: Assumption detection obrigatório
OVERCONFIDENCE:
Description: Confidence alto sem base
Detection: Confidence > 0.9 com pouca evidência
Mitigation: Calibração de confidence
ANALYSIS_PARALYSIS:
Description: Analisar demais, não concluir
Detection: Muitos steps, baixa actionability
Mitigation: Time limits, focus em conclusão
Changelog¶
| Data | Mudança |
|---|---|
| 2025-12-28 | Criação inicial como parte do Sistema APEX Fase 6 |
| 2025-12-29 | Adicionado mapeamento REASONING ↔ ORCHESTRATOR para harmonização |