Conceitos & Glossário

Os termos do Makuco num só lugar.

Referência rápida do vocabulário do Makuco. Para o detalhe de cada skill, veja o Fluxo.

Estrutura do trabalho

Termo	O que é
Módulo	Agrupador de features, identificado como `module_NNN_<slug>`.
Feature	Uma capacidade do produto, identificada como `feature_NNN_<slug>`. É o ponto de partida do fluxo.
PBI	Product Backlog Item — uma parte atômica e independentemente valiosa de uma feature, identificada como `pbi_NNN` + slug. Cada PBI percorre o ciclo de desenvolvimento por conta própria.
Task	Unidade atômica de implementação dentro do `task.md`: um componente, uma função, um endpoint, ou uma mudança de arquivo. Os testes são co-localizados na task.
Artefato	Qualquer arquivo produzido pelo fluxo (`feature.md`, `pbi.md`, `spec.md`, `task.md`, `review.md`, `learnings.md`…). Fica versionado em `.makuco/docs/`.

As skills e os agentes

Termo	O que é
Skill orquestradora	Uma das três skills autônomas que conduzem o trabalho de ponta a ponta e que você invoca direto: `makuco-analisar`, `makuco-desenvolver` e `makuco-code-review`.
Skill de apoio	Skill carregada sob demanda por uma orquestradora — especialistas de domínio, passes de review, formatação de artefatos, práticas. Veja Skills de apoio.
Agente	Um dos 3 agentes que sobraram: `makuco-copy-writer`, `makuco-documentation` e `makuco-quick`. Você só invoca o último.
Progressive disclosure	O padrão em que a skill carrega só o arquivo de passo (ou referência) que o fluxo precisa naquele momento, em vez de tudo de uma vez.

Análise

Termo	O que é
DESCOBERTA	Modo do `makuco-analisar` para uma oportunidade ainda nebulosa: brainstorming amplo → `discovery.md` com recomendação → gate de produto.
SOLUÇÃO	Modo do `makuco-analisar` para um problema já claro: interrogatório de negócio em rodadas de perguntas com resposta recomendada, sem técnicas de brainstorming. Pula o gate de produto.
EXPRESS	Modo do `makuco-analisar` para um item já decidido e escrito (card ou requisitos): lê a origem inteira, esclarece as lacunas e sai com o PRD e uma PBI. Sem brainstorming, sem gate, sem decomposição.
INVESTIGAÇÃO	Modo do `makuco-analisar` para um bug em produção cuja causa é desconhecida: causa raiz com evidência → `rca.md` → PBIs de correção. Nunca corrige. Veja Investigação de bug.
Interrogatório de negócio	A árvore de decisão que o SOLUÇÃO percorre — dor → fluxo → regras → limites —, em rodadas de 3 a 5 perguntas. Requisitos e critérios de aceite são derivados das respostas, nunca perguntados.
Go / No-Go / Refinar	A recomendação que o `discovery.md` carrega ao final do modo DESCOBERTA.
Gate de produto	A pausa em que você apresenta o `discovery.md` ao aprovador configurado em `analise.aprovador` e volta com `aprovado` / `reprovado` / `ajustar`. É humano, não técnico, e não é configurável.
INVEST	Os seis critérios que toda PBI deve passar antes de ser criada: Independent, Negotiable, Valuable, Estimable, Small, Testable.
PRD	O `feature.md` — a documentação da feature: problema, solução, regras de negócio, escopo e decisões.
`rca.md`	O laudo de causa raiz do modo INVESTIGAÇÃO: sintoma × objetivo, cadeia causal com `arquivo:linha` fixado num commit, hipóteses, falsificadores, veredito adversarial, lacunas e os requisitos da correção.
Gate de evidência	O gate que libera o modo INVESTIGAÇÃO no lugar do gate de produto: cada item fechado com evidência ou declarado como lacuna.
Capacidade de investigação	Um papel que a investigação consegue ler — `source`, `tracker`, `logs`, `metrics`, `code_index`, `runtime`, `edge` —, resolvido pelo `makuco-observability-context` e gravado em `observability.yml`. Capacidade ausente vira lacuna com teto de confiança.
Protocolo anti-viés	A rotação deliberada do eixo criativo (técnico → UX → negócio → edge cases → mercado) a cada ~10 ideias do brainstorming, para o LLM não ficar preso numa mesma lane semântica.

Desenvolvimento

Termo	O que é
Spec	A `spec.md` — a especificação de escopo de dev de uma PBI, com CAs normalizados, edge cases levantados e as decisões técnicas.
Rodada de dúvidas técnicas	A parada do `makuco-desenvolver` antes da spec: o que a codebase não decide, ou decide com mais de um padrão vivo, é perguntado de uma vez, com `arquivo:linha` em cada opção. Zero dúvidas é um resultado válido.
Decisões técnicas	A tabela da `spec.md` com cada escolha técnica, a evidência e a origem (`usuário` ou `assumida`). O que ficou sem resposta é `EM ABERTO` e é reperguntado na execução.
`WHEN … THEN system SHALL …`	O formato em que cada critério de aceite é normalizado na `spec.md`. O que não cabe nesse formato é vago demais.
Requirement Traceability ID	Identificador único (`[PBI-SLUG]-[NUMBER]`) de cada CA e cada edge case, usado para rastrear qual task satisfaz o quê.
`[P]`	Marca de paralelismo no `task.md`: tasks com `[P]` podem ser implementadas em paralelo. Só é aplicada quando dependências e segurança de paralelismo dos testes permitem.
RED → GREEN → VERIFY → COMMIT	O ciclo de implementação de cada task: testes → código que passa → gate → commit atômico.
Tier gate	O gate de teste da task, no tier declarado no `task.md` (`quick` / `full` / `build`), com os comandos vindos do `TESTING.md` do projeto.
Quality gate	Os gates de qualidade do `makuco-quality-gate`. Escopo `per-task` (barato, antes de cada commit) e escopo `full` (caro: cobertura, checklist e, se ligado, SonarQube — no fechamento, depois que o review aprovou).
Gates opcionais	SonarQube e verificação de complexidade: desligados por padrão, ligados por projeto em `.makuco/integrations/quality-gate.yml`. Desligados, aparecem como DESATIVADO.
Ciclo de review	O `makuco-desenvolver` chama o `makuco-code-review` no fechamento, corrige o que ele aponta e pede nova rodada — até duas rodadas automáticas; no teto, a decisão volta para você.
Gap de UI	Uma task de frontend numa PBI sem o par `DESIGN.md`/`EXPERIENCE.md`. Aciona o `makuco-ux` antes de a task ser emitida.
Roteamento por gap	A derivação, a cada sessão, do mapa domínio → skill especialista (`makuco-backend` / `makuco-frontend` / `makuco-ux`) a partir de `.makuco/docs/codebase/*`. Sem tabela de palavras-chave.
AD-004	A regra de que tasks de backend são ordenadas e executadas antes das de frontend na mesma PBI.
`SPEC_DEVIATION`	Marcador inserido no código no ponto exato em que a implementação divergiu da spec ou do design.
PULADO / SKIP	Um gate que não conseguiu rodar (skill ausente, MCP indisponível, Docker ausente, credenciais do Sonar não configuradas). É reportado com o motivo, nunca como aprovado, e nunca bloqueia.
DESATIVADO	Um gate opcional que o projeto não ligou. Não roda, não bloqueia e não é Blocker — a checagem fica com o pipeline do time.

Review

Termo	O que é
Modo PBI	Review de uma PBI implementada: passes 1–5, `review.md` via `makuco-copy-writer`, atualiza o `status.yml`.
Modo DIFF	Review de uma branch/PR/working tree avulsa: passes 2–5, relatório direto em `.makuco/reviews/`, sem `status.yml`.
Os cinco passes	1 conformidade com spec/tasks · 2 análise do diff · 3 correção (bugs e segurança) · 4 design (qualidade e padrões) · 5 testes. Os passes 1–2 rodam no contexto principal; 3–5 em subagentes paralelos.
Perfil do review	`leve`, `padrao` ou `profundo`, decidido pelo tamanho do diff e por sinais de risco (auth, entrada externa, segredo, dinheiro, migração, deleção…). Sinal de risco sobe o perfil por menor que seja a mudança, e o perfil é declarado no relatório.
`N/A`	Um passe que não se aplica (o conjunto de arquivos dele saiu vazio). Diferente de `SKIP`, que é um passe que deveria ter rodado e não conseguiu.
`critical` / `major` / `minor` / `suggestion`	As quatro severidades. Só `critical` e `major` bloqueiam a aprovação.
`CONFIRMED` / `PLAUSIBLE` / `REFUTED`	O veredito da verificação de um achado bloqueante contra o código real. `REFUTED` é descartado, citando a linha que o refuta.
Agrupamento por causa raiz	Vários achados que compartilham uma causa e uma correção viram um achado com tabela de instâncias.
APROVADO / NECESSITA CORREÇÕES	Os dois — e únicos — vereditos possíveis. Não existe "aprovado com ressalvas".
Rodada de revisão	Cada passada do review sobre a mesma PBI. Rodadas acumulam no mesmo `review.md`. A rodada que vem de uma correção é uma verificação — responde se foi corrigido e procura regressão no diff da correção.
Bloqueio congelado	A partir da segunda rodada de correção, só bloqueia o achado que ficou aberto, o que a correção introduziu e `critical` novo. `major` novo fora do diff da correção vira observação.

UX e referências

Termo	O que é
Contrato duplo de UX	O par `DESIGN.md` + `EXPERIENCE.md` produzido pela skill `makuco-ux`. Prevalece sobre qualquer mock em caso de conflito.
`DESIGN.md`	A identidade visual: tokens (cores, tipografia, espaçamento, componentes) e regras de uso, na especificação design.md do Google Labs.
`EXPERIENCE.md`	Como funciona: arquitetura de informação, estados, interações, acessibilidade e fluxos-chave. Referencia os tokens do `DESIGN.md`.
Referência visual	O desenho da tela que você mostra à skill. Pode ser um print, um protótipo HTML, um link do Figma ou só uma descrição. Veja Referências Visuais.

Estado e contexto

Termo	O que é
`status.yml`	A fonte da verdade do fluxo: acompanha o progresso da feature e de cada PBI, etapa por etapa. Apenas o `makuco-copy-writer` escreve nele.
Arquivo de sessão	O estado interno de cada skill orquestradora: `sessao.md` (analisar), `sessao-dev.md` (desenvolver), `sessao-review.md` (review). É o que permite retomar de onde parou.
`STATE.md`	Registro durável de decisões, blockers, lições aprendidas e ideias adiadas — além das tarefas concluídas via Quick Mode.
`HANDOFF.md`	Snapshot do que falta quando uma PBI é pausada no meio. Uma PBI concluída não gera handoff.
Base de conhecimento	Os arquivos em `.makuco/docs/codebase/` (`OVERVIEW.md`, `modules/<slug>.md` e os oito técnicos, com o registro de risco) que as skills leem antes de trabalhar. Gerada pelo `start-makuco`.
Registro de risco	O `risks.md`: o que é arriscado mexer no repo — débito, bugs conhecidos, falhas de segurança, gargalos medidos, áreas frágeis —, sempre com caminho de arquivo e, para desempenho, com número.
Modo local-only	O padrão: sem integração de tracker, as PBIs vivem só no disco com id local. Tudo funciona.
Modo `ado`	Com `.makuco/integrations/azure-devops.yml` presente: os work items são criados e o status é sincronizado local → tracker. Veja Azure DevOps.
Workspace multi-repo	Um workspace em que `repos/` tem ao menos uma sub-pasta de repositório. O contexto de código vive por repo, em `repos/<nome>/.makuco/docs/codebase/`.
Quick Mode	Trilha expressa para mudanças pequenas, que ignora o fluxo completo.

CLI interativa

Termo	O que é
CLI interativa	A interface de terminal que `makuco` abre desde a 3.2.0: lê os artefatos, deriva o próximo passo e invoca a skill sozinha. Veja CLI Interativa.
Loop	O laço da CLI: ler artefatos → derivar passos candidatos → oferecer → invocar a skill → reler.
Passo candidato	Uma dupla skill + alvo que o estado do projeto libera agora. `/steps` lista todos; `/next` roda o oferecido.
Oferta	O passo que a CLI está propondo. Aparece no placeholder da caixa; `Enter` com a caixa vazia aceita.
Parada por alvo	A licença que a CLI pede sempre que um alvo fecha, antes de seguir para o próximo. O modo yolo é o que a dispensa.
Provider	Quem executa o turno: `claude-code` (padrão) ou `custom-sdk`. Trocável em `/settings`.
ACP	Agent Client Protocol — o protocolo pelo qual a CLI conversa com o agente. É o que a torna agnóstica a qual agente está do outro lado.
Turno	Uma ida e volta com o agente: o prompt da CLI, o trabalho dele e o fim da resposta. É a unidade que `Esc` e `Ctrl-C` cancelam.
Modo yolo	O modo em que a CLI encadeia os passos sem pedir licença e aprova toda permissão. `--yolo`, `/yolo` ou `Shift+Tab`.
Ação segura / sensível	A classificação que decide o que pode ser auto-aprovado: `read`/`search`/`think` são seguras; editar, apagar, mover, executar e buscar na rede são sensíveis. Veja Modos e permissões.
Skill como comando	Qualquer skill do ambiente invocável por `/nome` na caixa de prompt. Origens: projeto > usuário > plugin.
Skill sombreada	Skill sem comando `/` — porque um comando embutido ocupa o nome, outra origem ganhou o nome, ou o nome tem espaço/barra. Continua alcançável pela tela `/skills`.
Passo estacionado	Passo que falhou ao abrir, ou que terminou sem avançar o estado. É deixado de lado com aviso, para o laço não repeti-lo para sempre.