Documentação Metodológica

1. Escopo e filosofia do aplicativo

Chess Habits é uma ferramenta independente de acompanhamento de padrões enxadrísticos. Ela não foi criada para substituir uma engine nem para afirmar que todo lance diferente da recomendação do computador está errado.

O objetivo é identificar comportamentos recorrentes que ajudam o jogador a construir uma base mais estável. O app trabalha com três camadas complementares:

• Hábitos de Abertura: desenvolvimento, segurança do rei, uso de peões, dama, tempos e trocas.
• Tática / Meio Jogo heurística: riscos materiais simples detectáveis rapidamente no histórico de muitas partidas.
• Stockfish sob demanda: avaliação aprofundada de uma partida específica, com melhores lances, linha principal e precisão estimada própria do app.

2. Fontes de dados e modos de uso

O aplicativo consome partidas públicas do Chess.com e utiliza o PGN, além de informações disponíveis como username, cor, resultado, ritmo, rating do oponente, URL, ECO e horário de encerramento.

2.1. Histórico de partidas

O usuário pode filtrar por período, limite máximo de partidas, ritmo e cor. Para análises recentes, há opções em dias; para histórico maior, opções em meses.

O valor padrão é 100 partidas, com limite máximo configurável de 500 partidas.

2.2. Partida específica

A página de partida específica aceita link público do Chess.com, PGN manual e seleção de uma partida já carregada. Links de análise e revisão são normalizados pelo ID.

• https://www.chess.com/game/live/169485215990?username=usuario&move=0
• https://www.chess.com/game/live/169468938258
• https://www.chess.com/analysis/game/live/169468938258/review
• https://www.chess.com/analysis/game/live/169468938258/analysis?move=74

Quando o link contém ?username=, o aplicativo extrai o username automaticamente. Quando contém apenas o ID, o usuário informa um username para localizar o PGN no histórico mensal.

2.3. Exportação

O relatório histórico e a análise de partida específica podem ser baixados em Markdown e PDF.

3. Visão geral das notas

3.1. Score Geral

Score Geral = 55% x Hábitos de Abertura + 45% x Tática / Meio Jogo

Exemplo: abertura 80 e tática 90 geram score geral 84,5.

4. Hábitos de abertura: fórmula e pesos

Cada sub-score começa em 100. O sistema desconta pontos quando identifica desvios e calcula uma média ponderada.

Abertura = 0,28D + 0,22R + 0,17P + 0,13Q + 0,12T + 0,08C

Depois da média ponderada, problemas graves podem impor tetos. O app conta no máximo uma categoria grave de cada tipo para evitar punições duplicadas pelo mesmo problema central.

5. Regras detalhadas da abertura

5.1. Desenvolvimento das peças

5.2. Bispo antes dos cavalos

É uma preferência didática, não uma regra universal de teoria. Nunca vira erro grave isoladamente.

5.3. Segurança do rei

5.4. Disciplina de peões

5.5. Dama cedo

5.6. Trocas precoces

5.7. Perda de tempo

5.8. Bônus por execução limpa

O app concede +2 em Desenvolvimento e +2 em Segurança do Rei quando o jogador fez roque, desenvolveu pelo menos 3 peças menores, não moveu a dama, fez no máximo 3 lances de peão cedo e não moveu a mesma peça 3 ou mais vezes.

6. Tetos por categorias graves

Aberturas com problemas graves recebem teto depois da média ponderada. O teto usa categorias graves únicas, não o número bruto de mensagens.

7. Consistência dos hábitos de abertura

O indicador de consistência usa somente Hábitos de Abertura. Ele não inclui Tática / Meio Jogo e não deve ser interpretado como avaliação global.

8. Tática / Meio Jogo heurística

A análise histórica não usa Stockfish. Ela observa riscos materiais simples depois dos lances do jogador e tenta reduzir falsos positivos com legalidade de captura, episódios contínuos e contexto da sequência realmente jogada.

8.1. Valores das peças

O bispo vale 3,1 para diferenciá-lo levemente do cavalo, seguindo a dica do GM Krikor.

8.2. Captura legal e episódios contínuos

O app verifica captura legal, não apenas ataque geométrico. Usa uma cópia temporária do tabuleiro e ajusta corretamente o turno do atacante. A mesma exposição contínua conta uma vez; se a peça ficar segura e depois voltar a ficar exposta, um novo episódio pode ser registrado.

8.3. Tipos de alerta

8.4. Penalidades-base

8.5. Progressão por reincidência

O multiplicador vale somente para perdas materiais prováveis sem compensação. Exposições e vulnerabilidades leves não aumentam a progressão.

Tática / Meio Jogo = max(0, 100 - soma das penalidades ajustadas)

8.6. Nível de risco por partida

9. Indicadores táticos do painel

Leitura conjunta recomendada: frequência mostra quantas partidas têm problema; severidade mostra quanto os problemas custam quando aparecem.

10. Diagnóstico principal, resumo automático e evolução

O app trata Tática / Meio Jogo como principal gargalo quando pelo menos uma condição ocorre:

• nota tática média abaixo de 80;
• nota tática pelo menos 8 pontos pior que Hábitos de Abertura;
• 15% ou mais das partidas com risco tático grave.

10.1. Resumo automático em linguagem natural

O app introduziu um resumo interpretativo gerado localmente por regras. Ele não usa API externa de IA. O texto combina abertura, tática, frequência de alertas, gravidade e evolução.

10.2. Comparação entre períodos

O painel compara as partidas mais recentes com o bloco imediatamente anterior. Quando possível, usa 20 jogos recentes versus 20 jogos anteriores e mostra deltas de Score Geral, Abertura, Tática / Meio Jogo e risco grave.

11. Stockfish na partida específica

Stockfish roda somente sob demanda na página de partida específica. O relatório histórico permanece leve para evitar lentidão em lotes grandes.

11.1. Configuração inicial

11.2. Avaliações exibidas

• avaliação antes e depois;
• perda em centipawns convertida para peões;
• expectativa WDL antes e depois;
• melhor lance sugerido;
• linha principal curta;
• profundidade aproximada;
• imprecisões, erros e blunders.

11.3. Precisão Stockfish Estimada

Perda prática = max(0, expectativa antes - expectativa depois)

Precisão do lance = 100 x exp(-5 x perda prática)

Precisão Stockfish Estimada = média das precisões dos lances x 0,90

A nota é própria e transparente. Ela pode diferir do Chess.com porque as metodologias não são idênticas. O Chess.com informa que seu modelo de pontos esperados considera avaliação da engine e rating do jogador; este app usa Stockfish local e perda de expectativa WDL para comparação interna.

11.4. Classificação por perda WDL

Mate permitido ou desperdiçado recebe tratamento específico como blunder.

12. Controles técnicos da versão 7.2.2b

12.1. Revalidação efetiva do mês atual

A função interna de requisição não usa mais cache diretamente. O cache permanece apenas para dados históricos estáveis. A consulta do mês atual efetivamente realiza nova requisição e pede revalidação, reduzindo atraso causado pelo próprio app.

12.2. Limite de concorrência do Stockfish

O servidor permite no máximo uma análise Stockfish simultânea por instância. Isso protege CPU e memória em hosts pequenos. Outros usuários podem continuar navegando e usando o relatório histórico.

12.3. Arquitetura modular

A partir da versão 7.2.0, a aplicação foi reorganizada em módulos próprios para configurações, API do Chess.com, hábitos de abertura, Tática / Meio Jogo, Stockfish, relatórios, notificações e interface. Essa separação facilita manutenção e testes sem alterar as fórmulas enxadrísticas.

12.4. Robustez operacional

O app usa retry leve para falhas temporárias da API, reutiliza conexões HTTP, limita caches em memória e registra duração, quantidade de partidas, retries e métricas de Stockfish nos logs.

12.5. Filtros mensais como janelas móveis

Os filtros mensais funcionam como janelas móveis aproximadas de 30 dias por mês e carregam um arquivo mensal adicional antes do corte por timestamp. Isso evita inconsistências em viradas de calendário.

12.6. Logs de produção e privacidade

Em produção, o nível INFO mantém mensagens consolidadas. A análise de partida específica registra a origem da consulta, o identificador da partida quando disponível, a quantidade aproximada de lances completos e a duração. O Stockfish registra início, conclusão, indisponibilidade temporária e falhas. O aplicativo não grava PGN completo, FEN ou linha principal nos logs.

12.7. Notificações operacionais

A partir da versão 7.2.2, o aplicativo envia notificações operacionais após ações manuais relevantes: análise histórica por username, análise de partida específica e execução do Stockfish. Erros inesperados também podem gerar notificação. O envio utiliza ntfy, possui deduplicação contra reruns imediatos e duplo clique, e falhas de notificação não interrompem a aplicação.

12.8. Empacotamento e testes

A base modular inclui Dockerfile para desenvolvimento local e DigitalOcean App Platform, além de testes básicos para janela mensal móvel, validação de username e cálculo combinado.

12.9. Identidade independente

O produto se chama Chess Habits. Chess.com aparece apenas como fonte das partidas públicas importadas. O projeto não possui vínculo oficial com Chess.com, Chessbrah ou Aman Hambleton.

13. Limitações e interpretação responsável

A análise histórica é intencionalmente simples. Mesmo na versão atual, existem situações que exigem revisão humana ou Stockfish:

• sacrifícios corretos;
• defesas indiretas por tática;
• compensação posicional;
• sequências forçadas maiores do que a janela observada;
• posições caóticas de bullet;
• combinações de mate;
• lances teóricos que quebram hábitos didáticos por motivo válido.

O relatório deve ser usado como detector de padrões. Uma única partida não define o jogador.

14. Histórico resumido de alterações

15. Resumo de bolso

• Score Geral: 55% abertura + 45% Tática / Meio Jogo.
• Abertura: desenvolvimento, segurança do rei, disciplina de peões, dama cedo, perda de tempo e trocas precoces.
• Tática histórica: captura legal, episódios contínuos, sequência jogada, perdas prováveis, exposições, compensações e riscos por peças menores.
• Stockfish: somente na partida específica, sob demanda, com WDL e precisão estimada calibrada em 90% da média dos lances.
• Infraestrutura inicial recomendada: 1 thread, Hash 32 MB e uma análise Stockfish simultânea por instância.
• Operação: arquitetura modular, logs consolidados sem PGN completo ou FEN e notificações ntfy que não interrompem a aplicação em caso de falha.