Skills de apoio

As três skills orquestradoras não fazem tudo sozinhas. Elas carregam skills de apoio sob demanda, e cada uma dessas skills é a única fonte da verdade sobre o seu próprio assunto.

Progressive disclosure

Nenhuma skill de apoio é pré-carregada. A orquestradora carrega só o arquivo que o passo atual precisa. É o que mantém a janela de contexto utilizável num fluxo de ponta a ponta.

Especialistas de domínio

Acionadas pelo makuco-desenvolver via roteamento por gap, e pelo makuco-analisar no caso da UX.

Skill	O que faz
`makuco-backend`	Disciplina de trabalho de backend, agnóstica de stack: descoberta de contexto, ownership, impacto de contrato, persistência, mensageria, observabilidade, segurança e handoff limpo. Todo detalhe de stack ou política vem do projeto alvo.
`makuco-frontend`	Disciplina de trabalho de frontend, agnóstica de stack. Trata o código real do projeto + os docs de convenção em `.makuco/docs/codebase/*` como única fonte da verdade sobre framework, estilo, tokens e estado.
`makuco-ux`	Produz o contrato duplo de UX: `DESIGN.md` (identidade visual e tokens) + `EXPERIENCE.md` (arquitetura de informação, estados, interações, acessibilidade, fluxos-chave). Capture-don't-create: elicita e registra a sua visão, nunca impõe uma.

Skill especialista não instalada → aviso uma vez e o fluxo segue com a disciplina genérica. Nunca bloqueia a entrega.

O contrato duplo de UX

DESIGN.md segue a especificação design.md do Google Labs: tokens no frontmatter YAML (cores, tipografia, arredondamento, espaçamento, componentes) + corpo em markdown na ordem canônica. EXPERIENCE.md referencia os tokens do DESIGN.md pela sintaxe {path.to.token}.

Os dois documentos prevalecem sobre qualquer mock, wireframe ou import em caso de conflito.

Passes de review

Carregadas pelos subagentes que o makuco-code-review despacha em paralelo. Cada uma define o próprio checklist e o próprio formato de saída.

Skill	Passe	O que valida
`makuco-reviewer-correctness`	3	Se a mudança funciona e se é segura, numa lente só: null/undefined, race conditions, vazamento de recursos, off-by-one, coerção insegura, erro engolido, estado inconsistente e o OWASP Top 10 em toda fronteira de confiança. É o passe que roda em todo perfil.
`makuco-reviewer-design`	4	Se a mudança é bem construída e se cabe onde caiu: SOLID, Object Calisthenics, Clean Code, e a estrutura de pastas, nomenclatura, fluxo de dependências, tratamento de erro e log do próprio projeto.
`makuco-reviewer-tests`	5	Se a mudança é testada: se o teste existe, se ele falha quando o comportamento quebra, e se segue a convenção de testes do projeto.

Desde a 3.3.0, esses três substituem os cinco anteriores — makuco-reviewer-quality, -security, -bugs e -patterns foram fundidos em -correctness e -design. O makuco update oferece remover as skills antigas do projeto.

Formatação de artefatos

Todas carregadas pelo makuco-copy-writer, uma por stage. São o template de cada artefato canônico — o formato, não o conteúdo.

Skill	Artefato
`makuco-artifact-feature`	`feature.md` (PRD) + `decisions.md`
`makuco-artifact-pbi`	`pbis/{slug}/pbi.md` — o que entrega, CAs, tabela INVEST
`makuco-artifact-discovery`	`discovery.md`
`makuco-artifact-rca`	`rca.md` — o laudo de causa raiz do modo INVESTIGAÇÃO
`makuco-artifact-structure`	`pbis.md` — a decomposição da feature
`makuco-artifact-business`	`pbis/{slug}/business.md`
`makuco-artifact-technical`	`pbis/{slug}/technical.md`
`makuco-artifact-spec`	`pbis/{slug}/spec.md`
`makuco-artifact-plan`	`pbis/{slug}/plan.md`
`makuco-artifact-task`	`pbis/{slug}/tasks/task-NN.md`
`makuco-artifact-review`	`pbis/{slug}/review.md`
`makuco-artifact-learnings`	`pbis/{slug}/learnings.md`
`makuco-artifact-reference`	`references/references.md` — referências visuais da feature

Contexto e infraestrutura

Skill	O que faz
`makuco-project-research`	Mapeia a codebase em `.makuco/docs/codebase/`. Dois modos: índice (barato, preenche o roteador de repos do `MAKUCO.md`) e pesquisa completa (`OVERVIEW.md` + os oito arquivos técnicos, com o registro de risco + `modules/<slug>.md` opcionais). Veja Configurações.
`makuco-workspace-detection`	Localiza o diretório `.makuco/` no workspace (inclusive multi-root do VSCode). Resolve o `MAKUCO_ROOT` ou pára pedindo ajuda.
`makuco-product-context`	Busca contexto de produto/negócio (goal, glossário, escopo, personas, entrevistas, PRDs) no Makuco Docs MCP, em vez de arquivos locais.
`makuco-azure-devops`	Interface única com o tracker. Lê/cria/atualiza/vincula work items respeitando a hierarquia Feature → PBI → Task, com todo nome de tipo, estado e campo resolvido do config do projeto. Veja Azure DevOps.
`makuco-quality-gate`	Dono das definições e limiares dos gates de qualidade. O `makuco-desenvolver` só roteia para ela — escopo `per-task` antes de cada commit e escopo `full` no fechamento. Complexidade e SonarQube só rodam quando ligados em `.makuco/integrations/quality-gate.yml`.
`makuco-observability-context`	Resolve quais capacidades de investigação a sessão tem — `source`, `tracker`, `logs`, `metrics`, `code_index`, `runtime`, `edge` — pela configuração, pelos docs de codebase, pelo ambiente ou perguntando uma vez e gravando a resposta em `.makuco/integrations/observability.yml`. Usada pelo modo INVESTIGAÇÃO.
`makuco-plantuml-diagram`	Gera código-fonte PlantUML a partir de descrição em linguagem natural. Todos os tipos de diagrama UML e não-UML.
`makuco-caveman`	Controle de verbosidade. Lê `~/.makuco/config.yml` e aplica as regras de comunicação do nível ativo (`off` / `lite` / `full` / `ultra`).

Práticas

Carregadas quando o assunto aparece — durante geração de código, review ou refactor.

Skill	O que aplica
`makuco-code-practices`	SOLID, Object Calisthenics (9 regras) e Clean Code.
`makuco-testing-practices`	TDD/BDD, estrutura AAA, nomenclatura, cobertura, uso de mock/stub/spy, isolamento.
`makuco-ux-practices`	User-Centered Design e Lean UX — a camada de princípios, complementar ao `makuco-ux` (que produz os contratos).
`makuco-ubiquitous-language`	Resolve antes do código como ele pode ser chamado: em que idioma os identificadores falam e qual termo nomeia cada conceito. A codebase do projeto vem primeiro; o default da skill (domínio em inglês) só vale quando o projeto não decidiu, e padrão ausente ou duplicado vira pergunta. O `makuco-desenvolver` a carrega na rodada de dúvidas técnicas.
`makuco-entity-relationship-diagram`	Padrões de modelagem ER: nomenclatura, atributos, cardinalidade, PK/FK. Delega a renderização ao `makuco-plantuml-diagram`.
`makuco-task-writing`	Estrutura, regras de densidade e restrições anti-redundância para arquivos de task.
`makuco-prd-generator`	Geração de PRD para uma feature nova.
`makuco-skill-creator`	Cria, edita e melhora skills — inclusive a descrição, para o gatilho ficar mais preciso.