Desenhar um caso

Desenhar é um diálogo. Você traz um objetivo e as tecnologias sobre as quais o caso fala; o comando fundamenta isso no conhecimento que o Fito de fato guarda e escreve uma proposta de caso. Nada mais é escrito — nenhuma pasta .case/, e nunca um arquivo dentro de um projeto de origem que você aponte.

Esta página cobre /fito-case-design, as flags dele e as duas recusas com que ele pode terminar. Para o formato daquilo que você está desenhando, leia O que é um caso.

Antes de começar

• Uma sessão do pi num diretório de trabalho seu, com o Fito instalado nele. Veja Preparar um diretório de trabalho.
• Toda tecnologia sobre a qual o caso fala, e a linha principal que ele mira, já provisionadas. Veja Provisionar uma tecnologia.
• Os componentes de conhecimento (knowledge components) que o caso vai referenciar, já enviados. Se eles ainda não existem, este comando recusa — veja Quando o comando para.

Você não precisa estar logado. Toda leitura que este comando faz é pública.

Desenhar o caso

1. Rode o comando com o objetivo e um --technology por tecnologia, cada um com a sua linha principal:

   /fito-case-design "diagnosticar um endpoint JSON quebrado" --technology javalin@7

   Para construir o caso sobre um projeto que você já tem, acrescente --source:

   /fito-case-design "diagnosticar um endpoint JSON quebrado" --technology javalin@7 --source ~/code/my-javalin-app

2. Responda ao diálogo. Ele fecha o escopo, o tipo do caso, uma estimativa de duração e a toolchain — as ferramentas de build contra as quais o projeto do caso é construído, nomeadas só por linha principal (9, nunca 9.5.1).

3. Leia a proposta que ele rascunha e questione. Escopo, referências, critérios de rubrica, pesos e quiz ficam abertos até você confirmar.

4. Confirme. A proposta é escrita em ./case-proposal.md, ou onde --output disser.

Confira o resultado antes de seguir: abra o arquivo e veja se ele traz Parameters, Learning objectives, Prerequisites e Rubric criteria. Esses quatro são o que o próximo passo lê, e ele para sem eles. Quiz items, Source grounding e Open questions só aparecem quando o caso os tem.

Flags

Flag	Obrigatória	O que faz
(texto inicial)	Sim	O objetivo — o que o caso deve ensinar ou avaliar
--technology <slug>@<version>	Sim, repetível	Uma tecnologia do caso, com a linha principal dela
--source <path>	Não	Um projeto existente sobre o qual construir o caso
--output <path>	Não	Onde escrever a proposta. O padrão é ./case-proposal.md

Todo --technology precisa trazer o seu @<version>. Um slug sozinho é recusado em vez de ser tratado como “qualquer versão”, porque todo componente de conhecimento é escopado a uma linha principal, e um componente vivo só em outra linha é lido como ausente.

Nota

A toolchain e as versões de --technology são duas declarações diferentes. As versões das tecnologias são o que o caso ensina; a toolchain é contra o que o projeto do caso é construído. Elas se sobrepõem e não são a mesma coisa.

O que a proposta traz

Um arquivo markdown com blocos YAML cercados, no formato dos arquivos .case/ que eles alimentam:

Seção	Alimenta
Scope	A situação e a tarefa
Parameters	manifest.yaml — tipo, duração, idioma, tags, tecnologias, toolchain
Learning objectives	learning_objectives.yaml
Prerequisites	prerequisites.yaml
Rubric criteria	rubric.yaml
Quiz items	quiz.yaml, quando o caso tem um
Source grounding	Só em execuções de reuso — o projeto, a área do caso, os comandos de gate
Open questions	O que ficou para você resolver no próximo passo

Os pesos da rubrica precisam ser números inteiros positivos somando exatamente 100, e todo critério esboça os quatro níveis, das pontuações 0 a 3.

Toda referência é verificada, nunca chutada

O comando lista o que o vocabulário guarda para cada tecnologia e linha principal declaradas, e depois busca cada id que a proposta vai carregar. Um id que não volta está ausente, e nenhum id não buscado chega à proposta.

Cuidado

Escolha as referências como se fossem permanentes, porque depois da publicação elas são. Um caso publicado cujas referências em objetivos de aprendizagem, pré-requisitos ou rubrica mudem não pode ser corrigido no lugar — essa correção é um caso novo. Veja O conjunto de referências.

A avaliação aponta para um objetivo de aprendizagem

O comando lista cada componente que os critérios da rubrica e as perguntas do quiz nomeiam, procura cada um nos objetivos de aprendizagem e reporta cada falta em Open questions — dizendo se ela é um pré-requisito, ou nenhum dos dois. Ele reporta em vez de reapontar, porque qual conserto você quer é decisão sua.

A regra completa, e por que ela é um aviso e não uma recusa, está em O que é um caso.

Os degraus são uma escada de qualidade no nível declarado

O bloom_level de um critério é o que um critério atendido registra: uma nota 2 ou 3 registra aquele nível, e uma nota 0 ou 1 registra NOT_ACHIEVED. Então os quatro degraus dos levels dele medem o quão bem quem aprende trabalhou naquele único nível. Eles nunca sobem de um nível para o próximo:

Degrau	Nota	O que ele descreve
not_achieved	0	Nenhuma tentativa no nível declarado, ou uma tentativa errada
partial	1	Uma tentativa no nível declarado que fica aquém
achieved	2	Atendido. Este degrau define o que é concedido, então escreva-o com o maior cuidado
exemplary	3	Bem atendido — o mesmo trabalho feito melhor, na mesma profundidade

O comando também compara o nível declarado de cada critério com o que os degraus dele pedem a quem aprende: lembrar, explicar ou aplicar. Um critério que declara APPLICATION enquanto os seus degraus pedem uma explicação avalia COMPREHENSION, e quem explicasse bem seria registrado em APPLICATION sem ter aplicado nada.

Cada falta vai para Open questions, nomeando o critério, o degrau, o nível declarado e o nível que o degrau avalia. O comando mantém o critério como foi rascunhado, porque o conserto — declarar o nível que os degraus avaliam, ou reescrever os degraus — muda o que o caso certifica. Resolva isso antes de publicar: depois disso, um nível alterado vira um caso novo.

Descrições nomeiam o tema, nunca a jogada

Toda description que você escrever aqui viaja: o passo de geração copia as descrições para os arquivos do caso, e a página pública do catálogo é rascunhada a partir dos objetivos de aprendizagem. Então uma descrição pode dizer o que está quebrado e o que quem aprende vai conseguir fazer, e não pode dizer a jogada que repara aquilo.

A regra completa, com exemplos, está em O que é um caso.

Quando o comando para

As duas paradas não escrevem proposta nenhuma.

O que você vê	O que significa	O que fazer
“The Fito vocabulary doesn’t hold these declared technologies yet”	Um slug não existe, ou existe sem a linha principal que você nomeou	Provisione a tecnologia, ou corrija uma declaração escrita errado
“These components don’t exist in the Knowledge Repository yet”	O caso precisa de conhecimento que ninguém escreveu ainda	Rode o pipeline de conhecimento sobre a fonte e rode este comando de novo

Não encolha o caso para caber no que existe. Descartar um componente de que o caso realmente precisa faz um caso pior; o que deve crescer é o vocabulário.

Uma conferida antes de recorrer ao pipeline: se todos os candidatos de uma tecnologia voltaram ausentes, desconfie da linha principal, não do vocabulário. A tecnologia e a linha existem — o passo 1 provou isso — então o que resta é que os componentes de que você precisa vivem em outra linha.

Qualquer outra falha, como um backend fora do ar, não diz nada sobre a sua declaração. Ela é relatada como chegou.

O que vem a seguir

• Gerar a pasta .case/ — transformar a proposta no contrato.
• Identificar componentes de conhecimento — se o desenho parou em componentes ausentes, comece por aqui.