jumibot/informe_deliberativa

Relatório de uma tarefa deliberativa

Uma tarefa deliberativa (pesquisar, deliberar ou projetar; «Sete tipos de tarefa em três famílias», 223) produz um relatório e as tarefas que dele surgem («Uma tarefa deliberativa produz um relatório e as tarefas que surgem», 218). Seus dilemas vivem no relatório, atualizados a cada resposta do proprietário, e não na fila nem em outro arquivo. O que pertence a outra tarefa é proposto para separação; ao fechar, o que ainda estiver aberto segue para sua tarefa («Em uma deliberativa, o que é de outra tarefa é proposto para separação», 221). Uma deliberativa não testa nada e apenas altera seu relatório: o que precisa ser aplicado é feito pelas tarefas que cria.

Esta skill descreve o que o relatório contém, como as perguntas são escritas e como é cada iteração. O gerador, os recursos, os temas e a verificação são os mesmos de criar_documentos, que deve ser lido em conjunto. É a skill do agente da família deliberativa, quando existir («Agentes especializados, um por família de tarefa», 304); enquanto isso, é carregada pelo subagente da tarefa.

O leitor é o proprietário, que precisa decidir. O relatório economiza trabalho: o que precisa ser decidido aparece primeiro, cada pergunta é respondida com uma letra e a recomendação se destaca rapidamente. Comunicar bem é um objetivo da SF (decisão 231).

Onde fica

• Em um projeto incorporado à SF, em sf/informes/ («Os documentos da SF ficam na pasta sf/», 203).
• Na própria SF, em docs/referencias/reports/, até que seja decidida sua migração para sf/ (pergunta 13 do relatório «Tipos de tarefa», na tarefa 303).

O nome do arquivo é o tema, não o número da tarefa: Tipos de tarefa.md e seu .html. As versões substituídas vão para _respaldo/, na mesma pasta.

Modelo: o relatório docs/referencias/reports/Tipos de tarefa.md da SF (tarefa 274). Se estiver no ambiente, é lido como exemplo; seu conteúdo não é copiado. O template vazio está em assets/plantilla-informe.md.

Estrutura

As seções seguem sempre esta ordem, com estes {#id}, para que o proprietário saiba onde olhar e as tarefas possam referenciá-las:

1. Resumo {#resumo}. A conclusão em dois ou três parágrafos curtos: o que é proposto, em que se baseia e quantas perguntas restam e onde. Se um esquema esclarece o conjunto, vai aqui. Termina com saltos para o que precisa ser decidido ([Ver as N perguntas](#por-decidir){: .salto}).
2. A análise, em uma ou várias seções próprias: o que foi estudado e o que é proposto, com suas razões. Primeiro o que é proposto ou concluído, mesmo que derivado do restante; depois, a avaliação que o sustenta e seus limites. Aqui vão os cartões, esquemas e tabelas do tema.
3. Decidido {#decidido}. Uma tabela com as decisões do proprietário que esta tarefa fixa: Nº | Decisão | O que fixa aqui. Cada decisão está registrada em seu arquivo de decisões antes de aparecer aqui.
4. Por decidir {#por-decidir}. As perguntas abertas, em um bloco ::: perguntas. Se forem muitas, são divididas em blocos, cada um em sua seção ({#por-decidir-<destino>}), por importância ou pelo local para onde iriam se separadas; cada bloco abre com uma frase que indica o que reúne e um salto para sua separação.
5. Separar {#separar}. As separações propostas: um cartão por separação ({: #a-<destino>}), com o que leva (as perguntas, com link para cada uma) e para onde (uma nova tarefa, um passo de uma tarefa existente ou /sf_split). Se houver escolha sobre como separar, também é uma pergunta.
6. Tarefas {#tarefas}. As tarefas que surgem: Tarefa | Tipo | O que faz. As já existentes, com seu número.

Anexos, ao final e apenas se necessários: fontes (::: fontes), dados completos, texto proposto para um documento que será alterado por outra tarefa.

Se a análise não deixar nada para decidir, separar ou criar, essas seções são removidas; as demais não mudam de ordem.

Cabeçalho: antetitulo com «Projeto · Relatório de <análise, projeto ou pesquisa> · <mês ano>», lema, subtitulo com o que o relatório responde, versao, estado («Proposta · Tarefa N», «Decidido · Tarefa N»…), capa: escura, destino: projeto, ferramentas, menu: secoes (o proprietário navega entre seções), tipo («Relatório de análise», «Relatório de projeto», «Relatório de pesquisa») e rodape com a tarefa, de onde parte o relatório e quem decide.

As perguntas

Cada pergunta é um cartão de ::: perguntas, o recurso «pergunta com opções» de criar_documentos:

::: perguntas 2 dobráveis

### 1 · Como garantir «apenas seu documento» {recomendada=A} {: #p1}

Hoje nada fiscaliza: qualquer alteração entra na tarefa.

Opção A
:   A tarefa declara seu documento com um comando, e `fechar` recusa se o branch tocar outros arquivos.

Opção B
:   Apenas a regra, escrita na orquestração.

Recomendação
:   **A.** É cumprida com um comando, não com a memória do principal.

:::

• Uma decisão por pergunta, com um título que a nomeia e um número por importância (1 a mais importante). O número e a âncora {: #pN} não mudam, mesmo que a pergunta seja decidida ou separada: os passos das tarefas a citam por eles («Decidir … (pergunta 5) (relatório «Tipos de tarefa», 274)»).
• Contexto em uma ou duas frases, apenas se necessário para a escolha: o que acontece hoje ou por que é preciso decidir.
• Duas ou três opções, Opção A, Opção B…, cada uma com suas implicações em uma ou duas frases. «Como hoje» é uma opção quando realmente é possível.
• Recomendação com sua justificativa em uma frase, e recomendada=A no título para que se destaque. Toda pergunta aberta traz recomendação; o gerador avisa se faltar.
• Status, atualizado a cada resposta:
  • status=aberta (padrão): aguarda resposta;
  • status=decidida escolhida=B: com um campo Decisão que informa o escolhido, com seus detalhes, e o número da decisão registrada; a opção escolhida é marcada e as demais ficam em cinza;
  • status=separada destino=tarefa_303: foi para outra tarefa (o _ é lido como espaço na marca). Permanece no relatório para que a tarefa de destino possa referenciá-la.
• Perguntas que dependem de outra são indicadas em seu contexto, com link para a outra.

Quando uma pergunta é decidida ou separada, seu cartão permanece no bloco com o novo status, e a decisão também vai para a tabela de «Decidido». O resumo informa quantas ainda estão abertas.

Cada iteração

Cada resposta do proprietário, ou cada avanço da análise que altere o relatório, é uma iteração:

1. Fazer backup da versão que será substituída: python -I -X utf8 <skills>/criar_documentos/scripts/respaldar.py <relatorio>.md <motivo> («Antes de substituir um documento, faz-se backup em _respaldo/», 217).

2. Escrever as alterações: o status das perguntas respondidas, «Decidido», as separações e as tarefas, e o resumo. Subir a versão no cabeçalho (2.5 → 2.6; o primeiro número muda quando a estrutura do relatório é alterada) e atualizar o estado.

3. Regenerar o HTML na mesma alteração («Cada alteração de um .md regenera seu HTML», 220):

   python -I -X utf8 <skills>/informe_deliberativa/scripts/informe_to_html.py <relatorio>.md
   

4. Enviar para develop sem branch, por ser um documento novo («Documentos novos vão para develop a cada iteração e são oferecidos no navegador», 216), com o comando que fará isso quando existir («Documentos novos para develop a cada iteração, e abri-los no navegador», 297).

5. Oferecer para abrir o HTML no navegador, com a nova versão.

Verificação

A mesma de criar_documentos («Verificação») e, adicionalmente:

• cada pergunta aberta tem pelo menos duas opções e uma recomendada; nenhuma decidida sem escolhida nem separada sem destino;
• as contagens do resumo (perguntas abertas, separações, tarefas) coincidem com as seções;
• cada link para uma pergunta (#pN) ou para uma separação (#a-…) existe;
• a tabela de «Decidido» contém apenas decisões já registradas.