LEARNING-SYSTEM.md - Sistema de Aprendizado Contínuo¶
Feedback loops, pattern recognition e melhoria contínua dos agentes.
Visão Geral¶
O Sistema de Aprendizado permite que os agentes:
1. Coletem feedback de outcomes
2. Identifiquem padrões de sucesso/falha
3. Ajustem comportamento baseado em resultados
4. Melhorem continuamente suas recomendações
O objetivo é criar um sistema que fica MELHOR com o tempo,
não apenas repete os mesmos erros.
Arquitetura de Aprendizado¶
┌─────────────────────────────────────────────────────────────────┐
│ LEARNING SYSTEM │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ FEEDBACK LOOP │ │
│ │ │ │
│ │ Action → Outcome → Feedback → Learn → Adjust → Action │ │
│ │ ↑ │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ PATTERN │ │ OUTCOME │ │ BEHAVIOR │ │
│ │ DETECTOR │ │ TRACKER │ │ ADJUSTER │ │
│ │ │ │ │ │ │ │
│ │ Identifica │ │ Monitora │ │ Modifica │ │
│ │ padrões │ │ resultados │ │ comportamento │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ INSIGHT GENERATOR │ │
│ │ │ │
│ │ Transforma dados em conhecimento acionável │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
1. Feedback Loop¶
Ciclo Completo¶
FEEDBACK_CYCLE:
1. ACTION:
Description: Agentes fazem recomendação
Data Captured:
- Query original
- Squad utilizado
- Contexto analisado
- Recomendação dada
- Confiança da recomendação
- Riscos identificados
2. OUTCOME:
Description: Resultado da ação é observado
Data Captured:
- Usuário aceitou/rejeitou/modificou?
- Se implementado, qual foi o resultado?
- Quanto tempo levou?
- Houve problemas não previstos?
3. FEEDBACK:
Description: Feedback explícito ou implícito
Sources:
- Feedback direto do usuário
- Métricas objetivas (MCP: getMetrics)
- Hipóteses validadas/invalidadas
- Comportamento observado
4. LEARN:
Description: Extrair lições do feedback
Process:
- Comparar previsão vs realidade
- Identificar gaps no reasoning
- Detectar padrões de erro
- Formular hipóteses de melhoria
5. ADJUST:
Description: Modificar comportamento futuro
Changes:
- Atualizar weights de agentes
- Modificar heurísticas
- Refinar squad composition
- Adicionar checkpoints
6. REPEAT:
Description: Aplicar ajustes na próxima ação
Validation:
- Monitorar se melhoria acontece
- A/B test quando possível
- Rollback se piorar
Feedback Types¶
FEEDBACK_TYPES:
EXPLICIT:
Description: Usuário diz diretamente
Examples:
- "Boa recomendação, vou seguir"
- "Não concordo, vou fazer diferente"
- "Faltou considerar X"
- "A análise estava errada"
Weight: HIGH (mais confiável)
IMPLICIT_BEHAVIORAL:
Description: Inferido do comportamento
Examples:
- Usuário implementou recomendação
- Usuário ignorou recomendação
- Usuário pediu mais detalhes
- Usuário fez pergunta de follow-up
Weight: MEDIUM
IMPLICIT_OUTCOME:
Description: Inferido de resultados
Examples:
- Métrica melhorou após ação
- Problema previsto aconteceu
- Risco não previsto materializou
- Hipótese foi validada/invalidada
Weight: HIGH (objetivo)
TEMPORAL:
Description: Feedback ao longo do tempo
Examples:
- Decisão ainda faz sentido 3 meses depois?
- Previsão se confirmou?
- Contexto mudou?
Weight: MEDIUM
2. Outcome Tracker¶
Outcome Schema¶
OUTCOME_SCHEMA:
id: "out_2025-12-28_001"
related_episode: "ep_2025-12-28_001"
timestamp: "2025-12-28T18:00:00Z"
original_action:
recommendation: "[O que foi recomendado]"
confidence: 0.85
squad: ["CRO", "CFO", "Pre-Mortem"]
risks_identified: ["Risco A", "Risco B"]
user_response:
accepted: true | false | "modified"
modifications: "[Se modificou, o que mudou]"
reasoning: "[Por que aceitou/rejeitou]"
implementation:
was_implemented: true | false
implementation_date: "2025-12-29"
deviations: "[Diferenças da recomendação]"
results:
status: "success" | "partial" | "failure" | "pending"
metrics_impact:
- metric: "conversion_rate"
before: 0.15
after: 0.18
delta: "+20%"
unexpected_outcomes: ["Lista de surpresas"]
risks_materialized: ["Riscos que aconteceram"]
risks_avoided: ["Riscos que não aconteceram"]
learning:
what_worked: "[O que funcionou]"
what_failed: "[O que não funcionou]"
what_was_missing: "[O que faltou considerar]"
hypothesis_generated: "HYP-XXX"
Tracking Timeline¶
TRACKING_TIMELINE:
T+0 (Immediate):
Track:
- User response (accepted/rejected/modified)
- Initial feedback
Method: Observação direta
T+1 day:
Track:
- Was it implemented?
- Any immediate issues?
Method: Follow-up ou observação
T+1 week:
Track:
- Short-term results
- Early metrics
- Problems encountered
Method: getMetrics, observação
T+1 month:
Track:
- Medium-term results
- Metrics stability
- Unexpected effects
Method: Checkpoint review
T+1 quarter:
Track:
- Long-term results
- Strategic impact
- Decision still correct?
Method: Quarterly review
3. Pattern Detector¶
Tipos de Padrões¶
PATTERN_TYPES:
SUCCESS_PATTERNS:
Description: O que correlaciona com bons resultados
Examples:
- "Squad com Pre-Mortem tem 25% menos surpresas"
- "Decisões Type 2 com teste primeiro têm 80% sucesso"
- "Recomendações do CRO + CFO juntos são 90% aceitas"
FAILURE_PATTERNS:
Description: O que correlaciona com maus resultados
Examples:
- "Decisões urgentes sem Focus Guardian falham 40%"
- "Features sem CPO review têm 60% mais bugs"
- "Pricing sem CFO tem margem errada 50% das vezes"
CONTEXT_PATTERNS:
Description: Quando certas abordagens funcionam
Examples:
- "Alta urgência → squad menor é melhor"
- "Decisão Type 1 → mais agentes necessários"
- "Burnout detectado → só Founder Coach funciona"
AGENT_PATTERNS:
Description: Como agentes específicos performam
Examples:
- "CMO melhor para awareness, Growth para conversão"
- "Pre-Mortem identifica 80% dos riscos reais"
- "Contrarian evita 30% das más decisões"
Pattern Detection Algorithm¶
def detect_patterns(outcomes, min_occurrences=5, min_confidence=0.7):
"""
Detecta padrões nos outcomes.
Args:
outcomes: Lista de outcomes
min_occurrences: Mínimo de exemplos para padrão
min_confidence: Mínima correlação para reportar
Returns:
patterns: Lista de padrões detectados
"""
patterns = []
# 1. Group outcomes by success/failure
successes = [o for o in outcomes if o.status == "success"]
failures = [o for o in outcomes if o.status == "failure"]
# 2. Find common factors in successes
success_factors = extract_common_factors(successes)
for factor, frequency in success_factors.items():
if frequency >= min_occurrences:
# Calculate if factor correlates with success
correlation = calculate_correlation(factor, "success", outcomes)
if correlation >= min_confidence:
patterns.append(Pattern(
type="SUCCESS",
factor=factor,
correlation=correlation,
occurrences=frequency
))
# 3. Find common factors in failures
failure_factors = extract_common_factors(failures)
for factor, frequency in failure_factors.items():
if frequency >= min_occurrences:
correlation = calculate_correlation(factor, "failure", outcomes)
if correlation >= min_confidence:
patterns.append(Pattern(
type="FAILURE",
factor=factor,
correlation=correlation,
occurrences=frequency
))
# 4. Find context-dependent patterns
context_patterns = detect_context_patterns(outcomes)
patterns.extend(context_patterns)
return patterns
Pattern Schema¶
PATTERN_SCHEMA:
id: "pat_001"
type: "SUCCESS" | "FAILURE" | "CONTEXT" | "AGENT"
description: "Descrição do padrão"
condition:
factor: "[Fator que causa o padrão]"
context: "[Quando se aplica]"
correlation:
strength: 0.85 # Quão forte é a correlação
confidence: 0.78 # Quão confiantes estamos
sample_size: 23 # Quantos exemplos
impact:
outcome_change: "+25%" # Impacto no outcome
risk_reduction: "30%" # Redução de risco
action:
recommendation: "[O que fazer com este padrão]"
priority: "HIGH" | "MEDIUM" | "LOW"
validation:
last_validated: "2025-12-28"
still_valid: true
exceptions: ["Lista de exceções conhecidas"]
4. Behavior Adjuster¶
Tipos de Ajuste¶
ADJUSTMENT_TYPES:
WEIGHT_ADJUSTMENT:
Description: Mudar peso de agentes no squad selection
Trigger: Padrão detectado com alta confiança
Example:
- Pattern: "Pre-Mortem melhora outcomes"
- Action: Aumentar prioridade de incluir Pre-Mortem
- Magnitude: +0.1 no weight
HEURISTIC_UPDATE:
Description: Modificar regras de decisão
Trigger: Heurística atual não funciona bem
Example:
- Pattern: "Urgência alta + squad grande = falha"
- Action: Adicionar heurística "urgência > 4 → max 3 agentes"
THRESHOLD_ADJUSTMENT:
Description: Mudar limiares de decisão
Trigger: Muitos falsos positivos/negativos
Example:
- Pattern: "Risco 3 sendo ignorado mas causa problemas"
- Action: Baixar threshold de "precisa Pre-Mortem" de 4 para 3
PROCEDURE_OPTIMIZATION:
Description: Melhorar workflows
Trigger: Steps específicos falham frequentemente
Example:
- Pattern: "Step 3 do pricing workflow falha 40%"
- Action: Adicionar checkpoint, melhorar inputs
TEMPLATE_REFINEMENT:
Description: Melhorar templates de output
Trigger: Outputs não são acionáveis
Example:
- Pattern: "Usuários pedem mais detalhes sobre riscos"
- Action: Expandir seção de riscos no template
Adjustment Protocol¶
ADJUSTMENT_PROTOCOL:
1. DETECT:
- Padrão identificado pelo Pattern Detector
- Confidence >= 0.7
- Sample size >= 5
2. PROPOSE:
- Formular ajuste específico
- Calcular impacto esperado
- Identificar riscos do ajuste
3. VALIDATE:
- Checar se ajuste faz sentido lógico
- Verificar se não conflita com outros ajustes
- Simular em casos passados
4. TEST:
- Aplicar em subset de casos (A/B)
- Monitorar resultados
- Comparar com baseline
5. DEPLOY:
- Se teste positivo, aplicar globalmente
- Documentar mudança
- Monitorar por 1 semana
6. MONITOR:
- Verificar se melhoria se mantém
- Detectar efeitos colaterais
- Preparar rollback se necessário
5. Insight Generator¶
Tipos de Insights¶
INSIGHT_TYPES:
PERFORMANCE_INSIGHTS:
Description: Como o sistema está performando
Examples:
- "Taxa de aceitação de recomendações: 78%"
- "Outcomes positivos: 65%"
- "Riscos previstos corretamente: 82%"
AGENT_INSIGHTS:
Description: Como agentes individuais performam
Examples:
- "CRO tem 90% de aceitação em pricing"
- "Pre-Mortem previu 8 de 10 problemas"
- "Focus Guardian reduziu scope creep em 40%"
PATTERN_INSIGHTS:
Description: Padrões descobertos
Examples:
- "Decisões tomadas segunda-feira têm 20% mais sucesso"
- "Squad de 4 agentes é optimal para decisões Type 1"
- "Consultar Contrarian evita 30% das más decisões"
IMPROVEMENT_INSIGHTS:
Description: Onde melhorar
Examples:
- "20% das falhas são por falta de contexto financeiro"
- "Riscos de timing são subestimados"
- "Falta considerar dependencies em 15% dos casos"
TREND_INSIGHTS:
Description: Como performance muda ao longo do tempo
Examples:
- "Taxa de sucesso subindo 2% por mês"
- "Tempo de resposta caindo 10% por semana"
- "Confiança do usuário aumentando"
Insight Generation¶
def generate_insights(outcomes, patterns, period="last_30_days"):
"""
Gera insights acionáveis dos dados.
"""
insights = []
# 1. Performance insights
metrics = calculate_performance_metrics(outcomes, period)
insights.append(Insight(
type="PERFORMANCE",
title="Performance Summary",
content=format_performance(metrics),
actionable=True if metrics.issues else False
))
# 2. Agent insights
agent_performance = calculate_agent_performance(outcomes, period)
for agent, perf in agent_performance.items():
if perf.notable:
insights.append(Insight(
type="AGENT",
title=f"{agent} Performance",
content=format_agent_perf(perf),
actionable=perf.needs_attention
))
# 3. Pattern insights (new patterns)
new_patterns = [p for p in patterns if p.discovered_date >= period_start]
for pattern in new_patterns:
insights.append(Insight(
type="PATTERN",
title=f"New Pattern: {pattern.description[:50]}",
content=format_pattern(pattern),
actionable=True
))
# 4. Improvement insights
failures = [o for o in outcomes if o.status == "failure"]
failure_analysis = analyze_failures(failures)
for gap in failure_analysis.gaps:
insights.append(Insight(
type="IMPROVEMENT",
title=f"Improvement Opportunity: {gap.area}",
content=format_gap(gap),
actionable=True
))
# 5. Trend insights
trends = calculate_trends(outcomes)
for trend in trends:
if trend.significant:
insights.append(Insight(
type="TREND",
title=f"Trend: {trend.direction} {trend.metric}",
content=format_trend(trend),
actionable=trend.needs_action
))
return insights
6. Learning Loops¶
Loop 1: Immediate Learning¶
IMMEDIATE_LOOP:
Trigger: Cada interação
Latency: Segundos
What Learns:
- Este contexto específico
- Esta combinação de agentes
- Esta resposta específica
How:
1. Registrar episódio
2. Capturar feedback imediato
3. Ajustar próxima resposta se necessário
Example:
- Usuário: "Faltou considerar X"
- Learning: Para este contexto, incluir X
- Application: Próxima resposta similar incluirá X
Loop 2: Session Learning¶
SESSION_LOOP:
Trigger: Fim de sessão
Latency: Minutos/Horas
What Learns:
- Padrões da sessão
- Preferências do usuário
- Contexto geral
How:
1. Consolidar episódios da sessão
2. Identificar temas recorrentes
3. Ajustar para próxima sessão
Example:
- Observação: Usuário preferiu respostas curtas
- Learning: Este usuário prefere concisão
- Application: Próxima sessão será mais concisa
Loop 3: Weekly Learning¶
WEEKLY_LOOP:
Trigger: Fim de semana (checkpoint)
Latency: Dias
What Learns:
- Outcomes de decisões
- Padrões de sucesso/falha
- Tendências
How:
1. Revisar outcomes da semana
2. Detectar padrões
3. Propor ajustes
4. Aplicar na próxima semana
Example:
- Observação: 3 decisões de pricing falharam
- Pattern: Todas não tinham CFO
- Adjustment: Incluir CFO em pricing decisions
Loop 4: Monthly Learning¶
MONTHLY_LOOP:
Trigger: Fim de mês
Latency: Semanas
What Learns:
- Performance de agentes
- Eficácia de workflows
- Padrões de longo prazo
How:
1. Análise estatística de outcomes
2. Comparar com baseline
3. Identificar melhorias significativas
4. Documentar learnings
Example:
- Observação: Success rate subiu de 60% para 75%
- Attribution: Mudança no squad selection
- Action: Confirmar mudança como permanente
Loop 5: Quarterly Learning¶
QUARTERLY_LOOP:
Trigger: Fim de quarter
Latency: Meses
What Learns:
- Estratégia geral
- Grandes padrões
- System-wide improvements
How:
1. Review de todas métricas
2. Retrospectiva de decisões importantes
3. Atualizar documentação
4. Planejar melhorias estruturais
Example:
- Observação: Protection tier tem ROI comprovado
- Learning: Investir mais em risk assessment
- Action: Expandir capacidades do Pre-Mortem
7. Hypothesis System¶
Integração com MCP¶
HYPOTHESIS_INTEGRATION:
GENERATION:
When: Padrão detectado ou gap identificado
Action: addLearning(hypothesis)
Output: HYP-XXX criada
TRACKING:
When: Periodicamente
Action: getHypotheses(pending)
Output: Lista de hipóteses a testar
VALIDATION:
When: Dados suficientes coletados
Action: Analisar outcomes relacionados
Output: validated | invalidated
DOCUMENTATION:
When: Hipótese validada/invalidada
Action: Atualizar DOCS/operations/learnings/
Output: Learning documentado
Hypothesis Schema¶
HYPOTHESIS_SCHEMA:
id: "HYP-XXX"
status: "pending" | "validated" | "invalidated"
statement: "Se [condição], então [resultado]"
origin:
type: "pattern" | "failure_analysis" | "user_feedback"
source: "[De onde veio]"
date: "2025-12-28"
test_design:
method: "Como testar"
success_criteria: "O que significa validar"
sample_needed: 10
timeline: "2 weeks"
evidence:
supporting: ["Evidência a favor"]
contradicting: ["Evidência contra"]
sample_size: 8
conclusion:
result: "validated" | "invalidated" | null
confidence: 0.85
date: "2025-12-28"
implications: "[O que isso significa]"
8. Continuous Improvement Metrics¶
System Metrics¶
SYSTEM_METRICS:
ACCURACY:
recommendation_acceptance_rate:
Definition: % de recomendações aceitas pelo usuário
Target: >= 80%
Current: [tracking]
outcome_success_rate:
Definition: % de outcomes positivos
Target: >= 70%
Current: [tracking]
risk_prediction_accuracy:
Definition: % de riscos previstos que ocorreram
Target: >= 75%
Current: [tracking]
EFFICIENCY:
avg_response_time:
Definition: Tempo médio de resposta
Target: < 30s
Current: [tracking]
squad_efficiency:
Definition: Outcomes / Agentes usados
Target: Melhorar 5% por mês
Current: [tracking]
LEARNING:
patterns_discovered:
Definition: Novos padrões por mês
Target: >= 3
Current: [tracking]
hypotheses_validated:
Definition: Hipóteses validadas por mês
Target: >= 2
Current: [tracking]
improvement_rate:
Definition: Taxa de melhoria em métricas core
Target: >= 2% por mês
Current: [tracking]
Learning Dashboard¶
LEARNING_DASHBOARD:
This Week:
outcomes_tracked: [number]
new_patterns: [list]
hypotheses_tested: [list]
adjustments_made: [list]
This Month:
success_rate_trend: [chart]
top_performing_agents: [list]
areas_for_improvement: [list]
key_learnings: [list]
This Quarter:
major_patterns: [list]
system_improvements: [list]
accuracy_evolution: [chart]
next_quarter_priorities: [list]
9. Comandos de Learning¶
# Ver status do learning system
/learn status
# Ver padrões detectados
/learn patterns
/learn patterns --type success
/learn patterns --type failure
# Ver outcomes recentes
/learn outcomes --last 10
/learn outcomes --status failure
# Ver insights
/learn insights
/learn insights --period weekly
# Forçar análise
/learn analyze
# Ver hipóteses
/learn hypotheses --status pending
# Ver métricas de learning
/learn metrics
# Debug mode
/learn debug on
10. Integração com Sistema APEX¶
APEX_INTEGRATION:
MEMORY-SYSTEM.md:
- Learning alimenta memória episódica
- Patterns viram conhecimento semântico
- Adjustments viram procedural
ORCHESTRATOR.md:
- Orchestrator consulta patterns
- Squad selection usa weights ajustados
- Heurísticas são atualizadas pelo learning
AGENT-INTERFACES.md:
- Performance de cada agente é trackada
- Interfaces podem ser ajustadas baseado em feedback
WORKFLOWS.md:
- Workflows são otimizados baseado em outcomes
- Novos workflows emergem de patterns
REASONING-FRAMEWORK.md:
- Learning informa reasoning
- Confidence calibration usa outcomes
Changelog¶
| Data | Mudança |
|---|---|
| 2025-12-28 | Criação inicial como parte do Sistema APEX Fase 5 |