Analisar

makuco-analisar

Função

Porta de entrada da análise. Leva uma oportunidade vaga, um problema já entendido, um card já escrito ou um bug em produção até uma Feature documentada (PRD) e um conjunto de PBIs validadas por INVEST, prontas para o makuco-desenvolver. É uma skill de facilitação conversacional: cada passo pára e espera sua confirmação antes de seguir.

Uma feature, uma análise. A skill nunca produz um segundo conjunto de artefatos para uma feature que já tem os seus — ao detectar uma pasta feature_NNN_* do mesmo assunto, ela pára e pergunta se você quer continuar aquela.

Os quatro modos

O modo nunca é presumido — o passo 1 sempre pergunta.

Os três primeiros diferem no que já está decidido: DESCOBERTA ainda pergunta se, SOLUÇÃO pergunta como, EXPRESS não pergunta nenhum dos dois — alguém já decidiu, e o que falta é a forma documentada. INVESTIGAÇÃO fica fora desse eixo: ela pergunta por quê, e o que ela analisa já existe em produção.

• Um pedido de feature já claro e delimitado entra em SOLUÇÃO.
• EXPRESS é para item já definido. Quando não está claro o que o item entrega, a skill oferece SOLUÇÃO.
• Um bug cuja causa já é conhecida não é INVESTIGAÇÃO: é SOLUÇÃO, ou EXPRESS quando o card já diz o que mudar.

Pule a skill só quando as PBIs já existem e estão documentadas (pbi.md no disco). Para um card solto no Azure DevOps, use o EXPRESS.

Cada modo passa por exatamente um gate, ou por nenhum: DESCOBERTA pelo gate de produto (isso merece existir?), INVESTIGAÇÃO pelo gate de evidência (essa conclusão se sustenta?), SOLUÇÃO e EXPRESS por nenhum.

Fluxo em passos

step-01-setup              → resolve config, pergunta o modo, cria as pastas, escreve sessao.md, oferece retomar
                             (INVESTIGAÇÃO também: classe do sintoma + mapa de capacidades)
 ├─ DESCOBERTA   → step-02a-descoberta   → discovery.md + recomendação (Go / No-Go / Refinar)
 │                    └─ step-03-gate     → sempre roda → aprovado / reprovado / ajustar
 ├─ SOLUÇÃO      → step-02b-solucao      → rodadas de perguntas sobre a árvore de decisão de negócio,
 │                                          marca validation_approved = true, nunca carrega o gate
 ├─ INVESTIGAÇÃO → step-02d-investigacao → evidência, matriz de hipóteses, falsificadores executados
 │                    └─ step-03b-refutacao → subagente adversarial + gate de evidência → rca.md
 │                         ↓ (os três acima convergem aqui)
 │                   step-04-feature      → feature.md (PRD) + decisions.md
 │                         ↓
 │                   step-05-pbis         → PBIs uma a uma, validadas por INVEST → pbis.md + pbi.md + diagrama
 │                         ↓
 └─ EXPRESS      → step-02c-express      → lê o card inteiro (+ imagens) → esclarece → feature.md +
                    (pula 2a/3/4/5)        decisions.md + UMA pbi.md + pbis.md
                         ↓ (só se alguma PBI tem tela)
                   step-05b-ux-proposal  → aciona makuco-ux → DESIGN.md + EXPERIENCE.md
                         ↓
                   step-06-fechamento    → handoff para makuco-desenvolver + decisões no STATE.md

Cada arquivo de passo é auto-contido: a skill carrega só o que o fluxo precisa no momento (progressive disclosure). Depois do step-06 o caminho é o mesmo para todos os modos: o makuco-desenvolver implementa cada PBI e o makuco-code-review revisa.

Modo SOLUÇÃO — interrogatório de negócio

O SOLUÇÃO percorre uma árvore de decisão de negócio, em rodadas de perguntas.

A árvore

                  ── PERGUNTADO ──
L0  pré-requisitos — o problema, quem é afetado, restrições
L1  a dor — quem sente, com que frequência, o que faz hoje (contorno), quanto custa
L2  o fluxo principal — o caminho feliz, em passos de negócio
L3  regras de negócio — condições, exceções, casos especiais, conflito com regra existente
L4  limites — fora do escopo · pre-mortem · casos de borda
                  ── DERIVADO, NUNCA PERGUNTADO ──
D1  requisitos funcionais — as capacidades que as regras implicam
D2  critérios de aceite — como cada requisito é verificado
D3  porte — contagem de requisitos × cenários

A cada rodada, a skill pergunta só o que já pode ser perguntado — um nó cujos pré-requisitos estão fechados. L3 depende de L2, e L4 depende de L2 e L3.

As rodadas

Antes da primeira pergunta, a skill faz a própria lição de casa: lê o OVERVIEW.md e os docs de módulo, o .makuco/STATE.md e o vocabulário do MAKUCO.md, e diz num bloco curto o que o produto já faz. Fato é trabalho dela; decisão é sua — nada que o projeto responde vira pergunta.

Cada rodada tem 3 a 5 perguntas numeradas, e toda pergunta vem com a resposta recomendada pela skill. Um exemplo do formato:

❓ Q1 — Quem aprova: Quem pode liberar o pedido bloqueado — só o gestor da loja, ou qualquer
   pessoa com o perfil financeiro?
 
➡️ Só o gestor da loja: é o único papel que o fluxo atual já responsabiliza pelo bloqueio.

Decisões fechadas podem virar opções de múltipla escolha; justificativas são sempre texto livre.

O que a skill cobra e o que ela nunca pergunta

• Cobra especificidade. "Melhorar a experiência" ou "tratar o erro adequadamente" voltam como pergunta: qual erro, mostrado a quem, registrado onde. A skill pede um caso real e recente; sem ele, a dor fica registrada como suposição, não como fato. Número sem base entra como [definir meta].
• Nunca pergunta requisitos nem critérios de aceite. Eles saem das suas respostas: cada regra de negócio vira a capacidade que ela implica, e cada capacidade ganha o critério que a verifica. Requisito sem origem na conversa é inventado e fica de fora.
• Nunca pede métrica de sucesso. Se você oferecer uma, ela é registrada; se não, o PRD diz que a feature não tem métrica.
• Nunca faz pergunta técnica — arquitetura, endpoint, schema, framework, protocolo de integração, orçamento de performance, infraestrutura, estratégia de teste. Isso fica com o makuco-desenvolver. Detalhe técnico que você oferecer vira restrição, nas suas palavras.
• Separa regra de requisito, e mostra a separação. "Se o estoque zerar, ocultar o produto" é regra; "o sistema deve permitir ocultar produtos sem estoque" é requisito.
• Não rascunha as regras de negócio. Só os candidatos a fora do escopo podem ser oferecidos, explicitamente como candidatos.

Porte, alternativas e síntese

Com a árvore fechada, a skill conta os requisitos e os cenários de aceite. Se o total passar da régua de 3 a 8 cenários por PBI, ela pergunta uma vez se você quer quebrar a entrega, já com uma linha de corte concreta. "Seguir com um só" encerra o assunto.

Alternativas rejeitadas só entram no PRD quando uma bifurcação real apareceu nas perguntas. Quando a solução já chegou decidida, o PRD diz exatamente isso.

A síntese é apresentada uma vez, com os requisitos e critérios derivados, e segue direto para o PRD. As correções acontecem na revisão do PRD, não numa rodada de aprovação item a item.

Modo EXPRESS — do card ao PRD

Para o item já decidido e escrito: um card do Azure DevOps ou uma lista curta de requisitos. O card é a PBI. O EXPRESS pula o meio do fluxo (brainstorming, gate, decomposição), mas nunca a leitura nem as perguntas.

1. A origem

A skill pergunta de onde vem o item:

• Card do tracker — informe o id ou a URL do work item. Sem .makuco/integrations/azure-devops.yml, a skill diz isso numa linha e pede que você cole o conteúdo do card; ela nunca finge ter lido um card que não conseguiu buscar.
• Requisitos — cole o que já está definido. É um caminho de primeira classe, não uma degradação.

Se o tema informado for só o id do card, a skill lê o título do work item para nomear a pasta — nunca usa o id puro no nome.

2. A leitura inteira do card

A skill pede ao makuco-azure-devops a leitura completa: campos, comentários e anexos, inclusive as imagens coladas no meio da descrição, dos critérios e dos comentários. As imagens são baixadas para anexos/ e abertas uma a uma.

De cada imagem a skill registra o que é factual: texto visível, campos de formulário, estados mostrados, navegação, regras visíveis. Imagem que não abre entra como NÃO LIDA: {motivo}, a contagem lidas/total é informada, e uma imagem não lida que parece essencial vira pergunta obrigatória.

3. As perguntas, antes de montar qualquer coisa

Só o que o card não responde: contexto de negócio, quem é o afetado, critério de sucesso, o que fica fora do escopo, restrições conhecidas — e, quando for o caso, qual lado vale numa divergência entre o texto e a imagem (a decisão é sua) e o conteúdo de uma imagem que não pôde ser lida. Depois, a pergunta de sempre sobre onde ficam as regras de negócio.

4. INVEST como relatório, não como gate

A tabela INVEST roda sobre o item, mas no EXPRESS um ⚠️ não bloqueia. Um alerta em S (grande demais) ou I (dependente) oferece dividir em mais de uma PBI ou manter uma só; mantido, o ⚠️ fica registrado no pbi.md, à vista de quem for desenvolver.

5. O PRD e a PBI

• Nada é inventado para preencher uma seção. O que a origem não cobre sai como Não informado na origem — a confirmar, visível.
• Alternativas — quando não houve nenhuma, o PRD diz: Não houve avaliação de alternativas — análise express sobre item já decidido.
• Mockups e evidências — uma linha por imagem aberta, com os requisitos que saíram dela, mais as NÃO LIDA com o motivo.
• Exatamente uma PBI, a menos que você tenha escolhido dividir no INVEST. O diagrama é oferecido, e o padrão é pular.

O EXPRESS nunca cria work item — o card é vinculado, não duplicado. Ao final, a skill oferece um comentário no card apontando para os artefatos gerados. Nada além disso: sem reescrever descrição, sem mudar estado, sem tocar em campo.

Modo INVESTIGAÇÃO — causa raiz de um bug

Para quando algo já quebrou em produção e a causa é desconhecida. A skill resolve quais fontes o projeto realmente tem (código, log, métrica, tracker, borda), monta a cadeia causal com arquivo:linha fixado num commit, executa os falsificadores que só leem e manda a tese para um subagente adversarial tentar derrubar antes de escrever o laudo. O resultado vira rca.md e refutacao.md, e daí para frente o fluxo é o de sempre: PRD, PBIs de correção, makuco-desenvolver e makuco-code-review.

A análise nunca corrige: quem acha e quem conserta continuam separados. O modo tem página própria: Investigação de bug.

O gate de produto (só em DESCOBERTA)

Depois do discovery.md, a skill pausa e pede que você apresente o documento ao aprovador configurado em MAKUCO.md (analise.aprovador). Ao voltar, informe:

• aprovado — avança para a documentação da Feature;
• reprovado — encerra o processo e registra a decisão no discovery.md;
• ajustar [o que] — volta ao brainstorming para refinar.

O gate é uma decisão humana, não um gate técnico, e não é configurável: ele é parte do que significa o modo DESCOBERTA.

Brainstorming (só em DESCOBERTA)

A skill carrega 61 técnicas de brainstorming (10 categorias) sob demanda — nunca o catálogo inteiro de uma vez — em quatro modos de seleção: usuário escolhe · IA recomenda · aleatória · fluxo progressivo.

Um protocolo anti-viés roda em paralelo: a cada ~10 ideias, o eixo criativo é rotacionado (técnico → UX → viabilidade de negócio → edge cases → mercado) e as personas do projeto são alternadas conforme o MAKUCO.md / makuco-product-context. Nenhuma persona é chumbada na skill.

Validação INVEST — obrigatória por PBI

Nenhuma PBI é criada sem passar pelos seis critérios:

Cada PBI é proposta uma a uma, com a tabela INVEST preenchida, e você aprova, ajusta ou remove. Um ⚠️ não resolvido bloqueia a criação da PBI — exceto no EXPRESS, onde ele é reportado e fica registrado, sem bloquear.

Artefatos gerados

.makuco/docs/modules/module_NNN_nome/feature_NNN_nome/
├── discovery.md      # só no modo DESCOBERTA
├── anexos/           # só no modo EXPRESS — imagens do card, lidas na análise
├── rca.md            # só no modo INVESTIGAÇÃO — o laudo técnico
├── refutacao.md      # só no modo INVESTIGAÇÃO — o veredito do estágio adversarial
├── feature.md        # o PRD
├── decisions.md      # log de decisões, com as alternativas rejeitadas (nunca vai para o tracker)
├── pbis.md           # a decomposição, dependências e a justificativa
├── sessao.md         # estado da sessão (escrito direto pela skill)
├── status.yml        # progresso do fluxo (escrito SÓ pelo makuco-copy-writer)
└── pbis/
    └── pbi-NNN-slug/
        ├── pbi.md            # o que entrega, CAs, tabela INVEST
        ├── diagrama.puml     # fluxo de informação (opcional)
        └── DESIGN.md
            EXPERIENCE.md     # só se o step-05b rodou

Todos os modos produzem a mesma forma de artefatos e o mesmo status.yml. O INVESTIGAÇÃO acrescenta dois documentos técnicos ao lado, sem inventar um segundo layout.

O que a skill delega

As registrações no tracker são enfileiradas durante o loop de PBIs e criadas em um único lote confirmado ao final — nada é escrito no tracker no meio do caminho.

Configuração que a skill lê

• MAKUCO.md — frontmatter YAML, chave analise.aprovador (papel genérico / nome / nenhum).
• .makuco/integrations/azure-devops.yml — presente habilita a criação de work items e a leitura do card no EXPRESS; ausente, a skill oferece configurar e só cai para local-only se você recusar. Veja Azure DevOps.
• .makuco/integrations/observability.yml — só no INVESTIGAÇÃO, lido pelo makuco-observability-context. Veja Configurações.
• MAKUCO.md / makuco-product-context — vocabulário de domínio (personas, dimensões, tipos de item) usado nos templates, no eixo anti-viés e nos fatos que o SOLUÇÃO busca em vez de perguntar.

Gatilhos

analisar feature, iniciar análise, brainstorming profundo, nova descoberta, viabilizar solução, gerar PRD, criar PBIs com INVEST, processo de análise, discovery mais profundo, análise rápida/express, gerar PRD a partir do card/work item, já tenho o card pronto — ou investigar bug, achar a causa raiz, RCA, por que quebrou em produção, analisar erro/5xx/timeout/lentidão.

Modelos sugeridos

Próximo passo

As PBIs prontas seguem para o makuco-desenvolver — sempre com o id da PBI, nunca o da Feature. A ordem sugerida de implementação está na seção de dependências do pbis.md. Numa investigação, as PBIs de verificação vêm antes das de correção que elas destravam, e a remediação de dados vem por último.