Identificar componentes de conhecimento

Identificar é o passo em que o pipeline lê a sua fonte e propõe o que vale a pena escrever. Cada comando procura um tipo de componente de conhecimento (knowledge component) e escreve uma lista de candidatos no seu disco. Nada chega ao Fito ainda — gerar e publicar vêm depois.

Esta página cobre os três comandos de identificação, as flags deles e a lista que eles escrevem. Ela supõe que você tem algo para ler: uma árvore de código-fonte ou documentação buscada. Cada comando também consegue fazer a ingestão para você na entrada.

Os três comandos

Um comando por tipo de componente, e cada um escreve na sua própria pasta:

Comando	Procura	Escreve na pasta, por padrão
/fito-identify-domain-concepts	Concepts	./output/2-identify/domain_concepts/
/fito-identify-execution-facts	Execution facts	./output/2-identify/execution_facts/
/fito-identify-usage-scenarios	Usage scenarios	./output/2-identify/usage_scenarios/

Cada comando escreve dois arquivos na sua pasta. Para concepts, eles são o domain_concepts.json, a lista de candidatos que o passo de geração lê, e o domain_concepts.md, os mesmos candidatos em um resumo que você consegue ler. Os outros dois comandos escrevem o mesmo par, com os nomes execution_facts e usage_scenarios.

Os três compartilham todas as flags. Rode os três para cobrir uma tecnologia, ou só os que você precisa.

Antes de começar

• Uma sessão do pi em um diretório de trabalho seu, com o Fito instalado nele. Veja Preparar um diretório de trabalho.
• Um provedor de LLM configurado no pi, e o pacote pi-subagents instalado. Cada comando entrega a leitura a uma persona trabalhadora, por esse pacote, no seu próprio modelo.
• A tecnologia e a linha principal que você vai informar, já provisionadas. Veja Provisionar uma tecnologia.

Você não precisa estar logado no Fito. Toda chamada que a identificação faz ao servidor do Fito é uma leitura pública.

Identificar candidatos

1. Decida o que o comando lê. Passe --source <path> para um projeto no seu disco, --fetch para uma lista de URLs, ou nada para ler o que um passo anterior já ingeriu.

2. Rode o comando. Para uma ferramenta:

   /fito-identify-domain-concepts Javalin --technology javalin --technology-version 7 --source ~/code/my-javalin-app

   Para uma prática, cuja linha principal é a numeração do próprio Fito:

   /fito-identify-domain-concepts "Hexagonal Architecture" --technology hexagonal --technology-version 1

   O primeiro argumento é o nome do assunto. O --technology é o slug dele no Fito, e o --technology-version é a linha principal (major line) a que todo candidato precisa se aplicar.

3. Rode os outros dois comandos com os mesmos argumentos, se quiser esses tipos também. Com --source, cada um remonta o bundle da árvore, o que é barato.

4. Leia o resumo que o comando repassa. Ele diz quantos candidatos encontrou, e quantos deles já existem no Fito.

5. Revise os candidatos no resumo .md antes de gerar. A geração escreve todo candidato novo, a menos que você escolha alguns — veja Flags da geração.

Confirme que deu certo: os dois arquivos estão na pasta da tabela acima, e todo candidato na lista JSON carrega um valor already_exists.

Flags

Flag	Obrigatória	Padrão	O que faz
<tool-name>	Sim	—	O nome do assunto, como primeiro argumento. Use aspas num nome com espaços
--technology <slug>	Não	O nome, em minúsculas, com espaços trocados por hifens	A tecnologia a que os candidatos pertencem
--technology-version <slug>	Sim	—	A linha principal a que os candidatos se aplicam — 7 para uma ferramenta, 1 para uma prática
--description "<text>"	Não	—	Um relato curto do que o assunto faz, para ajudar o identificador a achar os domínios dele
--source <path>	Não	—	Monta o bundle dessa árvore de código-fonte e o lê. Vence o --fetch
--fetch	Não	—	Roda o /fito-fetch-urls-content antes
--urls <file>	Não	urls.txt	A lista de URLs do --fetch
--docs <path>	Não	./output/1-ingest/extracted_links_content/	Uma pasta já ingerida para ler
--output <path>	Não	A pasta da tabela acima	A pasta em que os dois arquivos são escritos. Os nomes deles nunca mudam

Passe --technology quando o nome e o slug diferem

Quando você deixa o --technology de fora, o comando deriva o slug do nome. Javalin dá javalin, que está certo. "Hexagonal Architecture" dá hexagonal-architecture, e a tecnologia no Fito é hexagonal — então o comando não encontra essa tecnologia e para.

Passe --technology sempre que o nome que você digita não for o slug.

Qual identificador roda

O comando lê do Fito o tipo (kind) da tecnologia, e o tipo escolhe o trabalhador: um identificador de tool ou um identificador de practice, um par para cada tipo de componente. Nenhuma flag escolhe, e você nunca nomeia um. Declare a tecnologia, e o identificador certo vem junto.

De onde vem a entrada

O comando pega a primeira destas opções que se aplica:

1. --source — monta o bundle da árvore e lê o bundle. O --fetch é ignorado.
2. --fetch — busca a lista do --urls para a pasta da documentação buscada, e lê essa pasta.
3. --docs — lê a pasta que ele indica, ou a pasta da documentação buscada quando não indica nenhuma.

Dentro de um checkout de caso, um comando que não recebeu nenhuma das três oferece seguir com --source ., depois de verificar que o checkout é seu para criar. Veja Ingerir um caso que você está criando.

O que a lista de candidatos guarda

Cada candidato é comparado com o que o Fito já tem para a linha principal declarada, e carrega a resposta:

• already_exists: true, com canonical_id nomeando o id de referência (reference id) do componente publicado — a ideia já está escrita.
• already_exists: false, com canonical_id: null — a ideia é nova.

A comparação vale para a linha principal. Um componente publicado só em outra linha aparece como novo, porque na linha que você declarou ele não existe.

O passo de geração pula os candidatos que já existem, então é este valor que impede você de escrever o mesmo componente duas vezes.

Quando o comando para

Mensagem	O que significa	O que fazer
Please provide the tool name. Usage: …	Falta o primeiro argumento	Acrescente o nome do assunto
Please provide the Fito technology version the identified components apply to with --technology-version <slug> …	Falta a linha principal	Acrescente --technology-version
The Fito vocabulary holds no <slug> technology, so there is nothing to ground candidates against. …	O slug não existe no Fito	Provisione a tecnologia, ou corrija um --technology digitado errado
No source found at <docs-path>. …	Nada foi ingerido, e a pasta do docs está vazia ou não existe	Passe --source ou --fetch, ou aponte o --docs para uma pasta preenchida

Um slug digitado errado não é motivo para provisionar. Provisionar o erro de digitação cria uma segunda tecnologia, independente, ao lado da verdadeira, e os componentes publicados contra as duas caem em registros diferentes.

Um servidor fora do ar não é uma tecnologia ausente. Quando a consulta falha por qualquer motivo que não seja não-encontrado — servidor inalcançável, erro do servidor —, o comando relata a falha como ela veio e para, sem a mensagem de provisionar primeiro.

O mesmo vale dentro do identificador. Quando a comparação com o Fito falha para um candidato, ele para e relata a falha, em vez de marcar o candidato como novo.

O que vem a seguir

• Gerar e publicar componentes — escreva cada candidato novo, e publique.
• Componentes de conhecimento — para que servem os três tipos.