Desenvolver

makuco-desenvolver

Função

Leva um work item — id do Azure DevOps ou PBI local produzida pelo makuco-analisar — até código verde, em commits atômicos, e revisado. Carrega o contexto já decidido a montante (artefatos da feature/PBI, .makuco/STATE.md, .makuco/docs/codebase/*) sem reabrir a descoberta, pergunta numa rodada só o que a codebase não decide, gera uma spec.md + task.md de escopo de dev, implementa cada task no ciclo RED → GREEN → VERIFY → COMMIT e, no fechamento, conduz o review sozinho até existir um veredito.

Fluxo em passos

step-01-identificar       → resolve config · lê o item (tracker) ou localiza a PBI local ·
                            valida o tipo contra o type-map · resolve a pasta da PBI ·
                            oferece retomar · semeia sessao-dev.md
        ↓
step-02-carregar-contexto → carrega artefatos do makuco-analisar (feature/decisions/pbis/rca/
                            DESIGN/EXPERIENCE) + STATE.md + docs de codebase ·
                            resolve os gates opcionais · CAs imutáveis · nunca reabre a especificação
        ↓
step-03-spec-e-tasks      → convenção de testes + mapa stack→skill ·
                            RODADA DE DÚVIDAS TÉCNICAS (uma vez, com evidência, PARA) ·
                            spec.md (com Decisões técnicas) + task.md · backend antes de frontend ·
                            gap de UI → makuco-ux primeiro · PARA e aguarda sua aprovação
        ↓
step-04-implementar       → por task: Step 0 aciona a skill especialista ·
                            RED → GREEN → VERIFY → COMMIT · tier gate + quality gate
                            escopado antes de cada commit · passada de correção quando o review devolve
        ↓
step-05-fechamento        → build por repo · CICLO DE REVIEW (makuco-code-review, até 2 rodadas) ·
                            gate completo depois da aprovação · decisões e lições no STATE.md ·
                            sync de status local→tracker · HANDOFF · marca a PBI como concluída
                              ↑                                   │
                              └──── NECESSITA CORREÇÕES ──────────┘  (step-04, depois rodada N+1)

As dúvidas técnicas vêm antes da spec

Depois de carregar o contexto e antes de escrever a spec.md, a skill junta tudo o que ficou genuinamente em aberto e pergunta de uma vez.

Primeiro ler, depois perguntar. Só é dúvida o que a skill procurou e não achou. O que os docs de codebase, o decisions.md, o MAKUCO.md, o STATE.md, o TESTING.md ou uma busca no código real resolvem não é perguntado — vira decisão registrada, com a evidência.

A nomenclatura é resolvida primeiro

Antes de qualquer outra dúvida, a skill decide como o código pode ser chamado: em que idioma os identificadores de domínio falam e qual termo nomeia cada conceito. Quem decide é a sua codebase:

• Um padrão claro na codebase → a skill segue e registra, com o arquivo:linha. Não pergunta.
• Nenhum padrão, ou dois concorrentes → vira pergunta, com os precedentes reais como opções e o default do Makuco como uma delas.

O revisor mede contra essa decisão: identificador em português num projeto que fala português não é achado.

O que vira pergunta, e o que não vira

Vira pergunta quando a busca já rodou e:

1. A codebase é omissa — a implementação tem que escolher e nada no projeto decide: semântica de erro, defaults, limite de paginação, idempotência, fuso horário, política de retry.
2. Há mais de um padrão vivo — dois precedentes concorrentes para a mesma coisa, sem nada dizendo qual é o atual.
3. Um contrato externo que ninguém nomeia — rota, evento, tabela, coluna, chave de config ou escopo de permissão que a PBI cria.
4. Algo que a spec inventaria — qualquer SHALL que a spec afirmaria sem evidência por trás.

Não vira pergunta: o que tem exatamente um padrão, o que o linter já governa, o que já foi decidido a montante (inclusive os CAs, que são imutáveis), o que não muda nenhuma linha de código nem de teste, e preferência sem consequência técnica.

Zero dúvidas é um resultado válido e comum — a skill diz isso numa linha e segue.

Como as perguntas chegam

Uma rodada de até 4 perguntas (uma segunda só quando as dúvidas são independentes e não couberam). Passando de 8 dúvidas, a skill oferece voltar ao makuco-analisar.

Cada pergunta traz as opções com o precedente real — arquivo:linha, a consequência de escolher e o trecho de código daquele precedente —, com a recomendada primeiro e o motivo tirado do próprio código. Você pode responder:

• uma das opções → registrada como sua decisão;
• você decide → a skill escolhe o padrão mais recente e marca a decisão como assumida;
• pular → a dúvida fica EM ABERTO: as tasks que dependem dela carregam Bloqueado por: decisão EM ABERTO #{n}, e a skill pergunta de novo na hora de executar. Pergunta sem resposta continua pergunta; nunca vira suposição sem dono.

A spec.md de dev

Os critérios de aceite da PBI são imutáveis — a skill normaliza e estrutura, nunca re-deriva. Cada CA é reescrito no formato:

WHEN [evento/ação] THEN system SHALL [comportamento]

O que não cabe nesse formato é vago demais: a skill pára e sinaliza em vez de adivinhar. Além disso, ela levanta os edge cases que os CAs originais não cobriam (limites, entrada vazia ou gigante, caminhos de erro, entrada inesperada) como linhas próprias, e atribui um Requirement Traceability ID ([PBI-SLUG]-[NUMBER]) a cada CA e cada edge case.

Decisões técnicas

Toda resposta da rodada de dúvidas — e toda decisão que a codebase tomou sozinha — vira uma linha da tabela Decisões técnicas da spec:

Origem diz quem decidiu: usuário, ou assumida quando você delegou com você decide. A decisão que a codebase tomou sozinha leva só a evidência. Nenhuma dessas linhas é reaberta durante a implementação, e linha sem evidência e sem EM ABERTO reprova no checklist da spec.

A quebra em tasks

Uma task = um componente, uma função, um endpoint, ou uma mudança de arquivo. Os testes são co-localizados na task — nunca uma task separada. Cada task carrega:

What · Where · Depends on · Reuses · Requirement · Tools (skill especialista) · Done when · Tests · Gate · Commit

As ferramentas de cada task são derivadas, não perguntadas: saem do mapa stack→skill e das MCPs e skills que o projeto de fato tem, e aparecem na aprovação como uma afirmação que você pode corrigir. Um roteamento genuinamente ambíguo vai para a rodada de dúvidas, com os caminhos de módulo como opções.

Antes de mostrar qualquer coisa para você, três validações obrigatórias rodam:

1. Granularidade — nenhuma task mais larga que um componente/função/endpoint/arquivo.
2. Diagrama × Dependências — todo Depends on tem seta correspondente no diagrama de execução, e nenhuma task [P] depende de outra [P] da mesma fase.
3. Co-localização de testes — o campo Tests de cada task bate com o que a matriz de cobertura do projeto exige.

Um ❌ em qualquer check significa reestruturar as tasks e rodar de novo — nunca apresentar um check falhando pedindo aprovação.

Roteamento por gap — backend / frontend / UX

Não existe tabela de palavras-chave de stack. A cada sessão, a skill deriva o mapa domínio → skill especialista a partir de .makuco/docs/codebase/* (produzido pelo makuco-project-research):

O roteamento acontece duas vezes: no planejamento (step-03) e novamente no Step 0 de cada task, antes de ler ou escrever qualquer código. Se o resultado divergir do planejado (a codebase mudou, ou o palpite estava errado), a skill aciona a skill recém-derivada e anota a mudança — nunca segue calada sob a atribuição velha.

Regras fixas:

• Backend antes de frontend na mesma PBI, sempre.
• 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.
• Skill especialista não instalada — avisa uma vez e segue com a disciplina genérica. Nunca bloqueia a entrega.

Se .makuco/docs/codebase/* estiver ausente ou raso demais para rotear com segurança, a dúvida vai para a rodada de perguntas do step-03 em vez de ser adivinhada — um roteamento errado propaga as convenções da skill errada.

Os gates de qualidade

Os gates são divididos por custo. Os baratos rodam em cada task; os caros rodam uma vez, no fechamento, depois que o review aprovou.

Complexidade e SonarQube são opcionais e vêm desligados. Eles rodam no makuco-mcp, em Docker, e só rodam quando o projeto os liga em .makuco/integrations/quality-gate.yml — veja Configurações → Gates de qualidade. Desligados, aparecem no relatório como DESATIVADO. Com a complexidade desligada, os limites de tamanho de função e de arquivo também deixam de ser cobrados.

Por que o Sonar não roda por task: o sonar-run sobe um container e bloqueia no quality gate do servidor. Uma execução por commit dominaria o tempo de cada task. Rodando uma vez contra o diff acumulado, encontra os mesmos problemas novos.

O que bloqueia

• Por task: achado não resolvido em qualquer gate do escopo per-task bloqueia o commit. Corrija, rode de novo, commite.
• No fechamento: achado não resolvido bloqueia marcar a PBI como concluída — a menos que seja comprovadamente pré-existente (confirmado com git stash), aí vira Blocker no STATE.md e é reportado no resumo.
• Um gate habilitado que não pôde rodar (skill ausente, MCP indisponível, Docker ausente, SONAR_URL / SONAR_TOKEN não configurados) é reportado como PULADO com o motivo. Nunca como APROVADO, nunca omitido, e nunca bloqueia.
• Um gate desligado é reportado como DESATIVADO — não é PULADO, não é Blocker.

Gate de build, antes do review

Com todas as tasks prontas, a skill roda o gate de tier Build de cada repositório tocado — mesmo que nenhuma task individual tenha declarado gate build — antes de chamar o review. Gates por task frequentemente rodam só o tier de testes, e alguns runners transpilam sem type-check completo: um erro de compilação pode sobreviver a todos os gates por task e só aparecer no build.

O ciclo de review

Ao fechar uma PBI completa, a skill chama o makuco-code-review sozinha e só segue quando existe veredito.

build verde → review (rodada 1)
                ├─ APROVADO              → gate completo → PBI concluída
                └─ NECESSITA CORREÇÕES   → passada de correção → build + gate escopado → review (rodada 2)
                                              ├─ APROVADO            → gate completo → PBI concluída
                                              └─ NECESSITA CORREÇÕES → teto: a decisão volta para você

O review roda no mesmo contexto, nunca num subagente. Se o contexto da sessão já estiver carregado demais para um review sério, a skill diz isso e pede que você rode o makuco-code-review num chat novo — a sessão retoma do veredito gravado.

A passada de correção

Quando o veredito é NECESSITA CORREÇÕES, a skill volta ao step-04 só nas tasks apontadas:

• grava o commit de partida da correção;
• achado que não cabe em nenhuma task existente vira task nova no task.md, com a linha Corrige: achado #N (rodada M) — nunca uma edição sem rastro;
• roda o mesmo loop RED → GREEN → VERIFY → COMMIT, com um commit por achado, prefixado fix(review):;
• achado que ela considera falso-positivo é contestado por escrito, com o código que sustenta o argumento. A rodada seguinte tem que responder mantido ou aceito;
• entre rodadas roda só o gate escopado (build dos repos tocados + escopo per-task nos arquivos corrigidos). O gate completo espera a aprovação.

O teto de duas rodadas

Na segunda rodada com achado bloqueante ainda aberto, o ciclo pára. A PBI fica pausada, com um relatório do que continua aberto — cada achado com o que a correção tentou e por que não resolveu — e os achados contestados com o argumento. Os achados abertos entram como Blockers no STATE.md, o handoff lista o que falta, e o work item fica em andamento, nunca finalizado.

A decisão volta para você:

PBI de correção, vinda de uma investigação

Quando a análise rodou em modo INVESTIGAÇÃO, a pasta da feature tem um rca.md, e a PBI é uma correção. O caminho é o mesmo — spec, tasks, implementação, review — com quatro regras a mais:

• A causa é lida, não re-derivada. O rca.md já fixa o mecanismo em arquivo:linha; a skill abre essas linhas antes de escrever a spec.
• As linhas citadas são relidas no HEAD. Se o código mudou desde o commit do laudo, a skill diz e confirma com você.
• Requisito condicional continua condicional. A verificação é uma PBI própria e vem antes da correção que ela destrava.
• O teste de regressão é critério de aceite, e cobre a classe do bug — não só a reprodução.

A spec.md referencia o rca.md e os ids RF-NN/CA-NN que ele já traz, sem repetir o mecanismo.

Artefatos gerados

.makuco/docs/modules/module_NNN_nome/feature_NNN_nome/pbis/pbi-NNN-slug/
├── sessao-dev.md   # estado da sessão — inclui rodadas de review, correções e contestações
├── spec.md         # spec de escopo de dev desta PBI, com a tabela Decisões técnicas
└── task.md         # quebra em tasks atômicas

Esses três são estado de trabalho da própria skill — escritos direto, sem passar pelo makuco-copy-writer e sem nunca tocar o status.yml. O review.md e o sessao-review.md da mesma pasta são do makuco-code-review.

Fora da pasta da PBI: .makuco/STATE.md (decisões, blockers, lições, ideias adiadas) e .makuco/HANDOFF.md (só quando a PBI é pausada — no meio das tasks, ou no teto do ciclo de review; uma PBI completa e aprovada não gera handoff).

Por que a metodologia de spec/task vive dentro da skill

A metodologia aplicada — specify.md, tasks.md, implement.md, quick-mode.md — é entregue dentro desta skill, não como uma skill separada que ela chama. Nada no fluxo depende de outra skill de metodologia estar instalada, então ele se comporta de forma idêntica em qualquer projeto.

O makuco-quality-gate é o caso oposto: é uma skill real instalada ao lado desta, e duplicar as definições dos gates aqui criaria uma segunda fonte da verdade que divergiria. Por isso ela é invocada em runtime.

Configuração que a skill lê

• .makuco/integrations/azure-devops.yml — type-map, estados, custom fields, org/projeto. As tools são descobertas em runtime pelo nome vindo desse config, nunca chumbadas. Ausente → a skill oferece configurar e só cai para local-only se você recusar.
• .makuco/docs/codebase/* — stack/arquitetura/convenções. Única fonte para o roteamento por gap, para a análise de reuso da spec e para o que a rodada de dúvidas deixa de perguntar. Em workspace multi-repo, resolvido por repo com fallback: prefere repos/<nome>/.makuco/docs/codebase/*, senão a raiz.
• Artefatos do makuco-analisar — feature.md, decisions.md, discovery.md, rca.md, pbis.md, DESIGN.md/EXPERIENCE.md. Lidos, nunca duplicados nem reescritos.
• .makuco/integrations/quality-gate.yml — sonar e complexity (true/false) e, opcional, sonar_project_key. É o único que liga os gates 3 e 5; ausente ou false, eles ficam desativados, sem erro.
• sonar-project.properties na raiz do repo — pré-requisito do gate do SonarQube quando ele está ligado, e fonte do sonar.projectKey quando o quality-gate.yml não traz a chave. A presença desse arquivo não liga mais o gate sozinha.

Sync com o tracker

Só roda quando o modo é ado. É unidirecional: local → tracker, nunca o contrário — a skill empurra o resultado local para o work item e nunca lê o estado do tracker de volta.

Mover um work item para o estado terminal exige confirmação explícita, e só é oferecido depois que existe veredito. Fechar um card é uma ação de alta visibilidade e nunca é automática. Se você recusar, o estado no tracker fica intocado e a recusa é registrada no resumo final. Uma PBI pausada — inclusive no teto do ciclo de review — vai para o estado de andamento, nunca para o terminal. Um sync que falha (auth, rede, item obsoleto) é reportado e nunca bloqueia o fechamento local.

Gatilhos

desenvolver PBI, pegar work-item, implementar item, dev de PBI, tenho um ADO id ou PBI local pronto para desenvolver, continuar desenvolvimento, retomar sessão de dev.

Modelos sugeridos

Próximo passo

Nenhum, dentro desta PBI: o review já roda no fechamento, e a documentação pós-aprovação é acionada por ele. Para revisar uma branch, um PR ou um diff avulso fora desse ciclo, o makuco-code-review continua invocável direto, sem nenhuma mudança.