DELTA37/structured-report

Relatório estruturado

Um arquivo HTML auto-contido (sem rede) que permite a um leitor ocupado

1. ver todo o trabalho como um mapa de tarefas, com o que está aguardando a sua decisão dentro de cada tarefa,
2. abrir qualquer tarefa — e qualquer etapa dentro dela — e auditar como foi feita e por que cada afirmação é considerada verdadeira,
3. responder às perguntas do agente ali mesmo, e ver quais de seus prompts produziram o quê.

Estrutura vs. conteúdo

• Estrutura pertence ao template (assets/template.html): layout, nomes das seções (Problema, Tarefa, Contexto, Conclusões, Suposições, Resultado, Não verificado, Fluxo de trabalho, Precisa de aprovação, Suas ações), sua ordem, status, cada ícone e cada rótulo de interface. Fixo, sempre em inglês. Ícones marcam estrutura apenas, nunca o que o conteúdo é sobre.
• Conteúdo é seu: o JSON, no idioma do usuário. scripts/build.py o valida e preenche os placeholders do template. Você nunca escreve HTML e nunca inventa seções.

Fluxo de trabalho

1. Colete o material: mensagens, resultados de ferramentas, arquivos, comandos, links, testes, medições, decisões. Relate apenas o que realmente aconteceu.
2. Divida em tarefas (1–12): uma tarefa = um objetivo com seu próprio resultado. Conecte-as com links: depends, blocks, related.
3. Preencha cada tarefa seguindo as regras abaixo e references/schema.md.
4. Escreva o JSON — padrão reports/<YYYY-MM-DD>-<slug>.json no diretório de trabalho.
5. Construa: python3 <skill>/scripts/build.py <arquivo>.json → <arquivo>.html. Corrija cada error:; leia cada warning: e corrija-o a menos que seja genuinamente verdadeiro.
6. Abra localmente (open / xdg-open / start) e forneça o caminho. Nunca faça upload.
7. No chat: 2–4 linhas — o resultado principal e o que aguarda o leitor.

Relatório vivo: rastreie a sessão, receba respostas de volta

Quando o usuário quiser que o relatório seja mantido atualizado durante a sessão (ou solicitar um relatório rastreado / vivo), vincule a sessão uma vez:

python3 <skill>/scripts/track.py start reports/<arquivo>.json      # cria <arquivo>.journal.json

A partir daí, o hook UserPromptSubmit (instale uma vez: track.py install-hook, que também adiciona um hook de Parada) registra cada prompt do usuário no journal e lembra você do número do prompt. Após cada prompt que altere o trabalho, atualize o JSON e reconstrua — build.py gera impressões digitais de cada bloco (cada nó × seção) e marca blocos novos ou alterados com o prompt atual. Nunca escreva marcas você mesmo. O relatório mostra uma trilha de Prompts; selecionar um prompt destaca o que apareceu (verde) ou mudou (azul) ali.

Perguntas para o leitor. Coloque decisões em approvals. Cada uma é uma pergunta com options — exclusivas por padrão (uma resposta) ou "multi": true (qualquer quantidade que se aplique) — sua recommend (uma lista para multi), why e due. O leitor sempre tem "sua própria resposta" como uma opção extra; uma pergunta sem opções é respondida em texto livre. No relatório, as perguntas abertas de uma seção Precisa de aprovação formam uma série, uma pergunta por vez: uma opção exclusiva responde e segue em frente, uma multi-escolha ou resposta própria é confirmada com Próximo, a série termina em uma revisão de todas as respostas, e Enviar respostas as envia para você — não há outra forma de enviar, e actions (etapas que o leitor realiza) não têm entradas. As respostas vão para um serviço de resposta local (127.0.0.1:47319, iniciado e mantido atualizado pelo build) mesmo quando o relatório é aberto como um arquivo simples, e são armazenadas no journal como o próximo prompt. Enquanto o relatório tiver perguntas abertas, mantenha um waiter (espera) em execução como um comando em segundo plano:

python3 <skill>/scripts/track.py wait reports/<arquivo>.json

Quando o leitor enviar, wait imprime as respostas e sai — essa saída volta para você: trate-a exatamente como o prompt do usuário e continue; inicie wait novamente se restarem perguntas. Se nenhum waiter estiver em execução, o hook de Parada entrega as respostas enfileiradas antes do seu turno terminar, e o hook UserPromptSubmit as anexa à próxima mensagem do usuário — as respostas nunca são perdidas. Perguntas respondidas aparecem como respondidas após o próximo build. --static constrói um relatório sem o canal de respostas (para compartilhamento fora desta máquina): as perguntas são exibidas somente leitura, sem entradas.

Link sob a entrada. scripts/statusline.py imprime uma linha de status para o relatório da sessão — seu título como um link clicável que abre o HTML no navegador, e quantas perguntas ainda aguardam. Use-o como a linha de status ou anexe sua saída a uma existente; ele não imprime nada para sessões sem relatório.

Cada bloco do relatório tem um botão copiar como Markdown (o relatório inteiro, um cartão de tarefa, um relatório, uma seção, um item único, uma etapa, um prompt) — aponte o leitor para ele quando quiser colar algo em outro lugar.

As regras que tornam o relatório confiável

Separe como você sabe cada coisa; nunca as misture.

• contexto — fontes que você realmente consultou: id (C1…), title curto, uma url real, e uma note com o fato exato extraído. Nunca invente URLs. Prefira URLs de repositório/web: links file:// não abrem na máquina do leitor (o build avisa; um arquivo local ausente é um erro).
• inferências — conclusões, cada uma com basis (ids de contexto) e confidence. Sem base → é uma suposição.
• suposições — assumidas como verdadeiras sem verificação: why, como verify, risk se errada.
• não verificado — o que você não verificou ou fez, com why não. Os leitores confiam mais nisso do que em qualquer outra coisa; diga claramente. Uma tarefa concluída sem unchecked recebe um aviso ([] significa "verificou tudo" — somente se verdadeiro).
• resultado — o que existe agora, como itens tipados. Cada item verified precisa de how: o comando, teste ou link que o prova — o build falha sem ele.
• etapas — os passos que você realmente deu, 2–8 por nível. Uma etapa é o mesmo tipo de nó que uma tarefa: id + title obrigatórios, qualquer campo de tarefa permitido, seus próprios stages + flow, em qualquer profundidade. No cartão, mostra detail (o que você fez), outcome (o que saiu), status, when, uses. Clicar em uma etapa abre seu relatório na mesma estrutura, então dê conteúdo real a etapas que foram trabalho real. Becos sem saída também são etapas (failed / skipped).
• próximos passos são etapas planejadas — qualquer coisa ainda a fazer é uma etapa com status: "planned", um detail (o que será feito) e when (a condição ou momento: "após sua aprovação", "Segunda-feira"). Uma tarefa inacabada sem etapa planejada ou em andamento recebe um aviso.
• aprovações — decisões que apenas o leitor pode tomar: a pergunta, why é dele, options (exclusivas, ou multi: true), sua recommend (uma das opções; uma lista para multi), due. Várias perguntas relacionadas em um nó se tornam uma série — ordene-as conforme o leitor deve respondê-las. Nunca peça aprovação para algo já feito.
• ações — coisas que apenas o leitor pode fazer, com o command exato e due quando relevante.
• segredos — o relatório é encaminhado. O build falha em qualquer coisa que pareça uma chave, token, chave privada, JWT, atribuição de senha ou credenciais em uma URL (gitleaks também é usado quando instalado). Remova-o do conteúdo; nunca "masque" manualmente. Segredos em prompts registrados são mascarados automaticamente.

Escreva estrutura, não prosa

Cada campo de texto renderiza estrutura, então dê estrutura a ele:

• - item → marcadores; 1. item → numerados (apenas sequências reais); duas ou mais linhas Chave: valor → uma tabela alinhada; um array JSON de strings → marcadores.
• **negrito** para a(s) única(s) ou duas coisas por linha que o leitor não deve perder; ==texto== destaca; `código` para identificadores, caminhos, comandos.
• Nenhum parágrafo maior que duas frases; sem subtítulos ou linhas introdutórias.

Orientação de campos: brief — 1–3 linhas Chave: valor para o cartão do mapa. problem — fatos chave/valor. goal — marcadores do que significa 'feito'. result.summary — chave/valor ou marcadores.

Idioma

Conteúdo no idioma do usuário, meta.lang definido com seu código. Rótulos de estrutura permanecem em inglês.

Arquivos

• assets/template.html — a estrutura: marcação com placeholders, estilos, ícones e um script para layout, navegação, busca, a trilha de prompts e resposta.
• scripts/build.py — valida o conteúdo (verificações acima, segredos), carimba o journal, renderiza o template. --check valida apenas; --template usa outro template.
• scripts/track.py — start, wait, hook, stop-hook, daemon, status, install-hook (veja sua docstring).
• scripts/statusline.py — o link do relatório para a linha de status do Claude Code.
• references/schema.md — todos os campos.
• examples/ — exemplos em inglês e russo; o exemplo em russo carrega um journal de 5 prompts.