ajitta/know-your-unknowns

Loop de Incógnitas — loop operacional para trabalhar com modelos fortes

Princípio central: o gargalo com modelos fortes não é o modelo — é a capacidade do usuário de manter o mapa (plano) alinhado ao território (realidade). Essa lacuna são as incógnitas. Projetar o ciclo explorar → perguntar → planejar → implementar → registrar desvios → verificar é mais importante do que um bom prompt. Origem: os 11 exemplos "Conheça suas incógnitas"; o loop em si é uma extensão do plugin — veja skills/loop/references/talk-source.md.

Saída: Ferramenta de artefato → .unknowns/<YYYY-MM-DD>-loop-<slug>.html → markdown. O artefato de cada etapa mantém seu próprio controle de reação da skill; o controle do loop é o ponto de verificação por etapa, que é montado no rastreador .unknowns/loop.json. Detalhes: skills/loop/references/output-routing.md

Etapas (10 — reduza conforme o tamanho)

1. Definir valor e critérios de conclusão

Alinhar com o usuário antes de começar: propósito / valor para o usuário / critérios de conclusão / comportamento existente que nunca deve quebrar / escopo de custo e mudança permitidos. Sem critérios de sucesso, o volume de implementação é confundido com progresso.

2. Investigação de pontos cegos → /unknowns:blindspot (ou /blindspot para instalações copiadas)

Apenas investigar, sem implementar. Encontrar incógnitas desconhecidas, pontos de conflito, riscos de regressão; produzir um prompt melhorado. Se o próprio domínio for desconhecido (solicitações vagas porque os termos são desconhecidos), execute /unknowns:teach-me em conjunto.

3. Entrevista → /unknowns:interview

Primeiro as perguntas que alteram a arquitetura, no máximo 4 por rodada.

4. Explorar soluções e modelar (conforme necessário)

• O que fazer indeciso → /unknowns:brainstorm (mapa do espaço de soluções)
• Não consegue descrever como deve ser em palavras → /unknowns:prototypes (mockups divergentes)
• Tem exemplo a emular → /unknowns:reference (análise de referência)

5. Protótipo de suposição arriscada (conforme necessário)

Antes da implementação completa, construir protótipo mínimo verificando apenas a suposição técnica mais incerta. Declare a suposição e os critérios de sucesso/fracasso primeiro.

6. Planejar → /unknowns:plan

Plano ajustável ordenado por probabilidade de revisão, não por ordem de execução. Decisões que precisam de entrada do usuário (esquemas, interfaces, contratos de UX) ficam no topo.

7. Implementar + registro de desvios → aplicar regras de /unknowns:notes

Registre tudo que não estiver no plano; pare e pergunte sobre decisões que envolvam arquitetura, comportamento visível ao usuário, dados ou segurança. Se a conversa foi compactada, re-invoque /unknowns:notes (e esta skill para a lista de etapas) antes de continuar a implementação.

8. Verificação independente → agente unknowns:independent-reviewer

Invoque-o com a ferramenta de Agente (subagent_type: unknowns:independent-reviewer). Nunca um fork ou /subtask — eles herdam o contexto do implementador, que é exatamente o que esta etapa existe para excluir. Entregue ao agente: critérios de conclusão (etapa 1), o plano aprovado (etapa 6), o caminho do IMPLEMENTATION_NOTES.md, o intervalo de diff / arquivos tocados e como executar os testes. Nunca entregue o resumo do próprio implementador.

9. Verificação de compreensão e handoff → /unknowns:quiz

Verifique se o usuário consegue explicar este trabalho em um PR ou handoff. Se o trabalho precisar de aprovação do revisor ou stakeholder, produza também um documento /unknowns:buy-in.

10. Revisão de valor

Avalie pelo valor real, não pela qualidade do código: o problema de quem diminuiu e qual / quanto mais rápido / razões pelas quais pode não ser usado / métricas / condição de remoção. Construir é mais fácil, gerar valor ainda é difícil. Encerre capturando uma linha do scorecard — pergunte ao usuário se isso revelou algo que ele não sabia e se mudou uma decisão, depois anexe a linha a .unknowns/scorecard.md. Nunca responda a essas duas perguntas por ele, e escreva a linha mesmo quando ambas as respostas forem não. Detalhes: skills/loop/references/scorecard.md

Critérios de redução

• Correção pequena (1–2 arquivos, especificação clara): apenas regras da etapa 7 (notas) — nenhum loop necessário.
• Trabalho médio: 1 (uma troca) → 2 → 3 → 6 → 7 → 9.
• Trabalho grande ou desconhecido: todas as etapas, com 4 e 5 apenas conforme necessário.
• A etapa 1 é executada em todos os níveis. Não souber o nível → pergunte ao usuário e registre a escolha.

Status do loop (sobrevive a compactação, /resume, novas sessões)

Mantenha .unknowns/loop.json — {task, tier, stage, decisions[], artifacts[]} — e reescreva-o a cada mudança de etapa. Feche cada etapa com um ponto de verificação AskUserQuestion (continuar / pular / parar) e registre a resposta lá.

• Argumento status: ler o arquivo; relatar nível, etapa atual, etapas restantes.
• Argumento resume: ler o arquivo; continuar a partir da etapa registrada.
• Qualquer outro texto de argumento é a descrição da tarefa.
• Sem argumento: retomar .unknowns/loop.json se existir, caso contrário pedir a tarefa primeiro.

Princípios operacionais (resumidos)

1. Definir propósito. 2. Encontrar pontos cegos antes de implementar. 3. Fazer o modelo fazer perguntas. 4. Fornecer referências e protótipos em vez de palavras. 5. Ordenar planos por probabilidade de revisão. 6. Registrar incógnitas e desvios do plano. 7. Verificar com testes e revisão independente. 8. Confirmar que o usuário consegue explicar o resultado. 9. Entregáveis em formato reativo. 10. Medir valor real, não volume de código.