Gerar Quiz Rag

---
name: gerar-quiz-rag
description: "Gerador e executor de quiz sobre conhecimento RAG. Comandos: '/gerar-quiz-rag gerar' para gerar perguntas do banco RAG e salvar em JSON, '/gerar-quiz-rag iniciar' para executar quiz de 10 perguntas, '/gerar-quiz-rag status' para ver progresso. Claude consulta o banco SQLite RAG e gera perguntas diretamente."
---

# Quiz RAG - Skill do Claude Code

## ⚠️ IMPORTANTE: Nome Completo Qualificado

Ao invocar este skill via **Skill tool** (não via comando do usuário), você DEVE usar o **nome completo qualificado**:

```
✅ CORRETO: skill: "gerar-quiz-rag:gerar-quiz-rag"
❌ ERRADO:  skill: "gerar-quiz-rag"
```

**Por quê?**
- O nome curto `gerar-quiz-rag` pode causar erro: `Unknown skill: gerar-quiz-rag`
- O sistema requer o formato completo: `<namespace>:<skill-name>`
- Para este skill: `gerar-quiz-rag:gerar-quiz-rag`

**Quando usar:**
- Quando Claude invoca o skill programaticamente via Skill tool
- Quando há necessidade de desambiguação entre skills com nomes similares

**Comandos do usuário (continuam funcionando normalmente):**
- `/gerar-quiz-rag gerar 30` ✅
- `/gerar-quiz-rag iniciar` ✅
- `/gerar-quiz-rag status` ✅

---

## Visão Geral

Esta skill permite ao Claude:
1. **Gerar perguntas** consultando o banco de dados RAG (SQLite) e salvando em JSON
2. **Executar quizzes** de 10 perguntas com feedback imediato
3. **Gerenciar banco** de perguntas em formato JSON puro

**IMPORTANTE:** Claude gera as perguntas consultando o banco RAG SQLite diretamente.

## Comandos da Skill

### `/gerar-quiz-rag gerar [quantidade]`
Gera perguntas consultando o banco RAG e salva no JSON.

**MÉTODO PADRÃO: SUBAGENTS EM PARALELO** ⚡

**IMPORTANTE: SEMPRE usar subagents para máxima velocidade e qualidade!**

Exemplos:
- `/gerar-quiz-rag gerar` → 10 perguntas (1 subagent)
- `/gerar-quiz-rag gerar 50` → 50 perguntas (5 subagents paralelos)
- `/gerar-quiz-rag gerar 100` → 100 perguntas (10 subagents paralelos)
- `/gerar-quiz-rag gerar 200` → 200 perguntas (20 subagents paralelos) ⚡
- `/gerar-quiz-rag gerar completo` → Máximo possível (~250 perguntas, 25 subagents)

**Processo com Subagents (PADRÃO):**
1. **CRIAR PASTA** (se não existir): `mkdir -p temp-lotes/`
2. Calcular número de lotes: `quantidade / 10` (10 perguntas por lote)
3. Distribuir chunks entre lotes (59 chunks / N lotes)
4. Lançar N subagents EM PARALELO usando `Task` tool
5. Cada subagent:
   a. Consulta SQLite: `regulamento.db` chunks específicos
   b. Gera 10 perguntas REAIS do conteúdo
   c. ⚠️ **CRÍTICO**: Salva em `/Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/temp-lote-N.json`
      - ❌ NUNCA salvar na raiz da skill!
      - ✅ SEMPRE em temp-lotes/temp-lote-N.json
6. Aguardar todos os subagents concluírem (~1-2 minutos)
7. Executar `python3 coletar-e-merge-final.py` para merge automático
8. Resultado em `banco-perguntas.json` (validado, sem duplicatas)
9. Limpar `temp-lotes/` (opcional)

### `/gerar-quiz-rag iniciar [modo]`
Executa quiz de 10 perguntas.

**Modos:**
- `novo` - Gera 10 perguntas novas do banco RAG
- `aleatorio` - Sorteia 10 do banco JSON existente
- `teste` - Modo teste com respostas marcadas (⭐)

### `/gerar-quiz-rag status`
Mostra progresso atual do banco de perguntas.

## Banco de Perguntas (JSON Local)

As perguntas são armazenadas em arquivo JSON local na própria skill.

### Arquivo Principal
- **Localização**: `/Users/2a/.claude/skills/gerar-quiz-rag/banco-perguntas.json`
- **Formato**: JSON estruturado com metadata e array de perguntas
- **Gerenciado por**: Claude diretamente (lê e escreve via ferramentas Read/Write)

### Arquivos Temporários
- **Localização**: `/Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/`
- **Arquivos**: `temp-lote-1.json`, `temp-lote-2.json`, etc.
- **Uso**: Lotes individuais quando gerado com subagents paralelos
- **Limpeza**: Podem ser apagados após merge em `banco-perguntas.json`

### Schema do JSON (OBRIGATÓRIO)

**CAMPOS PERMITIDOS (apenas estes):**

```json
{
  "metadata": {
    "total_perguntas": 10,
    "ultima_atualizacao": "2026-01-04T20:00:00.000000",
    "fonte": "regulamento.db"
  },
  "perguntas": [
    {
      "numero": 1,
      "texto": "Qual a idade mínima para participar?",
      "alternativas": {
        "A": {
          "texto": "16 anos",
          "correta": false,
          "explicacao": "Incorreto. Idade mínima é 18 anos."
        },
        "B": {
          "texto": "18 anos",
          "correta": true,
          "explicacao": "Correto! Conforme regulamento."
        },
        "C": { "texto": "...", "correta": false, "explicacao": "..." },
        "D": { "texto": "...", "correta": false, "explicacao": "..." }
      },
      "dificuldade": "facil",
      "topico": "Elegibilidade",
      "fonte_chunk": "chunk_0"
    }
  ]
}
```

**⚠️ CAMPOS PROIBIDOS (NUNCA incluir):**
- ❌ `item_regulamento` (dentro de pergunta)
- ❌ `referencia_fonte` (dentro de pergunta)
- ❌ `secao` (dentro de pergunta)
- ❌ `regulamento_ref` (dentro de alternativas)

**✅ FORMATO CORRETO do `fonte_chunk`:**
- ✅ `"chunk_0"` - índice do chunk no banco RAG
- ✅ `"chunk_5"` - outro exemplo
- ❌ Não usar `regulamento_ref` aqui

## 🚀 Geração com Subagents (MÉTODO PADRÃO)

### Por Que Subagents?

✅ **10-15x mais rápido** que método sequencial
✅ **Máxima qualidade** - Perguntas reais e específicas
✅ **Paralelização** - Múltiplos agentes trabalhando ao mesmo tempo
✅ **Validação automática** - Merge detecta e remove duplicatas

### Template de Prompt para Cada Subagent:

```
Gere 10 perguntas de MÚLTIPLA ESCOLHA (A,B,C,D) do banco RAG.

**Banco**: /Users/2a/.claude/skills/gerar-quiz-rag/fonte-da-verdade-rag/regulamento.db
**Chunks**: X a Y
**Numeração**: N a N+9
**Arquivo**: /Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/temp-lote-Z.json

⚠️ CRÍTICO: Use caminho COMPLETO e ABSOLUTO para o arquivo!
   CORRETO: /Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/temp-lote-Z.json ✅
   ERRADO: temp-lote-Z.json (vai salvar na raiz!) ❌

FORMATO EXATO (array JSON):
[
  {
    "numero": N,
    "texto": "Pergunta específica baseada no chunk?",
    "alternativas": {
      "A": {"texto": "Opção", "correta": false, "explicacao": "Razão"},
      "B": {"texto": "Opção", "correta": true, "explicacao": "Razão"},
      "C": {"texto": "Opção", "correta": false, "explicacao": "Razão"},
      "D": {"texto": "Opção", "correta": false, "explicacao": "Razão"}
    },
    "dificuldade": "facil|media|dificil",
    "topico": "Tópico Específico",
    "fonte_chunk": "chunk_X"
  }
]

PASSOS:
1. sqlite3 regulamento.db "SELECT conteudo FROM chunks WHERE chunk_index BETWEEN X AND Y;"
2. Leia conteúdo REAL
3. Gere 10 perguntas ESPECÍFICAS
4. Salve array JSON em temp-lotes/
```

### Distribuição de Chunks (para 200 perguntas):

| Lote | Chunks | Perguntas | Arquivo |
|------|--------|-----------|---------|
| 1-20 | 0-58 (~3 chunks cada) | 10 cada | temp-lotes/temp-lote-N.json |

### Após Gerar os Lotes:

```bash
python3 coletar-e-merge-final.py
```

Resultado: `banco-perguntas.json` com todas as perguntas validadas e sem duplicatas!

---

## Instruções para o Claude

**⚠️ LEMBRETE:** Se você precisar invocar este skill via Skill tool, use o nome completo qualificado: `gerar-quiz-rag:gerar-quiz-rag` (não apenas `gerar-quiz-rag`).

### Quando `/gerar-quiz-rag gerar` for invocado:

**⚡ IMPORTANTE: SEMPRE USE SUBAGENTS EM PARALELO!**

**PASSO 0: Usar Subagents (OBRIGATÓRIO)**

1. **CRIAR PASTA**: `mkdir -p temp-lotes/`

2. **Calcular distribuição**:
   - Lotes: `quantidade_solicitada / 10`
   - Chunks por lote: 59 / num_lotes (normalmente 3 chunks/lote)

3. **Para CADA lote (1 a N)**, lançar subagent com este prompt COMPLETO:

```
Gere 10 perguntas de múltipla escolha do banco RAG.

BANCO: /Users/2a/.claude/skills/gerar-quiz-rag/fonte-da-verdade-rag/regulamento.db
CHUNKS: X, X+1, X+2
PERGUNTAS: N a N+9
SALVAR EM: /Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/temp-lote-Z.json

EXEMPLO DE 1 PERGUNTA (siga EXATAMENTE este formato):
{
  "numero": 1,
  "texto": "Qual idade mínima para pessoa física no Renda Extra conforme item 3.1?",
  "alternativas": {
    "A": {
      "texto": "16 anos",
      "correta": false,
      "explicacao": "Incorreto. Item 3.1 estabelece 18 anos."
    },
    "B": {
      "texto": "18 anos",
      "correta": true,
      "explicacao": "Correto! Item 3.1 define idade mínima de 18 anos."
    },
    "C": {
      "texto": "21 anos",
      "correta": false,
      "explicacao": "Incorreto. É 18 anos conforme item 3.1."
    },
    "D": {
      "texto": "25 anos",
      "correta": false,
      "explicacao": "Incorreto. Idade mínima é 18 anos."
    }
  },
  "dificuldade": "facil",
  "topico": "Elegibilidade",
  "fonte_chunk": "chunk_0"
}

REGRAS CRÍTICAS:
✅ Use "alternativas" (NÃO "opcoes", NÃO "options")
✅ Cada alternativa: {"texto": "...", "correta": boolean, "explicacao": "..."}
✅ Apenas 1 alternativa com correta: true
✅ Retorne array: [ {pergunta1}, {pergunta2}, ... ]
✅ NÃO envolva em {"perguntas": [...]}

PASSOS:
1. cd /Users/2a/.claude/skills/gerar-quiz-rag
2. Consulte chunks: sqlite3 fonte-da-verdade-rag/regulamento.db "SELECT conteudo FROM chunks WHERE chunk_index BETWEEN X AND X+2;"
3. Gere 10 perguntas REAIS
4. Write("temp-lotes/temp-lote-Z.json", array_json)
```

4. **Aguardar** todos terminarem (~2 min)

5. **Executar merge**: `python3 coletar-e-merge-final.py`
   - Move automaticamente JSONs soltos para temp-lotes/
   - Valida formato
   - Remove duplicatas
   - Gera banco-perguntas.json final

6. **Validar**: `jq '.metadata' banco-perguntas.json`

**NÃO USE MÉTODO MANUAL/SEQUENCIAL** (lento e ineficiente)

---

**PASSO 1 (Apenas para referência): Consultar banco RAG**
1. Subagents farão isso automaticamente com `sqlite3` em `regulamento.db`
2. Comando SQL para ler chunks:
   ```sql
   SELECT chunk_index, conteudo FROM chunks WHERE doc_id = 1 ORDER BY chunk_index;
   ```
3. Usar ferramenta `Read` para ler `/Users/2a/.claude/skills/gerar-quiz-rag/banco-perguntas.json` (se existir)
4. Analisar perguntas existentes para evitar duplicatas

**PASSO 1.5: Pré-processar texto dos chunks** 🧹 LIMPEZA OBRIGATÓRIA

**PROBLEMA:** Chunks do RAG contêm formatação com ruído (espaços duplos, caracteres especiais).

**SOLUÇÃO:** Antes de gerar perguntas, SEMPRE normalizar o texto:

```python
# Aplicar estas transformações NO TEXTO DOS CHUNKS:
1. Remover espaços múltiplos → espaço único
   "Renda  Extra" → "Renda Extra"

2. Normalizar aspas especiais → aspas normais
   "ˮ" → '"'

3. Remover espaços antes de pontuação
   " ." → "."
   " ," → ","

4. Normalizar quebras de linha
   Múltiplas → única

5. Remover caracteres de controle/unicode indesejados
```

**EXEMPLO de limpeza:**
```
ANTES (chunk bruto):
"O  Programa  Renda  Extra  (" Renda  Extra ˮ)  consiste  em..."

DEPOIS (chunk limpo):
"O Programa Renda Extra ("Renda Extra") consiste em..."
```

**IMPORTANTE:**
- Aplicar limpeza MENTALMENTE ao interpretar chunks
- Usar texto limpo para gerar perguntas
- Não modificar o banco de dados original
- Apenas processar em memória durante geração

**PASSO 2: Gerar perguntas novas** 🚨 LIMITE DE TOKENS

**REGRA CRÍTICA - Gerar em LOTES PEQUENOS:**

Se quantidade solicitada > 5:
```
❌ ERRADO: gerar_20_perguntas() de uma vez
✅ CORRETO:
   - gerar_5_perguntas() → salvar
   - gerar_5_perguntas() → salvar
   - gerar_5_perguntas() → salvar
   - gerar_5_perguntas() → salvar
```

**LIMITE MÁXIMO POR LOTE: 5 PERGUNTAS**

Processo para cada lote de 5:
1. Ler banco atual
2. Consultar conteúdo dos chunks via SQL
3. Gerar EXATAMENTE 5 perguntas completas baseadas nos chunks
4. Adicionar ao banco
5. Salvar imediatamente
6. Validar que salvou correto
7. Continuar próximo lote

**Motivo:** Evitar JSON truncado por limite de tokens

Requisitos por pergunta:
1. Baseado no conteúdo dos chunks do RAG
2. Estrutura JSON validada (ver schema acima)
3. Garantir que é DIFERENTE das já existentes
4. Variar tópicos e dificuldade
5. Referenciar o `fonte_chunk` de origem

**PASSO 3: Salvar no JSON** 🚨 ANTI-CORRUPÇÃO

**TÉCNICA OBRIGATÓRIA - Gerar por Partes:**
1. Ler banco existente (se houver)
2. Para cada nova pergunta:
   - Criar dict completo da pergunta
   - Adicionar ao array `perguntas`
3. Atualizar metadata (total_perguntas, ultima_atualizacao)
4. **VALIDAÇÃO CRÍTICA antes de Write:**
   ```
   CHECKLIST PRÉ-SAVE:
   [ ] Todas as perguntas têm 4 alternativas (A, B, C, D)?
   [ ] Todas alternativas têm texto, correta, explicacao?
   [ ] Nenhum campo está truncado (ex: "explicac", "tex", "corr")?
   [ ] fonte_chunk no formato "chunk_X"?
   [ ] SEM campos proibidos?
   [ ] JSON completo, sem "..." ou placeholders?
   ```
5. Usar ferramenta `Write` com JSON validado
6. **VERIFICAÇÃO PÓS-SAVE (OBRIGATÓRIA):**
   - Usar `Read` para ler arquivo salvo
   - Confirmar que JSON é válido e completo
   - Se corrompido: regerar
7. Mostrar resumo do que foi gerado

### Quando `/gerar-quiz-rag iniciar` for invocado:

**PASSO 1: Escolher perguntas**
- Se modo `novo`: Gerar 10 perguntas consultando RAG
- Se modo `aleatorio`: Ler JSON e sortear 10 existentes
- Se modo `teste`: Marcar resposta correta com ⭐

**PASSO 2: Executar quiz**
1. Apresentar 1 pergunta por vez
2. Aguardar resposta do usuário
3. Dar feedback imediato (correto/incorreto + explicação)
4. Avançar para próxima
5. Ao final, mostrar pontuação e análise

**Critérios para criação das perguntas:**

- Criar perguntas baseadas no conteúdo dos chunks do banco RAG
- Cada pergunta deve testar compreensão de pontos importantes
- Variar a dificuldade (fácil, média, difícil)
- Explorar diferentes tipos de informação do conteúdo
- **NÃO repetir perguntas que já estão no banco**
- **Referenciar o chunk de origem**: Cada pergunta deve indicar de qual chunk veio (ex: "chunk_0")

### Formato das Perguntas no Quiz

Cada pergunta deve seguir este formato:

```
**Pergunta X/10**

[Enunciado da pergunta]

A) [Alternativa A]
B) [Alternativa B]
C) [Alternativa C]
D) [Alternativa D]

Qual é a sua resposta? (A, B, C ou D)
```

Regras para as alternativas:
- Exatamente 4 alternativas (A, B, C, D)
- Apenas UMA alternativa correta
- Três alternativas incorretas mas plausíveis
- Randomizar a posição da resposta correta
- **[TESTE]** Em modo teste, destacar alternativa correta com ⭐

### Avaliação de Respostas

Após o usuário responder:

**Se CORRETA:**
```
✅ Correto! A resposta é [letra]: [texto da alternativa]

[Breve explicação do porquê está correto]

Pontuação atual: X/Y
```

**Se INCORRETA:**
```
❌ Incorreto. Você respondeu [letra], mas a resposta correta é [letra correta].

**Por que sua resposta está errada:**
[Explicação clara do erro]

**Resposta correta:**
[Texto da alternativa correta] - [Explicação]

Pontuação atual: X/Y
```

### Pontuação Final

Após a 10ª pergunta:

```
===========================================
           RESULTADO DO QUIZ
===========================================

Pontuação: X/10 (XX%)

[Avaliação baseada na pontuação:]
- 10/10: Excelente! Domínio completo.
- 8-9/10: Muito bom! Conhecimento sólido.
- 6-7/10: Bom. Alguns pontos precisam de revisão.
- 4-5/10: Regular. Recomenda-se revisar.
- 0-3/10: Precisa estudar mais.

DESEMPENHO POR TÓPICO:
===========================================
✓ Tópico A: 2/2 (100%)
✗ Tópico B: 1/2 (50%)
...

TÓPICOS PARA REVISÃO:
- [Lista de tópicos com desempenho < 70%]
===========================================
```

## Regras de Interação

1. **Uma pergunta por vez** - Nunca mostrar múltiplas perguntas de uma vez
2. **Aguardar resposta** - Não avançar até o usuário responder
3. **Aceitar formatos flexíveis** - Aceitar "A", "a", "1", "primeira" etc.
4. **Feedback imediato** - Sempre explicar o resultado após cada resposta
5. **Manter contexto** - Lembrar a pontuação ao longo do quiz
6. **Tom educativo** - Ser construtivo nas correções, não punitivo

## Comandos do Usuário

Durante o quiz:
- "pular" ou "próxima" - Conta como erro e avança
- "desistir" ou "parar" - Encerra e mostra pontuação parcial
- "repetir" - Repete a pergunta atual
- "pontuação" - Mostra pontuação atual

## Validação de Duplicatas (CRÍTICO)

**PARA GARANTIR QUIZ COMPLETO SEM DUPLICATAS:**

### Algoritmo de Detecção:

1. **Match Exato** (100% similiar):
   - Comparar texto da pergunta (ignorando case)
   - Se idêntico: ❌ DUPLICATA - gerar outro

2. **Similaridade de Texto** (>60% similar):
   - Extrair palavras-chave principais
   - Contar palavras em comum
   - Se palavras_em_comum / total_palavras > 60%: ❌ DUPLICATA

3. **Match de Padrão**:
   - Mesmos itens/seções mencionadas?
   - Mesma pergunta, apenas redação diferente?
   - Se sim: ❌ DUPLICATA

### Implementação:

**ANTES DE GERAR CADA PERGUNTA:**

```
Para cada pergunta nova:
  1. Extrair palavras-chave do texto
  2. Para cada pergunta existente no banco:
     a. Comparar texto (case-insensitive)
     b. Se 100% igual: DUPLICATA
     c. Contar palavras em comum
     d. Se similaridade > 60%: DUPLICATA
  3. Se não for duplicata:
     a. ACEITAR pergunta
     b. Adicionar ao banco
  4. Se for duplicata:
     a. GERAR nova pergunta diferente
     b. Voltar ao passo 1
     c. Máximo 3 tentativas
```

### Critérios de Duplicata (CONCRETOS):

- ✅ **ACEITAR**: "Qual é a idade mínima?" + "Qual idade mínima?" → Texto diferente, mesmo conceito ✓
- ❌ **REJEITAR**: "Qual é a idade mínima?" + "Qual é a idade mínima?" → Idêntico
- ❌ **REJEITAR**: "Qual é a idade mínima para participar?" + "Qual é a idade mínima para o programa?" → >60% similar

### Estratégia para 200+ Perguntas:

1. **Variar enfoques**:
   - "O Pagar.me pode fazer X?" (verdadeiro/falso)
   - "Qual é a consequência de X?" (resultado)
   - "O artigo Y menciona qual ponto?" (citação)
   - "Em qual situação Z se aplica?" (aplicação)

2. **Variar tópicos**:
   - Nunca gerar 2 perguntas sobre mesmo item consecutivamente
   - Alternar entre seções

3. **Monitorar duplicatas**:
   - A cada 50 perguntas: avisar se taxa de duplicatas > 10%
   - Se atingir 3 duplicatas seguidas: PARAR (banco completo)
   - Se quantidade solicitada > máximo estimado: ALERTAR usuário

## Início do Quiz

Ao iniciar, apresentar:

```
===========================================
        QUIZ DO CONHECIMENTO RAG
===========================================

Este quiz contém 10 perguntas de múltipla escolha
baseadas no conhecimento armazenado no banco RAG.

- Cada pergunta tem 4 alternativas (A, B, C, D)
- Apenas uma alternativa está correta
- Você receberá feedback após cada resposta

Preparado? Vamos começar!

---
```