mapeamento-semantico-de-progresso-textual-local
Rastreia conclusao de metas narrativas pela analise semantica do texto digitado, atualizando o Kanban de forma silenciosa.
SKILL.md.agents/skills/mapeamento-semantico-de-progresso-textual-local/SKILL.md
GitHubmapeamento-semantico-de-progresso-textual-local
Descrição
A skill mapeamento-semantico-de-progresso-textual-local rastreia automaticamente a conclusão de metas narrativas (cartões de tarefa Kanban) pela análise semântica local do texto livre digitado pelo autor no editor. Ela compara embeddings do parágrafo recém-digitado com os vetores das metas pendentes da cena ativa e usa um LLM local para confirmar a ação concreta, atualizando o status do Kanban de forma silenciosa sem interromper o fluxo de escrita.
Quando usar
Gatilhos concretos e observáveis:
- O autor digita uma quebra de parágrafo no editor e o sistema processa o texto gerado em background.
- O escritor muda o cartão Kanban de "A Escrever" para "Escrevendo" manualmente na UI.
- O sistema de gestão de outline detecta que novas cenas foram adicionadas ao banco de dados.
Quando NÃO usar:
- Em textos de notas de brainstorming ou rascunhos marcados como
is_draft = true(devem ser excluídos da análise). - Durante processamentos em tempo real tecla-a-tecla (deve rodar exclusivamente em background debounced).
Pré-requisitos
- Banco de dados vetorial local (SQLite-VSS) com os embeddings das metas ativas da cena.
- Modelo de embeddings local (
multilingual-e5-base) carregado em memória. - Pequeno modelo de linguagem local instruct-tuned (ex: Phi-3.5-mini) para classificação zero-shot.
Processo (passo a passo executável)
- Indexação das Metas Ativas (GMN Embeddings):
- Para cada meta do GMN com status
Em andamentona cena atual, computar e armazenar o embedding da descrição da meta no banco vetorial local.
- Para cada meta do GMN com status
- Vetorização do Parágrafo Digitado:
- Ao término da digitação de um parágrafo (identificado por quebra de parágrafo
\n\nou ponto seguido de quebra), capturar o texto do parágrafo. - Executar o embedding do parágrafo usando o modelo local em background.
- Ao término da digitação de um parágrafo (identificado por quebra de parágrafo
- Filtragem por Similaridade de Cosseno:
- Comparar o vetor do parágrafo com os vetores de cada meta pendente da cena ativa.
- Se a distância de cosseno entre o parágrafo e alguma meta superar o limiar
SEMANTIC_MATCH_THRESHOLD = 0.82, eleger essa meta como candidata à conclusão.
- Validação por Classificação Zero-Shot (LLM Local):
- Para cada meta candidata identificada na etapa 3, construir um prompt de verificação:
Meta: "Kael apresenta a chave de ferro ao ferreiro." Parágrafo: "Kael retirou a pequena chave enferrujada do bolso e a estendeu para Mestre Morgan." Pergunta: Esta meta foi concretamente executada no parágrafo? Responda APENAS com SIM ou NÃO. - Executar a inferência no modelo local e verificar a resposta.
- Para cada meta candidata identificada na etapa 3, construir um prompt de verificação:
- Atualização Automática do Kanban:
- Se o LLM responder
SIM:- Atualizar o status do cartão correspondente no banco de dados para
Concluído. - Criar um hyperlink de citação associando o cartão à linha e parágrafo exatos no manuscrito.
- Exibir um badge verde discreto no cartão Kanban na sidebar sem exibir pop-ups ou alertas.
- Atualizar o status do cartão correspondente no banco de dados para
- Se o LLM responder
Parâmetros e configuração
SEMANTIC_MATCH_THRESHOLD: Limiar de similaridade de cosseno para candidatura de meta à conclusão. Padrão:0.82.KANBAN_UPDATE_DEBOUNCE_MS: Tempo de debounce após quebra de parágrafo para disparar análise semântica. Padrão:2000(2 segundos).MAX_GOALS_PER_SCENE: Número máximo de metas ativas simultaneamente por cena. Padrão:5.
Armadilhas e como evitá-las
- Armadilha: Falsos Positivos por Discussão Passiva: um personagem menciona verbalmente que pretende realizar uma ação futura ("Temos que encontrar a chave"), gerando alta similaridade semântica com a meta "Apresentar a chave", mas sem concretizar a ação na cena. Mitigação: A etapa de filtragem por cosseno é apenas triagem. A validação final via prompt zero-shot do LLM local é mandatória antes de marcar qualquer meta como concluída. O prompt deve perguntar explicitamente se a ação foi concretamente executada na cena, não apenas mencionada ou planejada (Narrative Goal Tracking, 2025).
Critérios de validação (Definition of Done)
- A acurácia geral de detecção automática de conclusão de metas validadas (sem falsos positivos de discussão passiva) é de pelo menos 85% no dataset de validação de cenas literárias.
- A análise semântica e o update do Kanban não causam nenhum frame drop no editor durante digitação ativa.
Fundamentação científica
- Plot Event Extraction (2025) - Plot Event Extraction for Narrative Progress Tracking - arXiv 2025
- Narrative Goal Tracking (2025) - Automatic Tracking of Narrative Goals from Text Using LLMs - arXiv 2025
- Event-Centric Story Generation (2024) - Event-Centric Story Generation and Progress Detection - arXiv 2024
Requisitos do projeto relacionados
- RF-108 (atualizar wiki)
- RF-194 (quadro de progresso)
Maturidade e riscos de adoção
Nível: Emergente. Risco: O passo de validação por LLM local adiciona latência de 0.5 a 1 segundo por parágrafo, que pode ser percebida em máquinas com CPU lenta. Fallback para v1: Desativar a validação por LLM. Usar somente o threshold de cosseno para sugerir ao autor a marcação da tarefa como concluída, exibindo uma pergunta discreta na sidebar: "Você completou esta meta: [nome]? [Sim / Não]".
Exemplos
Entrada (Parágrafo e Meta ativa):
- Meta ativa: "Kael apresenta a chave secreta ao ferreiro."
- Parágrafo: "Kael tirou a chave do bolso e a colocou nas mãos do velho ferreiro sem dizer uma palavra." Saída esperada (Atualização automática do Kanban):
{
"goal_id": "goal_kael_chave_ferreiro",
"status_updated_to": "Concluído",
"source_paragraph_ref": "cap03_par14",
"hyperlink_created": true
}
Caso de falha conhecido: Marcar "Kael entrega a chave" como concluída quando o parágrafo diz apenas "Kael não encontrou a chave por nenhum lado".