Xs-trek/frame-align

frame-align: alinhe o framework primeiro, depois implemente

O que este skill resolve

O usuário chega com uma ideia de software. Pode ser apenas uma frase, um esqueleto com partes faltando, um rascunho com erros, um problema travado, ou algo diferente. Se você começar a implementar diretamente, provavelmente criará algo que ambos pensavam que o outro entendia, mas na verdade não.

Este skill permite que você e o usuário alinhem o framework antes de começar: você coloca seu entendimento e propostas em uma página, o usuário responde com cliques e anotações, e assim por diante, até que o usuário considere o framework aprovado, para então passar ao preenchimento do conteúdo.

A métrica de sucesso é se o usuário conseguiu alinhar com mais facilidade. Se, depois de carregar este skill, o usuário tiver que ler, preencher e esperar mais, é uma falha, mesmo que o processo seja seguido perfeitamente.

Dois tipos de falha devem ser evitados simultaneamente:

• Pesado demais: o processo e o formato te engessam, ideias diferentes recebem perguntas iguais, e sua própria percepção e criatividade não aparecem.
• Leve demais: você pula o alinhamento e já entrega uma solução, ou a página é apenas uma versão repaginada da conversa normal, sem diferença de não usar o skill.

O ponto certo é: o formato do ciclo é fixo, mas o conteúdo dentro dele é seu. Comece sempre pelo mais leve. Só aumente o peso quando os meios leves não forem suficientes.

Começar, continuar ou retrabalhar

Verifique se existe .frame-align/state.js no diretório de trabalho atual.

• Não existe: começar.
• Existe, phase está como framing: não foi concluído da última vez. Leia o estado, informe ao usuário em que rodada parou, o que estava fazendo, e continue de onde parou.
• Existe, phase está como filling: retrabalho, veja a seção "Retrabalho".
• O usuário diz que é outra ideia: pergunte primeiro o que fazer com a antiga; por padrão, renomeie o diretório antigo para preservá-lo e comece.

Começar

1. Leia antes de perguntar. Arquivos que o usuário mencionou, o repositório de código, documentação existente — tudo que você puder ler por conta própria, leia. Se já houver código, apresente o que leu como parte do seu entendimento para ele confirmar, não pergunte novamente.
2. Reafirme com suas próprias palavras. Escreva um parágrafo com seu entendimento da necessidade dele, sem copiar as palavras dele. Copiar não prova que você entendeu; reformular é que revela desvios.
3. Escolha um preset. Se ele chamou e especificou um nome, use esse. Caso contrário, escolha você e explique em uma frase no "O que estamos fazendo nesta rodada" da página inicial. Ele pode trocar. Veja "Ações e Presets".
4. Gere a página inicial. A página inicial contém apenas: a fala original dele, mantida exatamente como ele disse no topo (é a âncora do objetivo, só ele pode alterar); seu entendimento; o conteúdo da primeira rodada conforme o preset; uma caixa de texto livre para qualquer entrada; e um botão de enviar. Ao lado da caixa de texto, adicione: "Se for conveniente, conte um pouco sobre seu background técnico. Se não, tudo bem." Você pode incluir algumas opções de experiências relacionadas ao projeto para ele clicar. Pergunte sobre a experiência, não teste.

A página inicial é a primeira impressão do usuário sobre este skill, e também o momento em que você menos sabe sobre ele. Portanto, deve ser a página mais leve de todas.

Como funciona uma rodada

1. Verifique. Confira se os arquivos que você está usando como base mudaram; o usuário pode ter alterado algo durante a interação. Se mudaram, releia e marque os nós que dependem deles como "base alterada".
2. Explore. Leia código, pesquise, pense. A decisão de como fazer é sua. Há dois limites: antes da saída, não escreva código de produção, não monte infraestrutura, não instale dependências. Qualquer coisa que envolva executar o código do projeto, chamar serviços externos ou escrever arquivos fora de .frame-align/, pergunte primeiro. Se quiser fazer um experimento único e pequeno, em um diretório temporário fora do projeto, também pergunte primeiro.
3. Escreva o estado. Escreva o estado atual do framework e a proposta desta rodada em .frame-align/state.js. O formato está em references/state-format.md.
4. Apresente. A página é pré-fabricada; você não escreve HTML, apenas o estado. Na primeira rodada, inicie o servidor da página em segundo plano e entregue o endereço ao usuário. Nas rodadas seguintes, basta escrever o estado; a página se atualizará sozinha quando o usuário enviar. A forma de iniciar e o fallback quando não há runtime estão em references/page-contract.md.
5. Aguarde o retorno. O usuário clica, escreve anotações na página e envia. A página salva o resultado em .frame-align/returns/round-N.txt. Ele avisa na conversa que terminou, e você lê o arquivo.
6. Ajuste. Leia o arquivo de retorno, atualize o framework, o log e as observações, e volte ao passo 1, ou vá para a saída.

Cada página deve ter uma ou duas frases explicando o que está sendo feito nesta rodada: o que você leu do feedback anterior, o que mudou por causa disso, e o que pretende fazer agora. Isso permite que ele saiba que seu feedback foi ouvido. Uma reafirmação completa só é fornecida em três momentos: no início, quando a direção muda, e antes da saída, cada vez com no máximo um parágrafo.

A conversa fora da página também deve ser leve:

• Ao entregar a página, diga apenas onde ela está e o que foi feito nesta rodada, uma ou duas frases. Não repita o conteúdo da página. Depois, pare e espere; não antecipe respostas.
• Os cliques na página não equivalem totalmente à intenção dele. O que ele escreve manualmente na conversa representa melhor o que ele quer. Se houver discrepância, prevalece o que ele escreveu, e isso deve ser adicionado ao arquivo de retorno da rodada.
• Não peça para ele copiar o resultado da página para a conversa. O retorno é via arquivo; a conversa é para as palavras dele.
• Responda diretamente perguntas que podem ser resolvidas em uma frase, registre o resultado no estado, e não abra uma nova rodada para isso.

Ações e Presets

Cada rodada seleciona uma combinação destas ações. O usuário pode pedir para trocar.

Ação	O que faz
Reafirmar	Escreva seu entendimento com suas palavras, peça confirmação
Divergir	Ofereça inspirações e direções
Completar	Aponte lacunas no framework. Para projetos de software, consulte references/lenses.md
Questionar	Aponte contradições, riscos, erros
Convergir	Ajude a escolher e priorizar entre múltiplas direções
Explicar	Responda a dúvidas que ele marcou

Na fase de divergência, questione pouco: o framework ainda não está estabelecido, e criticar cedo demais pode abafar ideias.

Presets: Intervenção inicial, que diminui com o feedback

No início, você não sabe quase nada sobre o usuário. O preset define a direção: o que fazer na primeira rodada, o que não fazer, e como prosseguir normalmente. Ele tem mais influência na primeira rodada. Depois, a cada rodada, o feedback do usuário dita as ações; o que o feedback não cobre, o preset preenche. Quanto mais feedback, menos o preset influencia. Quando ele não tiver mais relevância, pare de mencioná-lo.

Ao se desviar do preset, explique o motivo em "O que estamos fazendo nesta rodada". Se o usuário disser que nenhum preset se encaixa, monte você mesmo uma combinação.

Preset	O que o usuário trouxe	Primeira rodada	Curso normal
Semente	Uma frase ou uma ideia vaga	Reafirme, dê algumas direções. Não questione, não peça detalhes	Divirja até ele dizer que é suficiente, depois complete, depois convirja
Esqueleto	O framework geral existe, mas muitas partes estão vazias	Reafirme e desenhe o esqueleto, marque as lacunas, comece perguntando sobre a parte mais impactante	Complete uma a uma, verifique se tudo se encaixa, depois convirja
Revisão	Um rascunho relativamente completo, quer saber o que está errado	Reafirme, confirme que entendeu; aponte uma ou duas contradições ou riscos mais importantes	Alterne questionamento e correção, preencha lacunas, depois convirja
Ponto crítico	Um problema travado, ou algo que não tem certeza se é viável	Reafirme o problema, diga o que você acha ser o ponto chave e por quê, e dê a verificação que melhor diferencia as possibilidades. Não monte uma matriz de testes	Localize o ponto chave, faça a verificação mínima, defina a solução com base no resultado, depois complete e convirja

Ponto crítico: primeiro localize, depois teste

Quando o usuário traz um problema difícil, a abordagem mais desperdiçadora é testar todas as soluções possíveis uma a uma. Primeiro, descubra o ponto chave: qual fator tem mais chance de determinar o sucesso ou fracasso, qual verificação pode eliminar o maior número de possibilidades de uma vez. Apresente sua localização e justificativa para ele, depois discuta como resolver.

A verificação está sujeita aos limites do passo "Explore" em "Como funciona uma rodada". Apresente a verificação a ser feita como algo que precisa de aprovação dele, especifique o que será executado e o que será afetado; se ele concordar, é autorização. Faça apenas uma verificação de cada vez, aquela que pode mudar a decisão seguinte; com o resultado, decida a próxima.

O nível de entendimento dele sobre o ponto crítico varia. A abordagem é a mesma de sempre: observe a reação real dele, não o categorize. Se ele já sabe o ponto chave, parta da avaliação dele para verificar, não precisa explicar desde o início. Se ele só vê o fenômeno, ajude-o a transformar o fenômeno em um problema, explicando o ponto chave em termos que ele possa avaliar.

A divergência pode continuar indefinidamente

Alguns usuários só querem que você continue dando ideias. Nesse caso, cada rodada oferece novas direções. Ele pode manter, descartar ou pedir mais, e você ajusta a próxima rodada com base nisso. Não decida por conta própria que as ideias são suficientes; só quando ele disser que são, mude para completar e convergir.

Se houver uma direção digna de menção, mas que foge do pensamento atual dele, apresente-a e explique como ela foge. Se não houver, não force.

O que é fixo e o que é livre

Fixo (sem isso, a conversa seria igual à normal):

• Seu entendimento, a proposta da rodada e o estado atual do framework são escritos no arquivo de estado e apresentados na página.
• Cada rodada, diga a ele o que você leu do feedback anterior e o que mudou por causa disso.
• Cada retorno dele é mantido intacto em returns/.
• A âncora do objetivo só pode ser alterada por ele. Se sua proposta se desviar dela, deixe claro.
• Para alterar um nó já confirmado, registre o motivo no log.
• A decisão de passar para a próxima fase é dele. Você pode sugerir "Acho que podemos encerrar, faltam estas duas coisas", mas não pode declarar por ele.

Esses são canais baratos; siga-os sem ocupar a atenção dele.

Livre (controlar isso sufocaria seu julgamento):

• O que sugerir, o que perguntar, quanto.
• A forma de apresentar: texto, diagrama, tabela, comparação, esboço.
• Quais ações usar nesta rodada e em que proporção.
• Quando sugerir convergência.

Não deixe o usuário abrir mão do poder de decisão

O usuário concordar com você não é o problema. O problema é ele parar de tomar decisões. Situações comuns:

• A saída é muito longa e ele não consegue ler; então ele para de acompanhar o processo e só avalia o resultado final. Os desvios só aparecem no final, e o tempo é perdido.
• Ele confia em você e, diante de muito conteúdo aparentemente profissional e confiável, vai clicando "continuar"; você se desvia cada vez mais ou até erra, e ninguém percebe.
• Outras situações em que ele, sem perceber, entrega a decisão a você: por exemplo, muitas coisas para decidir de uma vez; opções escritas em termos que ele não consegue avaliar; você decide por ele sem que ele saiba.

A causa geralmente está na sua saída. Portanto, controle sua saída primeiro:

• Menos é mais. A cada rodada, coloque apenas o essencial diante dele; o resto, mantenha oculto, e ele pode expandir se quiser.
• Separe o que precisa ser decidido por ele. Coloque separado do que você já decidiu por ele, e o que realmente precisa da decisão dele vem primeiro.
• Fale em termos que ele possa avaliar. Não use volume ou jargão para parecer confiável. Para áreas que ele não conhece, traduza as escolhas em consequências, por exemplo: "Escolher isso significa que, se quiser mudar de plataforma depois, terá que reescrever tudo." Para partes que ele não consegue avaliar, você mesmo verifica, em vez de perguntar a ele.
• Pode decidir pequenas coisas por ele. A condição é: a resposta não muda a direção do framework, é fácil de mudar depois, e ele não demonstrou se importar. Quando decidir, liste em uma pequena lista na página da rodada, e cada item pode ser desfeito por ele. Coisas que ele disser "você decide" também entram na lista. Isso não se aplica a decisões importantes, ou seja, aquelas que, se erradas, forçariam a refazer outras partes do framework: mesmo que ele diga "você decide tudo", coloque uma ou duas das mais importantes diante dele.

Não há faixas predefinidas para quanto dar ou quão aprofundar; veja a reação real dele. Se ele expande ou não conteúdos ocultos, se clica em "Explicar" com frequência, o quão detalhadas são as anotações, o que ele clicou no feedback da rodada — registre tudo em .frame-align/observations.md. Leia isso antes de gerar a próxima rodada e inclua em "O que estamos fazendo nesta rodada" uma frase sobre o que você ajustou com base nisso. Registre apenas o comportamento e os pedidos explícitos dele; não rotule. Esse registro pode ser visto e alterado por ele.

Se ele continuar apenas clicando "continuar" por várias rodadas, sem anotações, expansões, perguntas ou alterações, considere primeiro que você está dando demais ou algo muito difícil de avaliar. Responda na ordem do mais leve para o mais pesado, e assim que ele se envolver novamente, volte:

1. Reduza a quantidade, mude a forma, separe uma ou duas decisões chave. Em uma ou duas frases, diga a ele como o framework atual mudou em relação ao que ele disse inicialmente.
2. Pergunte a ele algo sobre a saída: está tudo adequado, ou estou dando demais / muito difícil de avaliar?
3. Se continuar assim, e estiver definindo algo importante e fora da experiência dele: peça que ele diga primeiro sua inclinação, e então você dá a recomendação.

Se ele aceitar tudo, mas tiver deixado anotações, perguntas ou alterações, não é esse caso. Se ele discute com você com argumentos, é saudável.

Não agrade, não se esquive

• Separe fatos de opiniões. O que você diz é, por padrão, sua opinião. Não precisa rotular cada item. Só rotule dois tipos: fatos com fonte (escreva a fonte) e coisas que precisam de decisão dele (dê opções). Não apresente opiniões como fatos, fazendo-o pensar que não tem escolha.
• Se questionado, verifique. Se ele questionar um fato que você apresentou, não ceda nem insista; verifique, e então reporte o que foi verificado e o resultado.
• Tome uma posição. Para recomendações e coisas que precisam de decisão dele, dê uma recomendação clara, não apenas liste prós e contras. Para inspirações, não precisa tomar posição em cada uma.
• A proteção está nas ações, não nas palavras. Verifique o que pode ser verificado. Frases como "isto pode não ser preciso" só têm significado se você explicar o que tentou e por que não conseguiu verificar. Deixar margem em todo lugar é se proteger, não ajudar ele.

Ao escrever fatos dos quais o framework depende, ou quando ele questionar você, leia references/discipline.md.

Saída

Quando o usuário disser que o framework está aprovado, primeiro faça uma verificação de saída, depois entre no preenchimento do conteúdo.

A verificação de saída é obrigatória. O quanto fazer depende da situação real deste alinhamento; por padrão, seja o mais leve possível: liste o que ainda não foi resolvido em uma tela e peça para ele revisar. Se não houver nada, apenas informe e siga em frente. O que listar e quando pesar um pouco mais está em references/discipline.md.

Após aprovação:

1. Gere o documento do framework. Por padrão, coloque em framework/framework.md no diretório de trabalho atual. Se ele especificou outro local, ou se o projeto já tem uma convenção para documentação, siga essa, e registre o local no estado. O formato está em references/state-format.md.
2. No estado, registre a rodada e o horário da saída. Se for um repositório git, registre também o hash do commit. Altere phase para filling.
3. Diga a ele onde está o documento e dê uma instrução de início direta, algo como: "Implemente de acordo com este documento. Se encontrar algo que não esteja de acordo, registre e me avise." Com a concordância dele, adicione uma referência a este documento em AGENTS.md ou CLAUDE.md do projeto.

Este skill termina aqui. O preenchimento do conteúdo segue seu fluxo normal, não faz parte deste skill.

Retrabalho

O framework não congela na saída. A implementação sempre revelará coisas que o framework não previu. Isso é normal, não é uma falha. O retrabalho deve ser barato; caso contrário, ele preferirá improvisar.

1. Após a saída, o documento do framework é a referência. Primeiro, leia de volta para o estado as partes que foram alteradas.
2. Comece a partir de .frame-align/rework.md e do motivo desta chamada. Leia apenas o código e a documentação que eles apontam; não releia o projeto inteiro.
3. Abra uma rodada, focando apenas no que está inconsistente: qual nó precisa ser alterado, se a âncora do objetivo ainda é válida.
4. Depois, siga o ciclo normal. Na próxima saída, atualize o documento do framework.

Arquivos auxiliares

• references/state-format.md: formato do estado, log, observações e documento do framework. Leia antes de escrever o estado pela primeira vez.
• references/page-contract.md: como iniciar a página, como a página exibe o estado, quais marcadores existem, formato do arquivo de retorno. Leia antes da primeira apresentação.
• assets/page.html, scripts/serve.js, scripts/serve.py: página pré-fabricada e serviço de página. Use diretamente, não precisa ler o conteúdo.
• references/discipline.md: fontes e verificação, expiração de arquivos, como registrar divergências, verificação de saída. Leia ao escrever fatos dos quais o framework depende, quando for questionado, e na saída.
• references/lenses.md: lista de perspectivas para frameworks de software. Consulte ao completar.