sdd-kb

SDD KB

In the first response of this skill, start with this line, only once: sdd-kb v2.0.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

Quick start

Turn what you know about a domain into material that any AI consults on demand — instead of you re-explaining everything in every conversation.

Define the domain: what goes in, what stays out — and ask whether it has a rule that applies per period (profile normative) and what the base date is.
Gather what you know, separating what is understanding from what is doing.
Check whether the project index exists; if it does not exist, create it.
Write the minimum viable: index.md + quick-reference.md + 1 concept + 1 recipe. In the normative profile, also fontes/CATALOGO.md, ≥ 1 rule in rules/ and the RULE_MAP.md generated.
Respect the size limits of each type.
Declare the source of each file and mark what has not been verified.
Register the domain in the index — mandatory step.
Ask the professional to review it — the one responsible for the content is them, not the AI.

Consult references/kb-protocol.md for the taxonomy and the rules, and references/sourcing.md for provenance. The templates are in assets/, and assets/example-kb/ is a complete example KB. For the normative profile, read references/normativo.md and use assets/example-kb-normativo/ as a model.

When to use / When not to use

Use it when the user needs the AI to know a context it does not have: laws, standards, manuals, normative instructions, internal policies, the office's process, a client's rules, a tool they master. Also use it when they notice they repeat the same explanations in every new conversation.

Recommended before starting an SDD flow — with the base ready, the following phases start from terrain already mapped instead of reconstructing it in every conversation. It is not a prerequisite: the method works without it.

Do not use it to document a software project under construction — for that there are the artifacts of the SDD flow. Do not use it to copy public documentation: the KB stores what you learned about that, mainly what the documentation does not say.

Required data

Minimum input:

the domain to document and what the user already knows about it.

Optional inputs:

documentation, manuals or reference standards;
real examples of how the process happens today;
a previous KB to expand;
access to the project to write the files.

Do not require filesystem or internet access. Without access to the project, deliver the files in the chat.

Mandatory output assets

The templates in assets/ are output assets: always use them to generate the final files, instead of rebuilding the memory structure.

Template	Generates
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` of the project, on the first run

In the normative profile, the following are added:

Template	Generates
assets/INDEX_NORMATIVO_TEMPLATE.md	`index.md` (in place of `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`

Step-by-step procedure

1. Delimit the domain

Define the scope with the user: which subject, and especially what is left out. A good domain is one in which you can say "this is not here" without hesitating.

A domain that is too large becomes material that no one finishes writing. When in doubt, start smaller — splitting later is easy; an unfinished domain serves no one.

Then ask — with these words or equivalents:

Does this domain have a rule that is valid for a period — law, rate, deadline, tax document layout? If so, what is the base date of this revision (the date on which the content is checked against the sources)?

Yes → profile normativo: every dated statement gains validity, every source enters the catalog with tier and SHA-256, and conflicts between sources are recorded. Read references/normativo.md before writing.
No → profile geral (the default): the procedure continues as below, without the normative items.

A tax rule is not true: it is true for a period. Without validity, the file that is correct today becomes wrong next year without changing a single line.

2. Separate what is understanding from what is doing

Gather from the user what they know and classify each piece by the question that resolves everything:

After reading this, will the person UNDERSTAND something, or will they DO something?

Understand → concept
Do → pattern

Pay attention to the common mistake, which has a known direction: writing as a concept what is actually a recipe. The symptom is a text that explains very well and does not allow executing anything. When the user describes a sequence of actions, that is pattern — write the steps.

3. Check (or create) the project index

Look for the project's KB index — typically _index.yaml at the root of the knowledge bases folder.

If it does not exist, create it from assets/KB_INDEX_TEMPLATE.yaml. Never assume that it is already there and never fail because of that: the missing index is the normal state the first time.

4. Write the minimum viable

Produce exactly this structure:

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

Four files. Each one according to the corresponding template.

In the profile normative, the minimum grows:

{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/ (values per validity period) and casos/ (input → expected result) are included when the domain has that material. Did a rule change on a date? Close the old one with ate: and create another — the past is not edited. A domain with only concepts does not help to execute; one with only recipes does not help to decide when to apply them — that is why both are mandatory from the start.

Writing more than one concept or recipe is welcome when the material exists. The minimum is a floor, not a ceiling.

5. Respect the size limits

Type	Limit
`quick-reference.md`	100 lines
`concepts/*.md`	150 lines
`patterns/*.md`	200 lines

Explain to the user why they exist, when they ask or when a file exceeds the limit: the AI loads the file along with all the rest of the context, and material that is too large does not generate a visible error — it starts to ignore parts silently. A 400-line file is not more complete; it is less reliable.

Exceeded the limit? There are almost always two subjects in the file. Separating is better than summarizing.

6. Declare the source

Each file says where what is written came from: documentation, standard, or own practice — all legitimate. And what has not been verified is marked as unverified, in one sentence.

An assumption written as fact is the most costly error in a KB: it cannot be distinguished from the rest and spreads with confidence. See references/sourcing.md.

In the normative profile, the source has tier (Constitution > complementary law > law > decree > normative act > technical act > consultation solution > doctrine > own practice). A rule supported only by doctrine or own practice remains nao-confirmado. And the file's date and name do not prove validity: the catalog records version, capture date, and SHA-256 (python3 scripts/kb_normativo.py sha fontes/<arquivo>).

Never include data of real people, passwords, or keys. Fictitious examples work just as well.

7. Register the domain in the index

Mandatory step, and the most forgotten one. Add the domain's block in _index.yaml, with name, description, path, and date.

A domain that exists in a folder but is not in the index is invisible: neither the person nor the AI discovers that it exists. In a real collection of 43 domains, 4 were in this situation — entire bases that no one found.

8. Deliver

If there is a writable project filesystem, write the files into the domain's folder, without silently overwriting existing material.

If not if there is an accessible filesystem, deliver all files in the chat, in separate blocks identified by path, and close with these three pieces of information, in this order:

that the files were not written;
the suggested folder structure (with the file names);
what to do with them — save them in the indicated structure and point the AI to that folder in future conversations.

Never fail silently or imply that it wrote.

9. Close with the professional's review (mandatory)

Before considering the base ready, make it explicit that the review of the content is the user's, not yours:

Review each file before using this base for real. I organized and wrote it, but whoever answers for what is written is you — especially where there is law, standard, policy or deadline. Check what was recorded and correct what is not faithful to the source.

This is not a formality. A knowledge base is consulted precisely when the person does not know — that is, at the moment when they have no way of realizing that the information is wrong. An error here does not stay isolated: it is repeated with confidence, by you and by the AI, and starts to guide decisions. When the domain involves a standard or obligation, the cost of the error is the professional's.

Name the passages that most need checking: numbers, deadlines, amounts, conditions for applying a rule, and everything that was marked as unverified (step 6).

If the user says they will not review now, record in the index.md that the base is pending review — better a base marked as unchecked than one that appears to have authority it does not yet have.

In the normative profile, the notice also goes in the index.md, in writing: this base is not tax, accounting or legal advice. And a base pending review should not feed software: validate_kb.py --strict rejects the normative domain marked as PENDENTE DE REVISÃO — run it before any skill, agent or system consumes the base.

10. Show how to use it from now on

Close by saying, in two or three lines, how the user will consult this: point the AI to the domain folder at the start of the conversation, or ask it to read the index.md before answering about the subject.

A KB that the user does not know how to activate changes nothing in their day to day.

Validations and quality checklist

Before declaring it complete, check:

Domain delimited, with what is left out explicit in the index.md.
Each file passed the "understand or do" test.
No recipe was written as a concept.
The four files of the minimum viable exist.
No file exceeds the limit of its type.
Each file declares the source.
The unverified is marked as such.
No data of a real person, password or key.
The domain is registered in the index.
None {placeholder} remained.
The user was warned that the content review is theirs, with the critical excerpts pointed out.
Unreviewed base is marked as pending review in the index.md.
The user knows how to consult the KB in future conversations.

In the normative profile, also:

Base date in index.md, section "Conflicts between sources" and the notice "this is not tax advice".
"Applies to:" in the header of each concept and recipe.
Each rule with validity (de, and ate when ended), source cataloged with locator and honest status.
Each source in the catalog with tier, version, capture date and, when the file is in fontes/, SHA-256.
RULE_MAP.md regenerated after the last change in rules/.

When there is a filesystem, the script scripts/validate_kb.py mechanically checks part of this:

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

Output PASS with code 0; problems listed with code 2. Lines WARN: (base pending review, old base date, general domain that looks normative) do not change the exit code. The profile comes from the domain registration in the _index.yaml.

Exception handling

Domain too large: propose a smaller scope and name the neighboring domains that are left for later. Record in the index.md what is not covered.
User only has concepts, no recipe: ask what they do with that knowledge. Almost always the recipe exists and was not verbalized.
User only has recipes: ask why the steps are like that. The concept is usually in the answer.
Project index does not exist: create it from the template. This is the normal state the first time, not an error.
A KB for this domain already exists: expand the existing one — new concepts and recipes in the same directories — instead of creating a parallel domain.
File exceeded the limit: look for the two subjects inside it and separate them. Summarize only when it is genuinely a single subject.
No filesystem: deliver everything in the chat with the three pieces of information from step 8.
Material with real data: replace with an equivalent fictitious example before writing.
Two sources say different things: record the conflict in the rule (conflito_com) and in the index.md, state what the base adopts and why. Never choose silently.
Rule changed: close the old rule with ate: and create another from the new date; regenerate the RULE_MAP.md.
Software will consume the base: --strict before; the software references rules by id and sources by SHA-256, without copying concepts (see "KB consumed by software" in references/normativo.md).

Examples

Office process Quero que a IA saiba como funciona o fechamento mensal aqui.

Define the scope (accounting close, without tax assessment), separate the concept that explains the revenue decisions from the one that carries out the checks, write the four files, record.

Tool the user has mastery of Uso essa ferramenta há anos e toda vez preciso reexplicar pra IA.

Elicit what they know that the documentation does not say — pitfalls, what goes wrong, when not to use it. It is exactly the material the AI lacks.

Legislation with effective dates Quero uma base da Reforma Tributária para alimentar meu validador de NF-e.

Regulatory profile, base date asked in step 1. Each rule of the technical note becomes a file in rules/ with effective date and page; the TN, the complementary law and the articles consulted enter the catalog with a tier; the "2026 crossed out, 2027 written over it" becomes a recorded conflict. kb_normativo.py rule-map generates the RULE_MAP.md (the validate_kb.py only checks that it did not drift), and the NF-e validator copies this map and references each rule by id.

Scattered knowledge Tenho anotações espalhadas sobre isso.

Read the material, classify each piece into understand/do, and show the user what was left out of the scope before writing.

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

Deliver the four files in the chat, identified by path, with the folder structure and the instruction on how to point the AI to them later.

Next Step

Knowledge base created. Point the AI to the domain folder at the start of the next conversations on the subject.

Part of SDD Open by RDD — https://github.com/robertodiasduarte/sdd-open