documento_fundacional

Documento fundacional

O documento fundacional apresenta um projeto, ou um produto de uma família, de forma formal e compacta: qual necessidade atende, por que merece ser desenvolvido, o que é, em quais situações agrega valor, o que o respalda e o que precisa demonstrar. É a descrição de referência do projeto.

Diferencia-se do documento de visão (skill documento_vision) em três aspectos:

• Sem história condutora. Não há caso, cenas nem prólogo. É uma descrição ordenada, como um dossiê.
• Mais formal. Cada afirmação do domínio carrega sua referência, e sempre se separa o que é publicado, o que é objetivo de design e o que é suposição de cálculo.
• Para o autor e para compartilhar. Serve ao autor (e ao Claude em sessões futuras) como descrição compacta e sem distrações, e pode ser entregue diretamente a colaboradores, sócios ou financiadores.

Ambos coexistem. A visão conta o projeto com uma história; o fundacional o descreve. Se um muda, o outro é revisado.

Esta skill diz o que compõe um fundacional e como escrevê-lo. O gerador, os recursos e sua sintaxe, os temas, as ferramentas e a verificação são os comuns de crear_documentos, que é lido em conjunto com esta.

Onde colocar

Os documentos fundacionais de um projeto ficam juntos em docs/specs/vision/ (metodologia da SF, "Estrutura documental comum"): a visão, o fundacional e as infografias técnicas em infografias/.

• Do projeto: docs/specs/vision/fundacional-<projeto>.md e seu .html.
• De cada produto de uma família, se existir: fundacional-<produto>.md.

O .md é a fonte. O .html é gerado e não é editado manualmente. Se partir de um PDF ou HTML existente, converte-se para .md e o original é preservado junto a ele ou em _respaldo/.

Modelo. Se o projeto já tem um fundacional que aplica bem estas regras, ele é lido como exemplo ao escrever ou revisar outro; o conteúdo específico do domínio não é copiado.

Seções

Há um núcleo que todo documento fundacional possui e seções opcionais que são incluídas quando o projeto as necessita. São numeradas na ordem em que aparecem. Os anexos vão ao final, com etiqueta "Anexo A · …".

Ordem: primeiro explicar, depois justificar. O leitor precisa saber o que é o produto antes de avaliar os argumentos. Após a abertura (propósito, se houver, e a prosa da razão para desenvolver com a ideia, a diferença e a tese), vêm as seções que explicam: o sistema ou a família, o produto e seu funcionamento, os cenários e as alternativas. Depois, as que justificam: a necessidade documentada e o custo do problema, o impacto, o dimensionamento, os riscos e "O que deve demonstrar". Os cartões da necessidade documentada podem ir em sua própria seção, após o produto, se a abertura já resume a tese.

Portada sóbria. Marca, nome e lema em letra normal (uma ou duas linhas). Nada mais, para que o cabeçalho seja baixo: a ideia com o propósito abre a primeira seção como entrada, a versão e o estado vão ao rodapé, e não há linha de números (contar fichas ou evidências é inventário, não argumento; se um número argumenta, vai no texto).

Avisos de escopo global (o que do documento é objetivo de design e o que está validado, ou qualquer critério que se aplica a todo o texto): vão no início, fora de qualquer seção. São escritos como citação > entre o # Nome e a primeira ##; o gerador os coloca antes das seções, como retângulo.

Núcleo

1. Razão para desenvolver. Começa com uma prosa inicial, antes dos cartões e sem subtítulos:

   • a ideia com o propósito, como entrada;
   • a diferença frente às alternativas existentes, em um parágrafo, com sua referência e uma frase por alternativa;
   • a tese de desenvolvimento: o que merece ser financiado ou construído agora e com que condição terá valor. Vai em prosa, não em um retângulo, e se justifica: em quais fatos do documento se apoia, com seu número e sua referência, e o que falta saber, que é o que deve medir o piloto.

   Depois, dois ou três cartões com a necessidade documentada (o problema medido, a capacidade de intervir, a consequência), cada um com sua referência. Esta forma, prosa que argumenta e depois cartões justificados, é o modelo de todas as seções (ver "Regras de redação").

2. O produto. O que é em poucos números (capacidade, autonomia, alcance…), como funciona por subsistemas, sua arquitetura, suas funções principais, como evolui (família, plataforma, verificar / reconfigurar / redesenhar) e o que não faz.

3. Cenários de uso. As situações em que o produto pode agregar valor, com um código cada (S1, S2…) para citá-los no restante do documento. Em cada uma: quando agrega valor, limite do argumento, o que medir e a base documental. Os cenários são compatíveis entre si; não são somados como populações independentes.

4. Evidências. Primeiro, o método e o escopo da busca. Depois, um cartão por evidência: tipo (medição, piloto, guia, estudo…), o que diz com seu número, a quais cenários afeta e uma leitura para o projeto que diga o que respalda e o que não.

5. O que deve demonstrar. O passo do documento ao piloto: fases priorizadas, cada uma com seu circuito, seu motivo e sua condição para avançar; as validações necessárias (técnica, operacional, econômica); as decisões de avanço (portas); a decisão proposta e como será medida.

6. Fontes e referências. Todas as fontes com código por tipo (por exemplo E evidências, F fichas técnicas, P preços, D economia, C clínica, M documentos do próprio projeto), sua procedência, seu link e a data de revisão.

Opcionais

• Propósito e valores (missão, visão e valores), no início, como seção própria ou como cartões dentro da primeira. Para projetos que buscam alinhar uma equipe ou colaboradores.
• Custo do problema, quando há uma dimensão econômica: casos documentados com seu número e sua "implicação e alcance", o que pode ser evitado e o modelo econômico (uma fórmula). Vai depois da razão para desenvolver.
• Dimensionamento do mercado ou do território: o que as fontes permitem afirmar e o que não, quais dados seriam necessários (denominador, exposição, economia), um cenário transparente (pode levar uma calculadora como componente próprio) e como convertê-lo em uma estimativa defensável. Vai antes de "O que deve demonstrar".
• Anexo de comparação com uma referência existente: um cartão por dimensão, com duas colunas ("referência · publicado" e "projeto · design") e a contribuição de cada abordagem. Ao final, os valores que a comparação deve preservar e como verificar o valor agregado.
• Anexo de fichas por elemento (medicamentos, materiais, componentes, clientes tipo…): uma ficha por elemento com seus dados e seus cenários. O gerador adiciona um buscador e um filtro por cenário.
• Impacto: o que mudaria se o produto funcionar, sempre condicionado ao que o piloto demonstrar. Um cartão por dimensão (econômica, para as pessoas, para o território ou o ambiente) com "O que pode mudar" e seu indicador, mensurável antes e depois. A prosa inicial nomeia a linha de base que já existe e o que falta medir; nenhum número de economia é atribuído ao projeto sem esse contraste. Os ODS, se citados, com seu nome oficial e sua fonte. Vai depois do custo do problema ou da necessidade.
• Riscos: o que pode falhar e como é mitigado. Um cartão por risco, com sua classe como etiqueta (técnico, operacional, econômico, regulatório), "Mitigação" e "Se comprova em", que remete a uma fase ou porta de "O que deve demonstrar". A prosa inicial diz o risco principal e como o plano o detecta cedo. O que ainda não foi analisado (por exemplo, o encaixe regulatório) é declarado como risco aberto, com suas fontes quando houver. Vai logo antes de "O que deve demonstrar".
• Convite para colaborar: quais perfis são procurados, o que se oferece e o que se espera. Para documentos que são compartilhados.

Leitura por camadas. Comunica-se primeiro o mais importante, e cada camada seguinte aprofunda: quem apenas lê a primeira leva o essencial, e quem quer mais continua lendo. A ordem é de importância, não a de como se chegou às conclusões. Vale para todo o documento e para cada seção, que abre com sua conclusão (ver "Regras de redação") e deixa o detalhe para os cartões, os #### dobrados e os anexos.

Se o projeto precisar de uma seção que não está aqui, propõe-se ao autor antes de escrevê-la. Se for útil para outros projetos, é uma melhoria desta skill, que é da SF: não é anotada no projeto, diz-se em uma linha; na própria SF é do projeto.

Regras de redação

• Apenas a última decisão. O documento descreve o estado atual, sem histórico.
• Três classes de afirmação, sempre separadas: fatos publicados (com referência), objetivos de design do projeto (o que se deseja que faça) e suposições de cálculo (marcadas como ilustrativas). Um retângulo de escopo no início explica isso, e as etiquetas "publicado" e "design" lembram onde são comparadas.
• Todo número ou afirmação do domínio é contrastado com fontes antes de escrevê-lo, nunca de memória, e carrega sua referência na mesma frase. Para buscar na web, pedir permissão ao autor se não tiver dado.
• Cada evidência diz também o que não demonstra. "Leitura para o projeto", "Limite do argumento", "Implicação e alcance": o documento ganha credibilidade quando marca seus próprios limites.
• Compacto. Parágrafos de duas ou três frases, frases de cerca de 20 palavras ou menos, siglas explicadas na primeira vez. O núcleo é lido de uma vez; o detalhe extenso vai para os anexos.
• Sem enrolação. Nada sobre o próprio documento ("É preciso atualizar este documento…", "Este documento não contém…") nem obviedades: cada frase contribui algo do projeto.
• Cada seção abre com prosa que argumenta, como a primeira: cerca de dois ou três parágrafos, antes de qualquer cartão e sem subtítulos, com a conclusão da seção, os fatos que a sustentam com seu número e sua referência, e o que falta saber. Uma frase de apresentação ("Seis experiências permitem…") não basta. A tese ou a leitura de conjunto vai nessa prosa, não em um retângulo. Os cartões vêm depois e fornecem o detalhe que é consultado, sem repetir o argumento.
• Frases completas, não catálogo. Dentro de cada subseção (###) escreve-se com frases com verbo que explicam como algo funciona e por que, não enumerações sem verbo ("Identificação, inventário, rastreabilidade…"). As subseções são intituladas pela pergunta que respondem ("Como mantém o frio"), não com o padrão "Tema: subtema", e não são fragmentadas em #### partes de um parágrafo: o #### fica para o detalhe que é dobrado.
• Estrutura visível, sem quebrar a leitura: quando vão cartões, prosa, subseções, retângulos, tabelas ou listas, o negrito, os campos repetidos e a tipografia, em crear_documentos ("Quando usar cada recurso"). Em um fundacional, os cartões típicos são experiências, cenários, evidências, fases, portas, dimensões de uma comparação, fichas e os números-chave do produto; em um balanço, o que funcionou é contado em prosa e as deficiências vão em uma tabela com o que ocorre e seu estado.
• Sem códigos que o leitor ainda não conhece. Os códigos internos (S1, S2…) são usados apenas após a seção que os define e onde ajudam a cruzar referências. Antes, e na prosa que argumenta, diz-se com palavras ("o transporte ao domicílio e a conservação em casa").
• Toda afirmação-chave é justificada no mesmo local. Uma tese ou conclusão importante diz em que se baseia (os fatos do documento, com número e referência) e o que ainda não está demonstrado.
• Propostas, não imposições. "Propõe-se", "a avaliar", "decide quem corresponde".
• Respeita as sensibilidades do domínio. As regras do domínio do projeto estão nas regras de sua identidade (as mesmas que documento_vision lê).

Como trabalhar

1. Ler antes de propor: a visão do projeto, sua identidade e suas regras, a especificação se existir, o código ou o gêmeo se fornecerem números, e o material que o autor trouxer. Inventariar todos os argumentos do projeto. Um documento fundacional de produto reúne todos os argumentos que o projeto possui, e mais quando se compara com outros produtos: os dos demais documentos fundacionais, a visão, a especificação e o que já foi construído (um gêmeo digital, um protótipo, testes). Antes de escrever ou revisar, faz-se um inventário do que falta, com sua fonte e sua classe (fato publicado, objetivo de design, suposição ou avanço verificado apenas em simulação), e das contradições entre documentos, que são perguntadas ao autor antes de passar qualquer número afetado. O que foi construído é contado com seus limites declarados.
2. Propor o índice e as ferramentas: perguntar se o documento é um artefato para o projeto ou para o usuário e quais ferramentas leva (buscador, notas, "Leitura", dobrado, legenda, edição…), com a recomendação para esse destino, em uma única pergunta com opções; anotar a resposta no cabeçalho. Propor o índice: o núcleo, as seções opcionais que se aplicam e por que, os cenários candidatos com seu código e os números de portada. Deixar que o autor o refine antes de escrever.
3. Pesquisar as evidências que faltarem (com permissão para buscar), com sua fonte exata.
4. Escrever o .md com os recursos abaixo e gerar o .html. Antes de substituir uma versão, faz-se um backup em _respaldo/ (crear_documentos, "Respaldar").
5. Verificar (ver "Verificação") e entregar com um resumo: o que contém, o que é ilustrativo, quais evidências faltam e o que convém que um especialista valide.
6. Refinar com o autor. Cada correção geral é adicionada a seguir.

…