tradermonty/signal-postmortem

Signal Postmortem

Visão Geral

Signal Postmortem registra e analisa os resultados de sinais de trading gerados pelo pipeline edge, screeners e outras habilidades. Ele compara a direção prevista contra os retornos realizados em 5 e 20 dias, categoriza os resultados (verdadeiro positivo, falso positivo, oportunidade perdida, incompatibilidade de regime) e gera feedback para ajustes de peso no edge-signal-aggregator e entradas no backlog de melhoria de habilidades.

Quando Usar

• Após o fechamento de uma operação e você deseja registrar o resultado
• Ao revisar um lote de sinais que atingiram seu período de manutenção (5 ou 20 dias)
• Para identificar padrões sistemáticos de falsos positivos de habilidades específicas
• Para gerar feedback para calibragem de pesos do edge-signal-aggregator
• Ao construir um backlog de melhoria de habilidades a partir de métricas de qualidade de decisão
• Para auditorias periódicas (semanais/mensais) de qualidade de sinais

Pré-requisitos

• Python 3.9+
• Chave da API FMP (opcional, para buscar retornos realizados se não fornecidos manualmente)
• Biblioteca padrão + requests para chamadas de API
• Entrada: registros de sinais em formato JSON (saídas do edge-signal-aggregator ou screeners)

Configuração da Chave da API (Opcional)

Se você deseja buscar automaticamente dados de preços para cálculos de retorno, configure a chave da API FMP:

export FMP_API_KEY=sua_chave_api_aqui

Alternativamente, passe a chave via linha de comando com --api-key SUA_CHAVE. Sem uma chave de API, você ainda pode registrar resultados manualmente fornecendo --exit-price e --exit-date.

Fluxo de Trabalho

Passo 1: Preparar Registros de Sinais

Reúna registros de sinais fechados ou maduros. Cada registro deve incluir:

• signal_id: Identificador único
• ticker: Símbolo da ação
• signal_date: Data em que o sinal foi gerado
• predicted_direction: LONGO ou CURTO
• source_skill: Qual habilidade gerou o sinal
• entry_price: Preço na geração do sinal (opcional, para substituição manual)

# Exemplo: Listar sinais prontos para postmortem (5+ dias de idade)
python3 skills/signal-postmortem/scripts/postmortem_recorder.py \
  --list-ready \
  --signals-dir state/signals/ \
  --min-days 5

Passo 2: Registrar Resultados

Execute o gravador de postmortem para buscar retornos realizados e classificar resultados.

python3 skills/signal-postmortem/scripts/postmortem_recorder.py \
  --signals-file state/signals/aggregated_signals_2026-03-10.json \
  --holding-periods 5,20 \
  --output-dir reports/

Para registro manual de resultados (quando os dados de preço já estão disponíveis):

python3 skills/signal-postmortem/scripts/postmortem_recorder.py \
  --signal-id sig_aapl_20260310_abc \
  --exit-price 178.50 \
  --exit-date 2026-03-15 \
  --outcome-notes "Fechado no alvo, +3,2% em 5 dias" \
  --output-dir reports/

Passo 3: Classificar Resultados

O gravador classifica automaticamente cada sinal em uma das quatro categorias:

Categoria	Definição
TRUE_POSITIVE	A direção prevista coincidiu com o sinal do retorno realizado
FALSE_POSITIVE	A direção prevista foi oposta ao retorno realizado
MISSED_OPPORTUNITY	Sinal não aproveitado, mas teria sido lucrativo
REGIME_MISMATCH	Sinal falhou devido a mudança de regime de mercado

As regras de classificação estão documentadas em references/outcome-classification.md.

Passo 4: Gerar Arquivos de Feedback

Gere feedback para consumidores downstream:

# Gerar sugestões de ajuste de peso para o edge-signal-aggregator
python3 skills/signal-postmortem/scripts/postmortem_analyzer.py \
  --postmortems-dir reports/postmortems/ \
  --generate-weight-feedback \
  --output-dir reports/

# Gerar entradas no backlog de melhoria de habilidades
python3 skills/signal-postmortem/scripts/postmortem_analyzer.py \
  --postmortems-dir reports/postmortems/ \
  --generate-improvement-backlog \
  --output-dir reports/

Passo 5: Revisar Estatísticas Resumidas

Gere estatísticas agregadas por habilidade, por ticker e por período de tempo:

python3 skills/signal-postmortem/scripts/postmortem_analyzer.py \
  --postmortems-dir reports/postmortems/ \
  --summary \
  --group-by skill,month \
  --output-dir reports/

Formato de Saída

Registro de Postmortem (JSON)

{
  "schema_version": "1.0",
  "postmortem_id": "pm_sig_aapl_20260310_abc",
  "signal_id": "sig_aapl_20260310_abc",
  "ticker": "AAPL",
  "signal_date": "2026-03-10",
  "source_skill": "edge-signal-aggregator",
  "predicted_direction": "LONG",
  "entry_price": 172.50,
  "realized_returns": {
    "5d": 0.032,
    "20d": 0.058
  },
  "exit_price": 178.50,
  "exit_date": "2026-03-15",
  "holding_days": 5,
  "outcome_category": "TRUE_POSITIVE",
  "regime_at_signal": "RISK_ON",
  "regime_at_exit": "RISK_ON",
  "outcome_notes": "Rompimento limpo, mantido durante pequena correção",
  "recorded_at": "2026-03-17T10:30:00Z"
}

Feedback de Pesos (JSON)

{
  "schema_version": "1.0",
  "generated_at": "2026-03-17T10:35:00Z",
  "analysis_period": {
    "from": "2026-02-01",
    "to": "2026-03-15"
  },
  "skill_adjustments": [
    {
      "skill": "vcp-screener",
      "current_weight": 1.0,
      "suggested_weight": 0.85,
      "reason": "15% de taxa de falso positivo no regime RISK_OFF",
      "sample_size": 42
    }
  ],
  "confidence": "MEDIUM",
  "min_sample_threshold": 20
}

Entrada no Backlog de Melhoria de Habilidades (YAML)

- skill: vcp-screener
  issue_type: false_positive_cluster
  severity: medium
  evidence:
    false_positive_rate: 0.15
    sample_size: 42
    regime_correlation: RISK_OFF
  suggested_action: "Adicionar filtro de regime ou reduzir confiança do sinal em RISK_OFF"
  generated_by: signal-postmortem
  generated_at: "2026-03-17T10:35:00Z"

Relatório Resumido (Markdown)

Os relatórios são salvos em reports/ com nomes de arquivo postmortem_summary_YYYY-MM-DD.md.

Recursos

• scripts/postmortem_recorder.py -- Grava resultados individuais de sinais
• scripts/postmortem_analyzer.py -- Gera feedback e estatísticas resumidas
• references/outcome-classification.md -- Regras de classificação e casos extremos
• references/feedback-integration.md -- Como integrar feedback com habilidades downstream

Princípios Chave

1. Atribuição Honesta -- Cada resultado é atribuído à sua habilidade de origem para responsabilidade
2. Consciência de Regime -- O contexto de regime é registrado para distinguir falha de habilidade de mudanças de regime de mercado
3. Tamanho Mínimo de Amostra -- Ajustes de peso exigem 20+ sinais para validade estatística
4. Fechamento do Ciclo de Feedback -- Os resultados fluem de volta para melhorar tanto a agregação de sinais quanto a qualidade das habilidades