gvozdb/semantic-spec-writer-skill

Redator de Especificações Semânticas

Produza arquivos .plan.ctx e .spec.ctx que um agente de implementação possa usar sem carregar esta skill.

Modo

• Novo documento: escreva o artefato semântico final diretamente a partir da solicitação e dos fatos fundamentados do repositório. Não crie um rascunho em prosa primeiro.
• Documento existente: converta-o apenas conforme solicitado, preservando o significado original e os identificadores. O artefato final deve ser menor que a fonte.
• Transferência ou uso repetido: otimize para execução independente por outro agente ou em uma etapa posterior.
• Pacote de execução do repositório: quando o usuário quiser uma transferência de codificação e o código-base estiver disponível, leia references/execution-packets.md. Fundamente uma rota mínima de leitura/edição antes de escrever o pacote.

Não afirme que a conversão economiza tokens totais para uma implementação única. Ela adiciona uma etapa de autoria; sua economia vem de um contexto reutilizável menor e de menos ambiguidade de implementação.

Alvo

Otimize todo o loop de implementação, não apenas a contagem de caracteres:

• preserve cada comportamento, restrição, caso de borda e identificador exato;
• remova narrativa, repetição, metadados decorativos e conselhos genéricos;
• exponha o caminho confiável mais curto do requisito à edição e à verificação;
• prefira linguagem direta em vez de abreviações que exijam interpretação.

Um arquivo menor só é útil quando permanece mais rápido de executar corretamente. Ao converter um documento existente, planeje a estrutura compacta antes de escrever e evite expandir a fonte. Não adicione loops de ferramentas ou reescritas repetidas apenas para perseguir o tamanho do arquivo.

Disciplina de tokens

• Leia cada fonte fornecida uma vez, a menos que um fato ausente exija uma consulta direcionada.
• Inspecione apenas os arquivos necessários para fundamentar escopo, interfaces e verificação.
• Escreva um artefato final. Torne-o mais curto na escrita inicial. Para conversão, execute scripts/check_conversion.py SOURCE OUTPUT a partir do diretório desta skill uma vez. Quando o tokenizador alvo for conhecido e tiktoken estiver disponível, passe --encoding NOME. Se a verificação falhar, remova a redundância uma vez e execute-a mais uma vez; nunca continue um loop de perseguição de tamanho. Não emita um esboço, rascunho, notas de conversão, relatório de tamanho ou explicação, a menos que seja solicitado.
• Não copie fatos do repositório que o agente de implementação pode obter do arquivo alvo exato sem pesquisa. Inclua fatos que impeçam uma edição incorreta ou descoberta extra.
• Prefira caminhos exatos e um comando de verificação executável a conselhos genéricos de implementação.
• Para um pacote de execução, gaste esforço de autoria apenas em fatos que removam descobertas posteriores ou impeçam uma edição incorreta. Não transforme o pacote em um despejo de repositório.
• Forneça aos pacotes de execução o loop limitado a jusante canônico da referência: uma leitura roteada, uma passagem de implementação, uma verificação declarada, então pare em caso de sucesso. A expansão requer uma contradição ou falha concreta.

Formato

• Comece com plan ou spec simples.
• Use .plan.ctx para planos e .spec.ctx para especificações, a menos que o projeto tenha outra convenção.
• Use nomes de blocos locais óbvios. Eles são rótulos, não palavras-chave reservadas da linguagem.
• Inclua apenas blocos que contenham informação. Não emita seções vazias.
• Combine fatos de alvo, escopo e contrato quando blocos separados repetiriam a mesma informação.
• Preserve caminhos de arquivo, símbolos, rotas de API, campos, tabelas, variáveis de ambiente, comandos, status, funções e texto de erro exatamente.
• Preserve a propriedade e o aninhamento dos campos exatamente. Corresponda a notação de campo à linguagem de implementação: para Python JSON/maps use event["payment_id"], não event.payment_id. Nunca invente um wrapper data, payload ou outro que a fonte não defina.
• Trate .ctx como texto simples, não Markdown. Não envolva identificadores comuns em crases, negrito ou outra marcação de apresentação. Use crases apenas para comandos executáveis sob verify.
• Defina um termo local apenas quando ele remover repetição real. Prefira termos descritivos; evite aliases de uma letra e notação inventada.
• Adicione IDs apenas quando outro item os referenciar.
• Use expressões familiares como x=true, x in [a,b] e condicao -> resultado. Não confie em sintaxe oculta.
• Use um comentário curto # apenas quando campos estruturados perderiam nuances críticas.
• Agrupe validações paralelas, campos de saída e erros exatos sob um mapeamento compacto em vez de repetir a mesma estrutura de frase.
• Após a propriedade do campo ser estabelecida, use rótulos curtos e inequívocos em mapas de validação e erro em vez de repetir o caminho completo do proprietário.
• Em um mapa de erros, deixe o bloco carregar a gramática repetida. Prefira campo: condicao | ErrorType "mensagem exata" em vez de repetir invalido proprietario.campo -> ErrorType em cada linha.
• Mantenha uma regra testável independentemente por linha. Um mapeamento compartilhado pode conter casos de campo relacionados quando sua gramática for consistente.
• Use IDs A* apenas uma vez, sob acceptance. Não reutilize IDs de aceitação como IDs de regra ou tarefa.

Fundamentação

Quando um código-base estiver disponível, inspecione-o antes de escrever. Capture o escopo de edição conhecido, interfaces existentes, restrições e comandos de verificação executáveis. Inclua verify apenas para um comando exato ou verificação nomeada existente; não invente cenários de verificação. Não adivinhe nomes de arquivos ou arquitetura.

Decisões desconhecidas pertencem a open_questions. Omita esse bloco quando não houver incógnitas.

Ordem da informação

Coloque a informação na ordem que um agente de implementação precisa. Use apenas as partes relevantes:

1. objetivo ou alvo, incluindo escopo de edição exato quando conhecido;
2. contratos não declarados pelo alvo;
3. regras, invariantes, estados ou fluxos;
4. trabalho ordenado apenas onde as dependências importam;
5. comandos de verificação e aceitação observável;
6. questões não resolvidas.

Escopo exato e verificação geralmente economizam mais trabalho do agente do que a compressão agressiva de prosa.

Regras de compressão

• Declare cada fato uma vez.
• Mescle requisitos duplicados.
• Omita um bloco quando seu conteúdo já for transportado por outra linha.
• Faça a aceitação referenciar IDs de regras, contratos e verificação existentes em vez de reafirmar sua prosa.
• Mantenha a aceitação apenas como referências quando os blocos referenciados já declararem o comportamento observável.
• Mantenha razões apenas quando elas alterarem uma decisão de implementação.
• Substitua verbos vagos como melhorar, suportar, lidar com, otimizar e corrigir por resultados observáveis.
• Mantenha casos de borda raros, mas consequentes. Nunca os descarte para tornar o arquivo mais curto.
• Não codifique requisitos comuns como fórmulas meramente para reduzir palavras.
• Prefira uma fórmula inteira exata derivada da fonte a uma descrição em prosa mais longa quando for mais fácil de executar corretamente.

Exemplos

Especificação de implementação:

spec
alvo: [src/payments.ts,tests/payments.test.ts] :: tornar POST /payments idempotente por Idempotency-Key
manter: esquema de resposta, comportamento de autenticação

regras:
  R1: escopo da chave é user_id
  R2: mesmo user + mesma chave + mesmo corpo -> reproduzir status e corpo originais
  R3: persistir resultado antes de retornar sucesso

erros:
  E1: Idempotency-Key ausente -> 400 idempotency_key_required
  E2: mesma chave + corpo diferente -> 409 idempotency_conflict

verificar:
  V1: `pnpm test tests/payments.test.ts`

aceitacao:
  A1: R1,R2,R3,E1,E2 -> V1

Mapa de validação paralelo:

validacao:
  retries: int>=0 | ValueError "retries must be non-negative"
  timeout: int>0 | ValueError "timeout must be positive"

Plano de implementação:

plan
objetivo: mover armazenamento de sessão da memória para Redis sem alterar o comportamento da API

fatos:
  armazenamento atual: src/session/memory.ts
  testes de contrato: tests/session.contract.test.ts

tarefas:
  T1: adicionar adaptador Redis por trás da interface SessionStore existente
  T2: executar testes de contrato contra adaptadores de memória e Redis
  T3: trocar a raiz de composição após T2 passar

verificar:
  V1: `pnpm test tests/session.contract.test.ts`

Portão de qualidade

Antes de finalizar, verifique:

• um novo agente de implementação pode agir sem esta skill ou contexto não declarado;
• cada linha altera escopo, comportamento, ordem de implementação ou verificação;
• nenhum requisito é duplicado ou substituído por uma abreviação não definida;
• arquivos, interfaces e comandos conhecidos são exatos;
• a aceitação é observável e rastreável até o contrato declarado;
• cada campo ainda tem o mesmo proprietário e aninhamento que na fonte;
• o resultado é mais curto removendo redundância, não obscurecendo o significado.

Produza o documento semântico primeiro. Adicione notas separadas apenas para decisões não resolvidas que impeçam materialmente a implementação.