human-in-the-loop

Human in the Loop

Camada de interfaces descartáveis entre o proprietário e o agente. O agente descreve o que o proprietário precisa ver e decidir, um script monta uma página HTML autônoma, o proprietário responde no navegador em qualquer ordem e retorna um JSON. A página não é escrita manualmente: apenas spec.json e scripts/build.py.

$SKILL abaixo indica a pasta deste arquivo.

Quando usar

• Documento para aprovação: especificação, PRD, proposta, plano. Status por seções, edição de texto no local, respostas para perguntas abertas.
• Seleção entre opções em várias perguntas simultaneamente, cada pergunta tem opções do agente e sua própria resposta.
• Rotulação cega para referência: o proprietário responde, as respostas do modelo ficam em um arquivo separado e não aparecem na página; depois score.py calcula a concordância.
• Avaliação de sugestões em escala.

Se for uma ou duas perguntas, pergunte no chat.

Ciclo

1. Spec. Monte o spec.json (formato: references/spec-format.md). Para documentos Markdown, existe um esqueleto: python3 $SKILL/scripts/from_markdown.py doc.md --options options.json -o spec.json (seções ## e ### se tornam blocos editáveis; a seção "Perguntas abertas" vira perguntas com opções do options.json). Para rotulação cega, coloque as respostas ocultas em um arquivo sidecar.json separado; elas não devem estar no spec.json.
2. Página. python3 $SKILL/scripts/build.py spec.json -o page.html monta e abre a página. Coloque o spec e a página junto ao projeto (ex.: em private/), não no scratchpad, para que o proprietário possa retornar. Diga ao proprietário em uma linha o que foi aberto e o que se espera dele.
3. Proprietário responde e insere o JSON no chat (botão "Copiar JSON para o agente"). No JSON, apenas o que foi alterado: status, comment, markdown_old/markdown_new, answers, notes, além de decision e general_comment.
4. Agente aplica as respostas usando o campo task do JSON e relata: o que foi alterado, o que permaneceu. Um decision vazio, quando há botões de decisão, significa que a decisão não foi tomada: pergunte novamente, não considere o documento aprovado. Para rotulação: salve o JSON e execute: python3 $SKILL/scripts/score.py labels.json sidecar.json --spec spec.json. Mostre as divergências ao proprietário em uma lista; não corrija erros de rotulação por conta própria.

Se o spec mudar, a página é reconstruída com a nova versão; respostas antigas no navegador não se aplicam a ela.

Verificação

python3 $SKILL/tests/selftest.py [pasta] monta os dois exemplos em examples/, executa-os em Chromium headless e verifica as exportações. Execute após qualquer alteração no template ou scripts.