Criar uma competência

Uma competência (competence) nomeia uma capacidade permanente que uma tecnologia (technology) exige, e cada um dos elementos (competence elements) dela é um componente de conhecimento (knowledge component) que o Fito já guarda. Esta página mostra como registrar uma pelo terminal, como editar o nome e a descrição dela e como apagá-la.

Esta página é para quem cria casos, já publicou componentes de conhecimento e quer agrupá-los nas capacidades que um aprendiz desenvolve. Ela não explica o que é uma competência, nem como a proficiência (proficiency) de um aprendiz nela é calculada — para isso, veja Competências e objetivos de aprendizagem.

Onde este passo fica

Uma competência vem depois da cadeia de conhecimento, porque todo elemento tem de apontar para um componente que já está vivo:

1. Provisione a tecnologia e a linha principal (major line) dela.
2. Identifique, gere e publique os componentes.
3. Crie as competências que esses componentes formam — esta página.

Um caso não precisa de competência. Um caso aponta para componentes de conhecimento, como objetivos de aprendizagem (learning objectives) e pré-requisitos (prerequisites), então você pode criar um caso sem este passo.

Antes de começar

• Uma sessão do pi no seu diretório de criação — veja Preparar um diretório de trabalho.
• Um login no Fito pelo terminal. Toda escrita é autenticada — rode o /fito-login se ainda não rodou.
• Para criar uma competência, você é curador (curator) ou admin. Não existe papel de curador para pedir: a partir do momento em que você é dono de um caso, em qualquer status, você é curador. Veja Trabalhar o catálogo de curadoria.
• A tecnologia, provisionada na linha principal para a qual você cria, e todo componente de que a competência precisa, já publicado.

Criar uma competência

1. Rode o comando com a tecnologia e a linha principal dela:

   /fito-create-or-update-competence --technology javalin@7

   Troque javalin@7 pelo seu <slug>@<version>. O comando confere se o Fito guarda tanto a tecnologia quanto essa linha principal, e para quando falta uma das duas.

2. Leia o que a tecnologia já exige. O comando lista cada competência por nome, id, descrição e elementos, com as subcompetências dela aninhadas embaixo. Quando nenhuma delas é a competência que você tem em mente, diga isso ao comando: esta execução é uma criação. Quando uma delas é, escolha-a e siga Editar o nome ou a descrição.

3. Escolha os elementos. O comando lista os componentes vivos na linha principal declarada, cada um por nome e resumo, e lê de volta cada componente que você escolhe antes de ele virar um elemento. Os elementos mantêm a ordem que você definir, e um componente aparece uma vez só.

4. Revise o registro e confirme. O comando mostra o nome, a descrição e os elementos em ordem, cada um pelo nome do seu componente. Nada é escrito até você confirmar.

   • Uma descrição null é desconhecida, não vazia. Acrescente uma quando puder: outra pessoa que cria casos a lê para decidir se esta competência é a que ela queria.
   • Leia antes Três regras que uma criação nunca avisa. Nenhuma delas pode ser desfeita depois da escrita.

   O registro confirmado vai para ./output/4-competence/competence.yaml.

5. Leia o id que a escrita imprime:

   ✓ Created competence "<name>" (<id>) ← <payload-file>

   Guarde o id. Uma edição e uma exclusão endereçam a competência por ele.

A lista de competências da tecnologia agora traz a competência, para todo mundo que cria contra a mesma tecnologia e todo aprendiz que a navega.

Três regras que uma criação nunca avisa

O Fito aceita cada uma delas sem dizer nada, então elas só aparecem depois de já terem custado caro:

• Os elementos ficam congelados. Depois de uma criação, nenhum comando acrescenta um elemento, tira um ou muda a ordem deles. Quando a lista de elementos está errada, crie uma competência nova com os elementos certos, e depois apague a errada.
• Uma criação é sempre de nível superior. Nada aqui aninha uma competência embaixo de outra. Uma competência que você pensou como subcompetência fica no nível superior, ao lado da competência que seria a mãe dela.
• Uma criação não é idempotente. Nada torna o nome de uma competência único, então uma segunda execução com o mesmo nome guarda uma segunda competência. Depois de uma conexão perdida, de um timeout ou de um erro do servidor, leia antes a lista da tecnologia, e crie de novo só quando a sua competência não estiver nela.

Quando falta um componente

Quando um componente de que a competência precisa não está no Fito, o comando se recusa a redigir a competência. Ele não escreve registro nenhum, e nunca tira o elemento para o registro caber: uma competência sem um componente de que precisa é uma competência mais fraca, e quem tem de crescer é o vocabulário. Um componente vivo só numa outra linha principal conta como ausente.

O comando nomeia as referências ausentes e manda você para o pipeline de conhecimento. Para continuar:

1. Publique os componentes ausentes — veja Identificar componentes de conhecimento e Gerar e publicar componentes.
2. Rode o /fito-create-or-update-competence de novo, com os mesmos elementos.

Quando todos os componentes voltam ausentes, desconfie da linha principal antes do vocabulário. Os componentes podem estar vivos em outra linha, e o comando pergunta a você antes de listá-los sem a versão.

O Fito aplica a mesma regra na escrita. Quando um componente some entre a sua confirmação e a criação, ou uma referência foi digitada errado, a escrita é recusada, e a recusa lista toda referência que não nomeia nada:

✗ Create failed (422): competence element references resolve to no knowledge component: <references>

Mantenha todo elemento que você confirmou, publique os componentes ausentes e crie de novo.

Editar o nome ou a descrição

Uma edição muda o nome, a descrição ou os dois, no lugar. A competência mantém o id, os elementos e toda proficiência registrada de aprendizes nela.

1. Rode o comando com a tecnologia e, quando você tiver, o id da competência:

   /fito-create-or-update-competence --technology javalin@7 --competence COMPETENCE_ID

   Troque COMPETENCE_ID pelo id que a criação imprimiu, ou deixe o --competence de fora e escolha na lista.

2. Escolha a competência na lista. Um id que a lista não mostra é recusado, e o comando pede que você escolha um que ela mostre. Uma subcompetência é um alvo como outro qualquer, pelo id aninhado embaixo da competência acima dela.

3. Confirme o nome novo, a descrição nova, ou os dois. O comando pula os passos de elementos, porque uma edição não escreve elementos. O registro vai para ./output/4-competence/edit.yaml.

4. Leia o resultado que a escrita imprime. Ele nomeia só o que você confirmou mudar:

   ✓ Updated the name and the description of competence "<name>" (<id>) ← <payload-file>

Uma edição pode definir uma descrição ou trocar uma, mas nunca apagar uma. Uma descrição null ou em branco é recusada antes de qualquer envio.

Quem pode editar ou apagar uma competência

Quem cria uma competência é dono dela. O dono e qualquer admin podem editá-la ou apagá-la, e mais ninguém pode, curador ou não. A recusa nomeia os dois caminhos, para você saber qual deles falta:

✗ Update failed (403): user <user-id> is neither the owner nor an admin, so may not edit competence <competence-id>

Uma exclusão recusada tem o mesmo texto, com Delete failed e delete.

Uma competência que veio do seeding não tem dono, então só um admin pode editá-la ou apagá-la. Quando você não consegue editar a Request handling fundamentals do javalin, o motivo é esse: peça a um admin.

Apagar uma competência

Uma exclusão remove a competência e toda subcompetência abaixo dela, numa escrita só. O Fito não confere se ela está em uso e não tem desfazer, então a prévia e o seu sim são a única proteção.

Uma exclusão não pode ser desfeita

Recriar uma competência apagada gera um id novo, e toda subcompetência abaixo dela tem de ser criada de novo, com ids novos também. Qualquer coisa que guardava o id antigo não guarda mais nada.

1. Rode o comando com o id da competência:

   /fito-delete-competence COMPETENCE_ID

   Troque COMPETENCE_ID pelo id. Quando você não tiver mais o id, passe --technology javalin no lugar e escolha na lista. Esse slug vai puro, sem @<version>. Quando você passa os dois, o id vence, e a lista só o confirma.

2. Leia a prévia. O comando primeiro roda a exclusão sem confirmá-la, o que não apaga nada e mostra o que iria embora:

   This will delete competence "<name>" (<id>) and everything beneath it:
     - "<sub-competence-name>" (<sub-competence-id>)
   1 sub-competence goes with it. No learner's recorded proficiency is touched.
   
   Nothing has been deleted. A delete needs the author's explicit confirmation:
     node delete.js <id> --confirm

   Essa execução sai com código diferente de zero e imprime na saída de erro, de propósito. Não é uma falha.

3. Diga sim, nomeando a competência. O comando nunca toma o silêncio, nem o fato de você ter rodado o comando, como um sim. Quando a revisão demorou, ou outra pessoa pode estar escrevendo, peça uma prévia nova antes: uma subcompetência acrescentada depois da prévia vai embora junto com o resto.

4. Leia o resultado:

   ✓ Deleted competence "<name>" (<id>) and its 1 sub-competence

Nenhuma proficiência registrada de aprendiz muda. O Fito registra proficiência por componente de conhecimento, então uma exclusão tira uma competência da tela do aprendiz e não destrói nota nenhuma.

Argumentos e flags

Os dois comandos aceitam os argumentos e as flags a seguir:

Comando	Argumento ou flag	Obrigatório	O que faz
/fito-create-or-update-competence	--technology <slug>@<version>	Sim	A tecnologia, e a linha principal em que os elementos são escolhidos
/fito-create-or-update-competence	--competence <id>	Não	A competência a editar, quando você tem o id dela
/fito-create-or-update-competence	--output <path>	Não	Para onde vai o registro confirmado. O padrão é ./output/4-competence/competence.yaml numa criação e ./output/4-competence/edit.yaml numa edição
/fito-delete-competence	<competence-id>	Um dos dois	A competência a apagar
/fito-delete-competence	--technology <slug>	Um dos dois	Um slug puro, para escolher a competência numa lista

Quando o comando para

Nenhuma recusa escreve nada. O comando mostra a mensagem do Fito palavra por palavra:

Mensagem	O que significa	O que fazer
Declare the technology and its major line: …	Falta o --technology, ou falta o @ nele	Passe --technology <slug>@<version>
Name the competence to delete — …	Nem um id nem o --technology	Passe o id, ou --technology <slug>
You are not logged in to Fito. Run /fito-login first, then re-run this flow.	Sem sessão	Rode o /fito-login e depois rode o comando de novo
✗ Create failed (403): user <user-id> is neither a curator nor an admin, so may not create a competence	Você não é dono de nenhum caso e não é admin	Crie um caso antes, ou peça a um admin
✗ Create failed (404): technology "<slug>" does not exist	Nenhuma tecnologia tem esse slug	Confira o slug, ou provisione a tecnologia
✗ Update failed (404): competence "<id>" does not exist	Nenhuma competência tem esse id. Uma exclusão mostra Delete failed	Escolha a competência na lista da tecnologia
✗ Create failed (400): <message>	Um registro que quebra uma regra: nenhum elemento, um elemento repetido, um nome em branco, um nome com mais de 255 caracteres ou uma descrição com mais de 4.000. Uma edição ou uma exclusão mostra Update failed ou Delete failed, e também recusa um id que não é UUID	Corrija o registro, confirme de novo e rode o comando de novo

O que vem a seguir

• Competências e objetivos de aprendizagem — como a proficiência de um aprendiz numa competência é calculada a partir dos elementos dela.
• Crie seu primeiro caso — ponha para trabalhar os componentes que você publicou.
• Gerar e publicar componentes — faça o vocabulário crescer quando uma competência precisa de um componente que o Fito não tem.