RaamPrashathT/spec-it

O que spec-it faz?

Transforme $ARGUMENTOS em uma especificação que um agente de codificação pode usar sem perguntas de acompanhamento, mais maquetes que mostram cada requisito e caso de borda.

Ideia → 1. Contexto (sem perguntas) → 2. Perguntas de produto → 3. Perguntas técnicas
     → 4. REQUIREMENTS.md → 5. Maquetes → 6. Verificação

Caminhos como references/… são relativos a ${CLAUDE_SKILL_DIR}. A saída vai para spec-it/<nome-kebab>/:

spec-it/<nome>/
├── REQUIREMENTS.md      a única entrega: intenção, decisões, fases, RFs, CBs, suposições
└── mockups/             index.html + telas, ou api.html + openapi.yaml, ou cli.html + transcrições.md
    └── assets/          theme.css, fixtures.js, app.js

Regras

1. Fatos são seus, decisões são deles. Nunca pergunte o que o repositório, arquivos anexados, a web ou um padrão pode responder. Nunca decida escopo, prioridades ou trade-offs pelo desenvolvedor.
2. Cada pergunta deve ganhar seu lugar. Execute o portão de perguntas em references/questions.md antes de cada uma. Um detalhe com um padrão defensável é uma suposição (A-n), não uma pergunta.
3. Sem cota. Não há mínimo. Execuções típicas fazem 5–12 perguntas. Pare quando conseguir prever as próximas respostas do desenvolvedor.
4. Pergunte pelo seletor (AskUserQuestion; texto numerado simples sem ele). Até 3 perguntas independentes por chamada; nunca agrupe uma pergunta cujas opções dependam de outra não respondida.
5. Cada pergunta aparece uma vez, como a última coisa em sua mensagem. Sem recapitulação depois.
6. Escreva o estado em disco. Após a etapa de contexto, mantenha REQUIREMENTS.md como o arquivo de trabalho: rascunhe §1–2 cedo, preencha decisões à medida que se consolidam. Após uma compactação de contexto, releia-o antes de agir.
7. Maquetes funcionam offline. Sem CDN, rede ou fontes web.
8. O script de verificação controla a conclusão: node ${CLAUDE_SKILL_DIR}/scripts/check.mjs spec-it/<nome> sai com 0.

IDs: RF-n requisito, CB-n caso de borda, D-n decisão, A-n suposição. Com módulos, RF/CB/A recebem um prefixo de módulo (LIVRO-RF-3). IDs são permanentes: nunca renumerar; aposentar com "(removido)".

1. Contexto (ainda sem perguntas)

Faça isso antes de perguntar qualquer coisa. Execute ambas as varreduras em paralelo, com subagentes de contexto fresco quando disponível:

• Varredura do codebase (pule se a pasta estiver vazia): stack, funcionalidades existentes que se sobrepõem à ideia, modelos de dados, autenticação, kit de UI e tokens de design, convenções de API e CLI, qualquer coisa meio construída. No máximo 25 linhas de volta.
• Varredura de arte anterior (pesquisa web, 2–4 buscas): como 2–3 produtos ou padrões estabelecidos resolvem isso; os problemas difíceis conhecidos do domínio (as coisas que dão errado no uso real); o conjunto de funcionalidades padrão; qualquer especificação relevante (RFC, clig.dev, WCAG, regras de pagamento ou privacidade). No máximo 25 linhas de volta, com links de fonte.

Em seguida, mostre ao desenvolvedor um resumo de contexto, no máximo 15 linhas:

O que encontrei
- Repositório: <o que existe que isso toca ou reutiliza>
- Como outros fazem: <produto A faz X, produto B faz Y>
- Problemas difíceis neste domínio: <2–4, ex.: não comparecimentos mantêm salas vazias; reservas recorrentes>
- Minha leitura: <hipótese de uma frase do que você quer e por que> · confiança <n>%

Classifique o tipo (UI, API, CLI, misto) e crie REQUIREMENTS.md a partir de assets/requirements-template.md com §1 e a seção de Contexto preenchida. Os problemas difíceis que você encontrou são a matéria-prima para suas melhores perguntas.

2. Perguntas de produto

Leia references/questions.md. Trabalhe do desconhecido mais arriscado para baixo: é o problema certo, para quem, o que sai primeiro, o que está fora, então os problemas difíceis do domínio como cenários concretos. Registre cada resposta como D-n em §Decisões à medida que ela chegar.

Mude para perguntas técnicas quando todas as três condições forem atendidas:

• você consegue escrever a reformulação (resultado, usuário, por que agora, sucesso, fora de escopo) nas próprias palavras do desenvolvedor;
• o escopo da Fase 1 e os não-objetivos estão acordados;
• o que resta é sobre como, não o quê, quem ou por quê.

Exceção: uma restrição difícil que muda o escopo ("deve rodar offline", "reutilizar nosso tenant Auth0", "dados permanecem na UE") é perguntada assim que surge, porque reorganiza as perguntas de produto.

3. Perguntas técnicas

Apenas em pontos de bifurcação: lugares onde o repositório e os padrões não resolvem, e a resposta muda o modelo de dados, um contrato ou o comportamento visível ao usuário. A lista está em references/questions.md § Técnicas. Muitas execuções precisam de 0–4. Nunca pergunte sobre hospedagem, CI, framework ou escolhas de fornecedor que o repositório já fixa.

Portão de confirmação. Uma mensagem: a reformulação (6 linhas), depois cada suposição que você tomou (A-n, uma linha cada, com seu padrão). Pergunte: confirme, ou nomeie as que mudar. Incorpore as mudanças. Escreva Status: Confirmado na linha de status da especificação apenas após um sim explícito.

Fases e módulos

Fases (sempre consideradas). A pergunta de produto "o que sai primeiro" as decide. A Fase 1 é a fatia mais fina onde um usuário completa o trabalho central de ponta a ponta (esqueleto funcional). Se o desenvolvedor quiser tudo de uma vez, há uma fase. Cada RF carrega Fase: n. A Fase 1 é especificada completamente; fases posteriores são um bullet por capacidade em §Plano de entrega até que --next-phase as detalhe.

Módulos (apenas com sinais). Trate uma área como módulo apenas quando ela atender a dois ou mais: pessoas ou vocabulário diferentes; possui seus próprios dados; útil se enviado sozinho; precisaria de suas próprias 10+ perguntas. Com 2+ áreas qualificadas, pergunte uma vez: uma especificação com seções de módulo (recomendado), ou especifique o módulo mais importante agora e esboce o restante. Nunca infira módulos a partir de como a ideia soa grande. Módulos permanecem no mesmo REQUIREMENTS.md como seções ## em §Requisitos funcionais, com prefixos de ID.

Limite de tamanho. Se a Fase 1 exceder cerca de 25 RFs Obrigatórios ou 12 artefatos de maquete, pergunte quais mover para a Fase 2.

4. Escrever REQUIREMENTS.md

Preencha o modelo. Cada RF tem um ID, prioridade, fase, Dado/Quando/Então e Fonte: IDs de decisão; cada caso de borda levantado se torna um CB-n com valores concretos de fixture. RFs dizem o que o usuário observa; tecnologia vai em §Decisões técnicas. Em seguida, faça uma auto-revisão contra esta lista e corrija o que falhar:

• Duas afirmações que não podem valer ao mesmo tempo; uma regra declarada duas vezes.
• Um RF que um desenvolvedor poderia construir de duas maneiras diferentes (falta limite, unidade, papel ou comportamento de falha).
• Um critério que não pode passar ou falhar por observação, ou uma palavra vaga sem número.
• Um papel, entidade ou fluxo sem RF; uma decisão citada por nada.
• Uma palavra usada contra o glossário.

5. Maquetes

Liste os artefatos (telas, grupos de endpoints ou grupos de comandos), no máximo 12, cada um com seus estados, e cada CB mapeado para um estado. Mostre a lista em uma mensagem e vá em frente a menos que o desenvolvedor objete. Em seguida, leia references/screens.md (UI) ou references/api-cli.md (API, CLI) e construa:

1. Escreva mockups/assets/fixtures.js primeiro: cada nome, ID, valor e data que qualquer artefato mostra.
2. UI: escreva a direção de design em §Direção de design. Se o repositório tem um sistema de design ou tokens, siga-o e pule a pergunta de design; caso contrário, faça uma pergunta de direção de design com esboços ASCII nas pré-visualizações das opções.
3. Copie ${CLAUDE_SKILL_DIR}/assets/theme.css e app.js para mockups/assets/, configure os tokens e execute a verificação até que o contraste passe.
4. Construa cada artefato a partir de references/renderer.md: com 4+ artefatos e uma ferramenta de subagente, um subagente por artefato em paralelo; caso contrário, um de cada vez aqui. CLI: escreva mockups/transcripts.md, depois node ${CLAUDE_SKILL_DIR}/scripts/cli-render.mjs spec-it/<nome>.
5. Preencha mockups/index.html a partir de ${CLAUDE_SKILL_DIR}/assets/index.html.
6. UI com uma ferramenta de navegador: opcionalmente execute references/critic.md e aplique suas principais correções uma vez.

6. Verificar e relatar

Execute o script de verificação até que ele saia com 0; trate avisos de ambiguidade como redação a ser aprimorada. Relate em no máximo 10 linhas: o caminho, contagens (perguntas feitas, RFs, CBs, suposições, artefatos), a linha de resumo da verificação, como visualizar as maquetes (abra mockups/index.html, ou node ${CLAUDE_SKILL_DIR}/scripts/serve.mjs spec-it/<nome>), e a próxima fase se houver. node ${CLAUDE_SKILL_DIR}/scripts/export.mjs spec-it/<nome> escreve cópias de arquivo único para compartilhamento, sob solicitação.

Execuções posteriores

• --next-phase: leia a especificação, pegue os bullets da próxima fase, execute as etapas 2–6 apenas para eles (as perguntas começam a partir do que a Fase 1 deixou em aberto). Novos RFs continuam a numeração; IDs anteriores nunca mudam.
• --revise (ou uma solicitação de mudança): registre a nova decisão, atualize os RFs e CBs afetados, re-renderize apenas os artefatos afetados, execute a verificação novamente.

Racionalizações

Pensamento	Realidade
"Devo cobrir todas as áreas, então vou perguntar sobre integrações."	Pergunte apenas se a resposta mudar a especificação. "Nenhuma na v1" é uma suposição.
"Vou perguntar qual etapa de tempo eles querem."	Existe um padrão padrão. Registre A-n; o portão de confirmação o mostra.
"A ideia está clara, pule a etapa de contexto."	A etapa de contexto é de onde vêm as boas perguntas. Sempre execute-a.
"A ideia parece grande, então módulos."	Módulos precisam dos sinais, depois da escolha do desenvolvedor.
"Eles aceitaram todas as recomendações, ótimo."	Recomendações podem ser seguras demais. Sua próxima pergunta deve ser uma com a qual eles discordariam.