plugadvpl-index-usage — Skill-chefe

Quando o projeto tem .plugadvpl/index.db, Claude DEVE consultar o índice antes de qualquer Read em fonte ADVPL. Fontes Protheus têm tipicamente 1.000–10.000 linhas — abrir cru queima contexto, escala mal e produz respostas vagas.

Quando usar

Esta skill ativa sempre que:

• O projeto atual contém .plugadvpl/ (detectado pelo fragment <!-- BEGIN plugadvpl --> em CLAUDE.md).
• O usuário pergunta sobre arquivos .prw, .prx, .tlpp (ou pede análise/edição).
• Antes de qualquer chamada Read em fonte ADVPL — sem exceção.
• Para localizar funções, callers/callees, uso de tabelas, parâmetros MV_, SQL embarcado.

Regra de decisão — qual ferramenta usar

Quando É permitido Read no .prw cru

Só depois de localizar a linha exata via índice. Exemplos válidos:

• Read FATA050.prw com offset=234, limit=46 (intervalo 234–280 identificado em sql_refs).
• Read MATA461.prw com limit=50 (apenas header/cabeçalho).

NUNCA abra o arquivo inteiro sem range — isso queima ~50k tokens por fonte médio e desperdiça contexto que poderia caber 10 arquivos analisados via índice.

Workflow recomendado

1. Receba a pergunta do usuário.
2. Mapeie para um comando da tabela acima.
3. Rode o slash command (resultado limitado a 20 entradas por default).
4. Refine com --module/--table/--path se vier "... e mais N resultados".
5. Só então, se ainda precisar do código exato, faça Read com offset+limit apontando para a linha retornada.

Output budget

Todo comando retorna no máximo 20 resultados (--limit 20). Se a saída indicar
"... e mais N resultados; refine com --table/--module/--path", refine com filtros, não peça mais resultados sem critério. Comandos suportam --compact para uma-linha-por-registro.

Saúde do índice

Antes de confiar em consultas, em sessão nova rode /plugadvpl:status para conferir contagens e última ingestão. Se arquivos foram editados fora do Claude (IDE, git pull), execute /plugadvpl:reindex <arquivo> ou /plugadvpl:ingest --incremental.

Anti-padrões

• Ler .prw cru "para entender o contexto" — proibido. Use arch primeiro.
• Pedir ao usuário para colar trechos do fonte — o índice já tem os metadados.
• Usar Grep direto no diretório com regex genérica em vez de find/grep do plugadvpl (que retorna chunks/funções, não linhas soltas).
• Ignorar --limit: pedir todos os resultados em base com 24k fontes é estouro de contexto garantido.

Referência rápida

Comandos plugadvpl relacionados

/plugadvpl:arch, /plugadvpl:find, /plugadvpl:callers, /plugadvpl:callees, /plugadvpl:tables, /plugadvpl:param, /plugadvpl:lint, /plugadvpl:status, /plugadvpl:ingest, /plugadvpl:reindex, /plugadvpl:grep, /plugadvpl:doctor, /plugadvpl:help.