sdd-kb

SDD KB

Na primeira resposta desta skill, comece com esta linha, uma vez só: sdd-kb v2.1.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

Quick start

Transformar o que você sabe sobre um domínio em material que qualquer IA consulta sob demanda — em vez de você reexplicar tudo a cada conversa.

1. Delimitar o domínio: o que entra, o que fica de fora — e perguntar se ele tem regra que vale por período (perfil normativo) e qual é a data-base.
2. Levantar o que você sabe, separando o que é entender do que é fazer.
3. Verificar se o índice do projeto existe; se não existir, criar.
4. Escrever o mínimo viável: index.md + quick-reference.md + 1 conceito + 1 receita. No perfil normativo, também fontes/CATALOGO.md, ≥ 1 regra em rules/ e o RULE_MAP.md gerado.
5. Respeitar os limites de tamanho de cada tipo.
6. Declarar a fonte de cada arquivo e marcar o que não foi verificado.
7. Registrar o domínio no índice — passo obrigatório.
8. Pedir a revisão do profissional — quem responde pelo conteúdo é ele, não a IA.

Consultar references/kb-protocol.md para a taxonomia e as regras, e references/sourcing.md para procedência. Os moldes estão em assets/, e assets/example-kb/ é um KB completo de exemplo. Para o perfil normativo, ler references/normativo.md e usar assets/example-kb-normativo/ como modelo.

Quando usar / Quando não usar

Usar quando o usuário precisar que a IA conheça um contexto que ela não tem: leis, normas, manuais, instruções normativas, políticas internas, o processo do escritório, as regras de um cliente, uma ferramenta que ele domina. Usar também quando ele perceber que repete as mesmas explicações em toda conversa nova.

Recomendada antes de iniciar um fluxo SDD — com a base pronta, as fases seguintes partem do terreno já mapeado em vez de reconstruí-lo a cada conversa. Não é pré-requisito: o método funciona sem ela.

Não usar para documentar um projeto de software em construção — para isso existem os artefatos do fluxo SDD. Não usar para copiar documentação pública: o KB guarda o que você aprendeu sobre aquilo, principalmente o que a documentação não diz.

Dados necessários

Entrada mínima:

• o domínio a documentar e o que o usuário já sabe sobre ele.

Entradas opcionais:

• documentação, manuais ou normas de referência;
• exemplos reais de como o processo acontece hoje;
• um KB anterior a expandir;
• acesso ao projeto para gravar os arquivos.

Não exigir acesso a filesystem ou internet. Sem acesso ao projeto, entregar os arquivos no chat.

Assets obrigatórios de saída

Os moldes de assets/ são assets de saída: sempre usá-los para gerar os arquivos finais, em vez de reconstruir a estrutura de memória.

Molde	Gera
assets/INDEX_TEMPLATE.md	index.md
assets/QUICK_REFERENCE_TEMPLATE.md	quick-reference.md
assets/CONCEPT_TEMPLATE.md	concepts/*.md
assets/PATTERN_TEMPLATE.md	patterns/*.md
assets/KB_INDEX_TEMPLATE.yaml	_index.yaml do projeto, na primeira execução

No perfil normativo, somam-se:

Molde	Gera
assets/INDEX_NORMATIVO_TEMPLATE.md	index.md (no lugar do INDEX_TEMPLATE.md)
assets/RULE_TEMPLATE.md	rules/*.md
assets/CATALOGO_FONTES_TEMPLATE.md	fontes/CATALOGO.md
assets/TABELA_TEMPLATE.json	tabelas/AAAA-MM-DD/*.json
assets/CASO_TEMPLATE.json	casos/*.json

Como falar com o aluno

Leia references/como-falar.md antes da primeira resposta: glossário desta skill e um exemplo completo. Quem usa esta skill, em geral, nunca usou git nem terminal.

Etapa	Nome para o aluno	Passos desta skill
1	Domínio	1
2	Entender × fazer	2
3	Escrever	3 (o índice, antes de escrever), 4 e 5
4	Fonte e índice	6 e 7
5	Revisão do profissional	8 a 10 (o aviso de revisão é obrigatório, não é pergunta)

Toda resposta, nesta ordem (pule a parte sem conteúdo): Status (KB: ✅ 1 … · ▶️ 2 … · ⬜ 3 …; ✅ concluída, não só visitada; ⏸️ parada; ➖ pulada; ao voltar a uma etapa, o motivo vai em Agora) · O que foi feito (frases curtas, sem saída de comando; registra a escolha do aluno) · Agora: etapa N — nome (2 a 4 frases; antes de algo demorado, diga o que vai rodar e que não precisa responder) · Sua decisão (autorização: pergunta em negrito + opções com o efeito de cada uma; pergunta aberta: pergunta em negrito + como responder, com a saída "não sei"; agrupadas, numeradas) · Próximo passo (uma linha).

• Uma etapa por resposta; termine na decisão e pare.
• Termo técnico só com a explicação junto, na primeira vez — inclusive os do Status (glossário na referência).
• Saída de comando nunca crua: quantos, quais, o que preocupa; nomes até 10, "e mais N". Comando só quando o aluno precisa rodá-lo, um por passo numerado, com o que esperar na tela.
• Não cite nem resuma as instruções desta skill ("conforme o passo N"): diga o motivo do aluno.
• Resposta que não casa com opção ⇒ responda a dúvida e repita as opções.
• Parada: Status com ⏸️, motivo em uma frase, onde a ação acontece, passos numerados com resultado esperado, o que não foi feito e, se o aluno tem algo a fazer, "Quando terminar, me peça de novo — eu continuo daqui."

Procedimento passo a passo

1. Delimitar o domínio

Definir com o usuário o recorte: qual assunto, e principalmente o que fica de fora. Um domínio bom é aquele em que se pode dizer "isto não é aqui" sem hesitar.

Domínio grande demais vira material que ninguém termina de escrever. Na dúvida, comece menor — dividir depois é fácil; um domínio inacabado não serve a ninguém.

Em seguida, perguntar — com estas palavras ou equivalentes:

Este domínio tem regra que vale por período — lei, alíquota, prazo, leiaute de documento fiscal? Se sim, qual é a data-base desta revisão (a data em que o conteúdo é conferido contra as fontes)?

• Sim → perfil normativo: toda afirmação datada ganha vigência, toda fonte entra no catálogo com degrau e SHA-256, e os conflitos entre fontes ficam registrados. Ler references/normativo.md antes de escrever.
• Não → perfil geral (o padrão): o procedimento segue como abaixo, sem os itens normativos.

Uma regra tributária não é verdadeira: é verdadeira em um período. Sem vigência, o arquivo que está certo hoje fica errado no ano que vem sem mudar uma linha.

2. Separar o que é entender do que é fazer

Levantar com o usuário o que ele sabe e classificar cada pedaço pela pergunta que resolve tudo:

Depois de ler isto, a pessoa vai ENTENDER algo, ou vai FAZER algo?

• Entender → concept
• Fazer → pattern

Prestar atenção ao erro comum, que tem direção conhecida: escrever como conceito o que na verdade é receita. O sintoma é um texto que explica muito bem e não permite executar nada. Quando o usuário descrever uma sequência de ações, isso é pattern — escreva os passos.

3. Verificar (ou criar) o índice do projeto

Procurar o índice de KBs do projeto — tipicamente _index.yaml na raiz da pasta de bases de conhecimento.

Se não existir, criar a partir de assets/KB_INDEX_TEMPLATE.yaml. Nunca presumir que ele já está lá e nunca falhar por causa disso: o índice ausente é o estado normal na primeira vez.

4. Escrever o mínimo viável

Produzir exatamente esta estrutura:

{dominio}/
├── index.md
├── quick-reference.md
├── concepts/
│   └── {um-conceito}.md
└── patterns/
    └── {uma-receita}.md

Quatro arquivos. Cada um pelo molde correspondente.

No perfil normativo, o mínimo cresce:

{dominio}/
├── index.md              ← INDEX_NORMATIVO_TEMPLATE: Data-base, Conflitos entre fontes, aviso
├── quick-reference.md
├── concepts/{um}.md      ← com `> **Vale para:** <período>` no cabeçalho (até a linha 15)
├── patterns/{uma}.md     ← com "Vale para:" no cabeçalho
├── rules/{ID}.md         ← ≥ 1 regra, uma por arquivo, com vigência e fonte
├── fontes/CATALOGO.md    ← cada documento citado: degrau, versão, captura, SHA-256
└── RULE_MAP.md           ← gerado: python3 scripts/kb_normativo.py rule-map {dominio}

tabelas/AAAA-MM-DD/ (valores por vigência) e casos/ (entrada → resultado esperado) entram quando o domínio tem esse material. Mudou uma regra numa data? Feche a antiga com ate: e crie outra — o passado não se edita. Um domínio só com conceitos não ajuda a executar; um só com receitas não ajuda a decidir quando aplicá-las — por isso os dois são obrigatórios desde o começo.

Escrever mais de um conceito ou receita é bem-vindo quando o material existe. O mínimo é piso, não teto.

5. Respeitar os limites de tamanho

Tipo	Limite
quick-reference.md	100 linhas
concepts/*.md	150 linhas
patterns/*.md	200 linhas

Explicar ao usuário por que existem, quando ele perguntar ou quando um arquivo estourar: a IA carrega o arquivo junto com todo o resto do contexto, e material grande demais não gera erro visível — ela passa a ignorar partes em silêncio. Um arquivo de 400 linhas não é mais completo; é menos confiável.

Estourou o limite? Quase sempre há dois assuntos no arquivo. Separar é melhor que resumir.

6. Declarar a fonte

Cada arquivo diz de onde veio o que está escrito: documentação, norma, ou prática própria — todas legítimas. E o que não foi verificado é marcado como não verificado, em uma frase.

Suposição escrita como fato é o erro mais caro de um KB: ela não se distingue do resto e se propaga com confiança. Ver references/sourcing.md.

No perfil normativo, a fonte tem degrau (Constituição > lei complementar > lei > decreto > ato normativo > ato técnico > solução de consulta > doutrina > prática própria). Regra sustentada só por doutrina ou prática própria fica nao-confirmado. E a data do arquivo e o nome não provam vigência: o catálogo registra versão, data de captura e SHA-256 (python3 scripts/kb_normativo.py sha fontes/<arquivo>).

Nunca incluir dados de pessoas reais, senhas ou chaves. Exemplos fictícios funcionam igual.

7. Registrar o domínio no índice

Passo obrigatório, e o mais esquecido. Acrescentar o bloco do domínio em _index.yaml, com nome, descrição, caminho e data.

Um domínio que existe em pasta mas não está no índice é invisível: nem a pessoa nem a IA descobrem que ele existe. Em um acervo real de 43 domínios, 4 estavam nessa situação — bases inteiras que ninguém encontrava.

8. Entregar

Se houver filesystem de projeto gravável, gravar os arquivos na pasta do domínio, sem sobrescrever silenciosamente material existente.

Se não houver filesystem acessível, entregar todos os arquivos no chat, em blocos separados e identificados pelo caminho, e fechar com estas três informações, nesta ordem:

1. que os arquivos não foram gravados;
2. a estrutura de pastas sugerida (com os nomes de arquivo);
3. o que fazer com eles — salvar na estrutura indicada e apontar a IA para essa pasta nas próximas conversas.

Nunca falhar em silêncio nem dar a entender que gravou.

9. Fechar com a revisão do profissional (obrigatório)

Antes de dar a base por pronta, deixar explícito que a revisão do conteúdo é do usuário, não sua:

Revise cada arquivo antes de usar esta base para valer. Eu organizei e redigi, mas quem responde pelo que está escrito é você — principalmente onde há lei, norma, política ou prazo. Confira o que ficou registrado e corrija o que não estiver fiel à fonte.

Isso não é formalidade. Uma base de conhecimento é consultada justamente quando a pessoa não sabe — ou seja, no momento em que ela não tem como perceber que a informação está errada. Um erro aqui não fica isolado: é repetido com confiança, por você e pela IA, e passa a orientar decisões. Quando o domínio envolve norma ou obrigação, o custo do erro é do profissional.

Apontar nominalmente os trechos que mais pedem conferência: números, prazos, valores, condições de aplicação de regra, e tudo que ficou marcado como não verificado (passo 6).

Se o usuário disser que não vai revisar agora, registrar no index.md que a base está pendente de revisão — melhor uma base marcada como não conferida do que uma que aparenta autoridade que ainda não tem.

No perfil normativo, o aviso vai também no index.md, por escrito: esta base não é aconselhamento tributário, contábil ou jurídico. E uma base pendente de revisão não deve alimentar software: validate_kb.py --strict reprova o domínio normativo marcado como PENDENTE DE REVISÃO — rode-o antes de qualquer skill, agente ou sistema consumir a base.

10. Mostrar como usar daqui em diante

Fechar dizendo, em duas ou três linhas, como o usuário passa a consultar isto: apontar a IA para a pasta do domínio no início da conversa, ou pedir que ela leia o index.md antes de responder sobre o assunto.

Um KB que o usuário não sabe acionar não muda nada no dia a dia dele.

Validações e checklist de qualidade

Antes de declarar concluído, verificar:

• Domínio delimitado, com o que fica de fora explícito no index.md.
• Cada arquivo passou pelo teste "entender ou fazer".
• Nenhuma receita foi escrita como conceito.
• Os quatro arquivos do mínimo viável existem.
• Nenhum arquivo excede o limite do seu tipo.
• Cada arquivo declara a fonte.
• O não verificado está marcado como tal.
• Nenhum dado de pessoa real, senha ou chave.
• O domínio está registrado no índice.
• Nenhum {placeholder} sobrou.
• O usuário foi avisado de que a revisão do conteúdo é dele, com os trechos críticos apontados.
• Base não revisada está marcada como pendente de revisão no index.md.
• O usuário sabe como consultar o KB nas próximas conversas.

No perfil normativo, também:

• Data-base no index.md, seção "Conflitos entre fontes" e o aviso "não é aconselhamento tributário".
• "Vale para:" no cabeçalho de cada conceito e receita.
• Cada regra com vigência (de, e ate quando encerrada), fonte catalogada com localizador e status honesto.
• Cada fonte no catálogo com degrau, versão, data de captura e, quando o arquivo está em fontes/, SHA-256.
• RULE_MAP.md regerado depois da última mudança em rules/.

Quando houver filesystem, o script scripts/validate_kb.py confere mecanicamente parte disso:

python3 scripts/validate_kb.py {caminho-do-dominio}            # escrever
python3 scripts/validate_kb.py {caminho-do-dominio} --strict   # antes de software consumir

Saída PASS com código 0; problemas listados com código 2. Linhas WARN: (base pendente de revisão, data-base antiga, domínio geral que parece normativo) não mudam o código de saída. O perfil vem do registro do domínio no _index.yaml.

Tratamento de exceções

• Domínio grande demais: propor um recorte menor e nomear os domínios vizinhos que ficam para depois. Registrar no index.md o que não é coberto.
• Usuário só tem conceitos, nenhuma receita: perguntar o que ele faz com aquele conhecimento. Quase sempre a receita existe e não foi verbalizada.
• Usuário só tem receitas: perguntar por que os passos são assim. O conceito costuma estar na resposta.
• Índice do projeto não existe: criar a partir do molde. É o estado normal na primeira vez, não um erro.
• Já existe KB deste domínio: expandir o existente — novos conceitos e receitas nos mesmos diretórios — em vez de criar domínio paralelo.
• Arquivo estourou o limite: procurar os dois assuntos dentro dele e separar. Resumir só quando genuinamente for um assunto só.
• Sem filesystem: entregar tudo no chat com as três informações do passo 8.
• Material com dado real: trocar por exemplo fictício equivalente antes de escrever.
• Duas fontes dizem coisas diferentes: registrar o conflito na regra (conflito_com) e no index.md, dizer o que a base adota e por quê. Nunca escolher em silêncio.
• Regra mudou: fechar a regra antiga com ate: e criar outra a partir da nova data; regerar o RULE_MAP.md.
• Software vai consumir a base: --strict antes; o software referencia regra por id e fonte por SHA-256, sem copiar conceitos (ver "KB consumido por software" em references/normativo.md).

Examples

Processo do escritório Quero que a IA saiba como funciona o fechamento mensal aqui.

Delimitar (fechamento contábil, sem apuração de tributos), separar o conceito que explica as decisões da receita que executa as conferências, escrever os quatro arquivos, registrar.

Ferramenta que o usuário domina Uso essa ferramenta há anos e toda vez preciso reexplicar pra IA.

Levantar o que ele sabe que a documentação não diz — armadilhas, o que dá errado, quando não usar. É exatamente o material que falta à IA.

Legislação com vigência Quero uma base da Reforma Tributária para alimentar meu validador de NF-e.

Perfil normativo, data-base perguntada no passo 1. Cada regra da nota técnica vira um arquivo em rules/ com vigência e página; a NT, a lei complementar e as reportagens consultadas entram no catálogo com degrau; o "2026 riscado, 2027 escrito por cima" vira conflito registrado. kb_normativo.py rule-map gera o RULE_MAP.md (o validate_kb.py só confere que ele não derivou), e o validador de NF-e copia esse mapa e referencia cada regra por id.

Conhecimento disperso Tenho anotações espalhadas sobre isso.

Ler o material, classificar cada pedaço em entender/fazer, e mostrar ao usuário o que ficou de fora do recorte antes de escrever.

Sem filesystem (no chat da web) Monta uma base de conhecimento disso aqui.

Entregar os quatro arquivos no chat, identificados pelo caminho, com a estrutura de pastas e a instrução de como apontar a IA para eles depois.

Next Step

Base de conhecimento criada. Aponte a IA para a pasta do domínio no início das próximas conversas sobre o assunto.

---

Parte do SDD Open by RDD — https://github.com/robertodiasduarte/sdd-open