Temper-Skills (modo biblioteca)

O que Temper-Skills (modo biblioteca) faz?

Transforme a lógica de decisão de um skill de agente ou prompt em Python determinístico — zero chamadas de LLM na inferência — usando a CLI temper-skills instalada. Você orquestra a CLI e retransmite sua saída; a biblioteca faz o temperamento. Você nunca escreve a árvore de decisão manualmente.

Use este skill quando você não tiver um subagente/primitive Task nativo para executar o loop você mesmo. Dentro do Claude Code, prefira o skill modo subagente (ele executa sem chave, com um painel ao vivo). Este modo usa a CLI externamente.

Quando usar

• Um skill .md, prompt do sistema ou playbook contém lógica de roteamento/decisão (se-isso-então-aquilo sobre entradas estruturadas) que deve ser testável, diferencial em um PR ou resiliente a atualizações de modelo.
• Boa adequação: roteamento de tickets, regras de classificação, verificações de elegibilidade — decisões categóricas sobre características pré-computáveis.
• Não é adequado: pontuação contínua, geração de texto ou lógica sem documentação que o modelo possa acessar.

Regras inegociáveis

1. Sempre chame a biblioteca através de sua CLI. Nunca reimplemente a lógica de decisão em linguagem natural como substituto para executá-la.
2. Nunca pule a ratificação do schema. O schema que você aprova é a semente ingênua que o loop então co-evolui (o schema_critic a expande, o guarda de ganhe-um-ramo a poda), então um erro de extração silencioso na semente ainda envenena tudo. Use a porta baseada em arquivo abaixo (--propose-schema), mesmo quando nenhum terminal estiver anexado. Revise o schema co-evoluído e quaisquer notas de schema gaps / schema grew que a CLI imprimir no final.
3. Nunca instale silenciosamente. Se a porta (Passo 0) relatar que a biblioteca ou um backend está faltando, pergunte ao usuário antes de executar pip install ou alterar seu ambiente.
4. Nunca afirme que a árvore está "correta" — apenas que é determinística e auditável. A correção é do usuário, estabelecida por exemplos ratificados (validate, Passo 4).
5. Retransmita as portas e vereditos da CLI fielmente — veredito de auditoria, painéis de persona, zonas cinzentas, casos aguardando ratificação. Não os resuma.

Passo 0 — Verificar instalação + backend

Execute python scripts/check_install.py e ramifique no código de saída:

• 0 — pronto, prossiga.
• 10 — instalado mas sem backend de modelo. Diga ao usuário: temper-skills precisa de um backend — uma CLI claude ou opencode logada, ou ANTHROPIC_API_KEY no ambiente. Pergunte como ele deseja fornecer um. Não prossiga até que um backend exista.
• 11 — não instalado. Pergunte: "temper-skills não está instalado. Instalar agora? (pip install temper-skills)" Instale apenas com confirmação explícita.

Passo 1 — Triagem com guide (lidere aqui)

Encontre o arquivo .md ou prompt que contém a lógica de decisão (confirme o caminho com o usuário se ambíguo), então execute o tour de comando único:

temper-skills guide <caminho/para/skill.md> --json

Se o usuário apontar para um diretório (uma biblioteca de skills), varra-o em vez de guiar um arquivo — a auditoria é um relatório que vale a pena retransmitir por si só:

temper-skills audit <dir> --json --report audit.md

Retransmita os resultados classificados (o JSON é uma lista de relatórios por skill, mais acionáveis primeiro) e ofereça-se para guide a melhor escolha. audit.md é uma versão Markdown compartilhável para um PR.

Sempre passe --json. guide e ingest emitem então um manifesto legível por máquina na stdout e enviam os painéis Rich humanos para a stderr — leia o manifesto, não extraia os painéis. O manifesto de guide é:

{ "audit": { "verdict": "...", "recommended_action": "...", ... },
  "action_taken": "temper|decompose|...",
  "status": "compiled|stopped_for_ratification|action_not_auto_run",
  "final_skill_path": "...", "artifacts": ["..."] }

guide audita o skill, então segue a recommended_action. Retransmita o veredito da auditoria e a ação ao usuário:

• temper — uma decisão em forma de árvore. guide tempera (rápido); status: compiled.
• decompose — um fluxo (≥2 decisões). guide emite schemas por decisão e para; status: stopped_for_ratification.
• externalize_data / build_normalizer / delegate_prose — não são trabalhos de temperamento. status: action_not_auto_run; retransmita a dica de ação e pare.

guide é o tour: ele executa o perfil quick e aceita automaticamente o schema inferido. Isso é bom para "mostre-me o que isso faz", mas para uma árvore na qual o usuário vai confiar, vá para o Passo 2 para que o schema seja ratificado.

Passo 2 — Produzir uma árvore duradoura (fluxo ratificado)

2a. Rascunhe o schema e PARE para ratificação

temper-skills ingest <caminho/para/skill.md> --propose-schema --json

Isso escreve schema.proposed.py e para — o loop nunca executa em um schema não ratificado. O JSON na stdout fornece {proposed_schema_path, fn_name, features:[{name,type,description}], constraints}. Mostre ao usuário as características propostas e pergunte exatamente uma coisa: aceitar essas características, ou editar a lista? Aplique as edições deles em schema.proposed.py.

Não pergunte nada mais ao usuário aqui — nem sobre amplitude de características, nem sobre quais ramos manter. A poda é trabalho do loop (o crítico de overengineering), não do usuário.

2b. Compilar contra o schema ratificado

temper-skills ingest <caminho/para/skill.md> \
  --schema schema.proposed.py \
  --profile standard \
  --json

Escolha o perfil com o usuário — quick | standard | audit-grade, padrão standard; veja references/profiles.md antes de recomendar. --json implica não interativo: o loop executa até a convergência (não pode pausar para uma porta por rodada quando acionado desta forma — essa porta é um recurso de terminal humano) e emite o manifesto resultante na stdout. Leia isso, não extraia os painéis. (--require-fit aborta cedo com código de saída 3 se o veredito da auditoria for skip; adicione-o para evitar queimar o loop em uma má adequação.

2c. Se a ação foi decompose

Um fluxo deve ser dividido primeiro; tempere cada decisão separadamente:

temper-skills decompose <caminho/para/skill.md> --temper-each --out-dir out/

Isso emite um schema por decisão e para para ratificação. Apresente os schemas, deixe o usuário editá-los, então reexecute o mesmo comando para compilar cada um em uma árvore mais o skill orquestrador (--yes-unratified pula a parada — evite-o a menos que o usuário peça).

Passo 3 — Relatar os artefatos (a partir do manifesto)

O manifesto ingest --json é a fonte da verdade — leia estes campos, não extraia:

{ "tree_path": "...", "tempered_skill_path": "...",
  "validation_dataset_path": "...", "validation_case_count": 0,
  "gray_zones": [{"node": 1, "condition": "...", "note": "..."}],
  "features": ["..."], "node_count": 0, "profile": "...", "cost_usd": 0.0 }

Apresente todos os três artefatos ao usuário:

• tree_path — a árvore de decisão: não importa nada, zero chamadas de LLM na inferência, com um cabeçalho generated_at + modelo e comentários de proveniência por nó;
• tempered_skill_path — o skill.md temperado: o skill original reescrito para chamar a árvore congelada em vez de re-decidir. Metade da entrega; não o descarte;
• validation_dataset_path — o .validation.jsonl confirmado que o loop construiu para suas zonas cinzentas, aguardando ratificação (validation_case_count). Linhas com "agrees": false são as discordâncias de maior valor para o usuário decidir. Os testes de bloqueio de comportamento ao lado dele (test_<stem>.py) permanecem verdes; apenas rótulos ratificados podem tornar um teste vermelho.

Diga ao usuário os caminhos, o perfil, o cost_usd e as gray_zones. Reafirme a regra 4: determinístico e auditável, não "correto."

Passo 4 (opcional) — Fixar em CI

Uma vez que o usuário tenha ratificado um conjunto rotulado, valide a árvore contra ele:

temper-skills validate decision_tree.generated.py ratified.json --min-agreement 1.0

Saída não zero em caso de discordância — é isso que fixa a árvore em CI. Cada discordância é um bug na árvore ou um exemplo mal rotulado; retransmita-os para aprovação.

Referência

Veja references/profiles.md para rodadas / convergência / painel de persona / custo por perfil antes de recomendar um.

Nunca

• Nunca escreva a lógica da árvore em linguagem natural em vez de executar a biblioteca.
• Nunca pule a ratificação do schema, mesmo em uma demonstração quick (quick remove comentários de proveniência, não a porta).
• Nunca instale ou modifique o ambiente sem confirmação explícita.
• Nunca afirme que a árvore gerada está "correta."