mrachny/decision-matrix-skill

Matriz de Decisão

Uma matriz de decisão ponderada transforma "não consigo decidir" em um número defensável e inspecionável — mas o número só é tão bom quanto os critérios, pesos e a pesquisa por trás dele. Seu trabalho é pensar (o que importa, quanto, quão bem cada opção realmente atende), não apenas preencher uma tabela. O relatório HTML no final é um subproduto de fazer esse pensamento bem feito, não o objetivo do exercício.

1. Verifique se a decisão realmente se encaixa neste método

Este método brilha quando há de 2 a 8 opções discretas e vários critérios que puxam em direções diferentes (mais barato vs. mais agradável, mais rápido vs. mais seguro). É exagero ou a ferramenta errada quando:

• Há realmente apenas um fator que importa ("qual é mais barato") — responda isso diretamente.
• É uma decisão sim/não, não uma escolha entre alternativas.
• O espaço de opções é efetivamente ilimitado (ex.: "onde devo morar" sem uma lista restrita ainda) — ajude a pessoa a restringir para uma lista curta primeiro, depois execute a matriz na lista curta.

Se couber, diga isso brevemente e siga em frente — não faça a pessoa justificar o uso de uma matriz de decisão para você.

2. Captura em uma única mensagem — não entreviste campo por campo

Perguntar "qual é a decisão", depois "quais são as opções", depois "o que importa para você", depois o peso de cada critério um de cada vez, transforma uma decisão de 2 minutos em um arrasto de 15 mensagens. Peça a decisão, as opções e uma noção aproximada das prioridades juntos, em uma única mensagem, e dê um exemplo para que a pessoa saiba quão pouco esforço uma boa resposta exige:

"O que você está decidindo, quais são as opções e o que mais importa para você — aproximado está totalmente bem, eu transformo em uma comparação limpa. Ex.: 'Escolhendo entre 3 ofertas de emprego — Acme, Globex e ficar no meu emprego atual (Initech). Eu me importo principalmente com salário, quanto eu cresceria e não ter um trajeto brutal.'"

Se eles derem uma resposta enxuta (apenas as opções, sem prioridades), tudo bem — vá para a etapa 3 e proponha prioridades para eles, em vez de perguntar novamente.

3. Proponha um rascunho editável — critérios, definições e pesos juntos

Não colete critérios e depois colete pesos separadamente. Pesquise o que normalmente importa para esse tipo de decisão (uma oferta de emprego e um apartamento não compartilham critérios) e devolva um rascunho completo — de 5 a 10 critérios, cada um com uma definição de uma linha e um peso sugerido (1-10) — para a pessoa editar em uma única passagem, em vez de construir a partir do brainstorming em página em branco ou perguntar sobre cada um por vez. Empurre gentilmente (ainda dentro deste rascunho, não peça permissão primeiro) se a lista deles ultrapassar ~10 — mescle ou descarte aqueles que se repetem.

Deixe as pessoas responderem da forma mais fácil — um número, ou apenas "alto/médio/baixo" (mapeie aproximadamente para 9/6/3) — e aceite uma resposta tão leve quanto "parece bom" ou "tire o trajeto, aumente o salário para 10". Exemplo do que enviar:

"Aqui está um rascunho para comparar ofertas de emprego — edite qualquer linha, adicione/remova uma, ou apenas diga 'parece bom':

Critério	O que significa	Importância (1-10)
Salário	Compensação total (salário + bônus + ações), ano um	9
Crescimento	Quanto mais você aprenderia/cresceria nesta função	8
Trajeto	Tempo porta a porta, em um dia típico	6
Estabilidade	Probabilidade de o cargo/empresa ainda existir em 2 anos	7
Equipe e cultura	Qualidade das pessoas e do dia a dia	7

Algo a adicionar — como plano de saúde ou flexibilidade remota?"

Duas coisas importam mais do que as pessoas esperam, uma vez que o rascunho é confirmado:

• Mantenha a definição de cada critério, não deixe que ela colapse de volta a um rótulo simples. "Crescimento" é ambíguo; "crescimento = quanto mais eu aprenderia nesta função no primeiro ano" é pontuável. Sem ela, suas próprias notas vão derivar inconsistentemente entre as opções.
• Cuidado com critérios que contam duas vezes a mesma coisa subjacente (ex.: "salário" e "segurança financeira" frequentemente colapsam em um único fator) — mesclá-los mantém os pesos honestos.

4. Trave e siga em frente

Uma rodada de edição normalmente é suficiente — uma vez que a pessoa confirma (ou não se opõe), trate critérios, definições e pesos como travados e vá direto para a pesquisa na etapa 5. Não peça para eles reconfirmarem números que você já mostrou; se precisar mudar algo depois (ex.: um critério se mostra impossível de pontuar), diga o que está mudando e por que, em vez de reabrir todo o rascunho para aprovação.

5. Pesquise e pontue cada célula opção × critério (1-10)

Esta etapa é onde o trabalho real está, e onde um agente ganha seu sustento sobre um modelo simples. Para cada célula:

• Pesquise de verdade — use busca/ferramentas para encontrar o fato relevante (preço, especificação, avaliação, dados salariais, resenha, política) antes de pontuar. Não invente um número de aparência precisa a partir de impressões.
• Ancore a escala consistentemente dentro de um critério. Decida o que 1 e 10 significam para este critério (ex.: "10 = mais barato entre estas opções" ou "10 = atende a todos os requisitos obrigatórios") antes de pontuar a primeira opção, e mantenha essa âncora em todas as opções para que as notas sejam comparáveis. Escreva essa âncora uma vez por critério em suas próprias anotações.
• Dê uma justificativa de uma frase por célula, nomeando o fato ou fonte por trás do número. Essa justificativa é o que torna o relatório confiável e é mostrada no alternador "por que" do relatório HTML.
• Diga quando você está supondo. Alguns critérios são genuinamente subjetivos (ex.: "entusiasmo", "intuição") ou mal documentados. Pontue esses a partir do julgamento declarado da própria pessoa e sinalize na justificativa que é subjetivo/não verificado, em vez de apresentá-lo com falsa precisão. Nunca invente uma fonte.

6. Calcule o total ponderado

Para cada opção: nota_ponderada = Σ(peso_i × nota_i) / Σ(peso_i), uma média normalizada de 1 a 10. Isso mantém o total na mesma escala de 1 a 10 das entradas, o que facilita a verificação de sanidade.

7. Entregue a tabela Markdown primeiro

Antes de construir o HTML, mostre o resultado no chat como uma tabela: opções como linhas ordenadas da melhor para a pior, critérios como colunas (apenas a nota, para manter a legibilidade) e uma coluna final de total ponderado. Siga com 2 a 3 frases nomeando a melhor opção, a segunda colocada e o maior fator que as separa — e sinalize claramente se as duas primeiras estão próximas o suficiente para que o "vencedor" seja realmente um cara ou coroa.

8. Construa o relatório HTML interativo

Escreva um arquivo de dados JSON correspondente ao esquema abaixo e então execute:

python3 scripts/build_report.py data.json report.html

Isso injeta seus dados no mecanismo de assets/report_template.html e escreve um único report.html auto-contido (sem servidor, sem recursos externos além de uma fonte do Google — funciona ao clicar duas vezes no arquivo). O script valida os dados e falha com uma mensagem específica se algo estiver faltando ou fora do intervalo.

Esquema de dados

{
  "meta": {
    "title": "Qual apartamento devo alugar?",
    "subtitle": "Comparando 4 listagens no mesmo bairro",
    "description": "Uma ou duas frases curtas e simples de contexto. Exibido abaixo do título.",
    "direction": "ltr",
    "credit": "Matriz de decisão por <seu nome>",
    "credit_url": "https://github.com/mrachny/decision-matrix-skill"
  },
  "criteria": [
    { "id": "aluguel", "label": "Aluguel mensal", "description": "10 = mais barato dos quatro, 1 = mais caro.", "weight": 9 }
  ],
  "options": [
    { "id": "optA", "label": "Apartamento na Rua Elm", "included": true }
  ],
  "scores": { "optA": { "aluguel": 7 } },
  "notes": { "optA": { "aluguel": "₪5.200/mês, o segundo mais barato dos quatro (fonte: listagem)." } }
}

• meta.direction é "ltr" ou "rtl"; omita para "ltr".
• O rodapé do relatório mostra uma pequena linha de atribuição "Gerado com uma matriz de decisão" por padrão. meta.credit / credit_url substituem seu texto/link; defina meta.credit como false se a pessoa explicitamente não quiser nenhuma linha de atribuição.
• criteria[].description e notes são opcionais, mas fortemente recomendados — eles se tornam o texto "por que" mostrado no relatório. Um critério ou célula sem descrição apenas não mostra justificativa, o que é aceitável para um rascunho rápido, mas enfraquece o relatório.
• options[].included (padrão true) define o estado de mudo inicial do relatório.
• Cada nota deve ser um número de 1 a 10. O script de construção verifica isso e a consistência de IDs entre criteria/options/scores antes de escrever qualquer coisa.

Diga à pessoa onde o arquivo está e que ele abre diretamente em qualquer navegador — pesos e os alternadores de mudo recalculam a classificação em tempo real, nada é enviado a lugar nenhum e nada é salvo a menos que ela mantenha o arquivo.

9. Convide para uma verificação de sensibilidade

Conclua apontando que o relatório foi feito para ser manipulado, não apenas lido: se desativar o critério mais duvidoso ou ajustar um peso inverter o vencedor, isso é um sinal real de que a decisão está acirrada e vale mais reflexão (ou que as diferenças não importam e a pessoa deve simplesmente seguir a intuição / custo / qual é mais fácil de reverter). Se a classificação for robusta a esse tipo de cutucada, isso também é um sinal útil.

Arquivos de referência

• references/method.md — contexto sobre o método, armadilhas comuns de pontuação (critérios correlacionados, compressão de peso, desvio de ancoragem) e como discutir um empate com a pessoa.
• assets/report_template.html — o mecanismo do relatório. Você não deve precisar editar isso manualmente; tudo personalizável flui através do arquivo de dados JSON.
• scripts/build_report.py — constrói o relatório; execute python3 scripts/build_report.py --help para uso além do mostrado acima.
• examples/laptop-purchase.json — um arquivo de dados de exemplo preenchido, se você quiser ver um completo antes de escrever o seu.