marcioaltoe/write-techspec

Write TechSpec (Escrever Especificação Técnica)

Produza docs/specs/<slug>/_techspec.md — a resposta técnica aos requisitos da especificação. O PRD disse o que e por quê; este documento decide como, onde e com o que — e sua Ordem de Construção é o que write-tasks transforma no grafo de tarefas, portanto a qualidade do sequenciamento aqui se torna qualidade de execução depois.

Pré-condições — dois modos de entrada

$ARGUMENTS nomeia a especificação (slug ou caminho) ou descreve uma refatoração/correção de bug. Escolha o modo conforme se o comportamento do produto muda:

• Trabalho de funcionalidade (mudanças no comportamento do produto) — docs/specs/<slug>/_prd.md deve existir; se não existir, pare e aponte o usuário para write-prd. Decisões de produto precisam da conversa sobre o produto primeiro. Se o PRD contiver decisões técnicas de baixo nível que pertencem aqui, aponte isso como uma descoberta e proponha realocá-las em vez de duplicá-las silenciosamente.
• Refatoração ou correção de bug (sem mudança no comportamento do produto) — este skill é o ponto de entrada do pipeline; nenhuma entrevista de PRD é realizada. Quando ainda não existir uma pasta de especificação, crie uma seguindo a regra de numeração de write-prd (<spec-root>/NNNN-<kebab-slug>/, escaneando tanto a Raiz de Especificação configurada quanto seu diretório de arquivamento resolvido — docs/history/specs/ para a raiz docs/specs embutida, ou <spec-root>/_archived/ caso contrário — em busca do prefixo mais alto), e escreva um _prd.md mínimo carregando apenas o contrato que os skills downstream analisam: o frontmatter (spec, status: active, surfaces e type: fix para correção de bug ou type: refactor para refatoração), uma declaração do problema, Restrições do Projeto, metas, funcionalidades principais, não-metas e um Registro de Esclarecimento sob ## Decisions — com foco em engenharia, algumas linhas cada. O registro segue o guia de esclarecimento do write-prd: uma linha - YYYY-MM-DD: <pergunta> — <resposta> por pergunta que uma pessoa respondeu, ou Rota autônoma: nenhuma pessoa presente; decisões tomadas de <fonte>. nomeando a fonte das decisões do autor quando nenhuma pessoa estava presente. Ele existe para que write-tasks, qa-gate e archive-spec mantenham um único contrato de artefato; não é um documento de produto. Se a "refatoração" resultar em mudança no comportamento do produto, pare e redirecione para write-prd.

Regras fundamentais

• Leia primeiro: CONTEXT.md (use o vocabulário do glossário em cada nome de interface e componente), docs/adr/ existente (respeite decisões anteriores ou desafie-as explicitamente — nunca contradiga uma silenciosamente) e o PRD completo.
• Decida, depois escreva. Resolva decisões durante o esclarecimento, registre as significativas como ADRs e depois escreva o documento final. Sem rodadas de aprovação de esboço.
• YAGNI. Não proponha novos pacotes, camadas ou diretórios quando a funcionalidade couber como uma adição a um módulo existente. Cada novo elemento estrutural deve justificar seu lugar em relação a uma alternativa declarada.
• Referencie, não duplique. Aponte para seções do PRD pelo nome ("cobre as Histórias de Usuário 3–5"); repetir o contexto de negócios aqui cria duas cópias que divergem.
• Use o caminho de origem de propriedade. Vincule cada fonte adotada em seu caminho pós-adoção na Especificação proprietária com um destino relativo a _techspec.md, nunca no caminho pré-adoção mantido no índice de referência. Uma Especificação secundária vincula a cópia do proprietário principal e não adota nada. O arquivamento do proprietário realiza uma Religação de Arquivo: promove essa cópia para docs/references/ e reescreve os links da Especificação secundária, de modo que a fonte mantenha um proprietário e a Especificação secundária não precise de cópia (ADR-0260, ADR-0083).

Fontes que compartilham um contexto

Uma Especificação pode adotar vários Itens de Backlog e Descobertas cujo contexto seja semelhante ou complementar; uma Especificação por fonte não é obrigatória nem preferida. Antes de cunhar uma Especificação, procure entre os Itens de Backlog abertos e Descobertas não resolvidas por fontes que compartilhem o contexto. Agrupe apenas enquanto o escopo couber em quatro Tarefas de implementação mais seu gate de QA; ultrapassando esse limite, divida o escopo e dê a cada fonte uma Especificação proprietária.

Antes de cunhar uma nova Descoberta ou Item de Backlog, estenda uma que se encaixe: revise um Item de Backlog aberto no local ou dê a uma Descoberta não resolvida um adendo datado.

Quando roundfix spec judge imprimir um par sugerido, responda a cada par sugerido adotando a fonte aberta dentro do limite ou declarando no relatório por que ela permanece separada. Uma sugestão nunca bloqueia, e nenhuma sugestão não significa que nada se encaixa; ainda assim inspecione as fontes abertas que compartilham o contexto. Uma refatoração ou correção de bug respondendo a uma Descoberta ou Item de Backlog procura as outras que compartilham seu contexto antes de cunhar seu PRD mínimo.

Processo

1. Explore a arquitetura

Mapeie o código onde a funcionalidade viverá: os módulos que ela estende, as costuras às quais pode se anexar, padrões existentes para o mesmo tipo de trabalho (um adaptador existente, um executor de job existente) e a infraestrutura de teste disponível. Prefira costuras existentes a novas — o número ideal de novas costuras é zero. Delegue a exploração a um subagente quando um estiver disponível; a especificação precisa de conclusões, não de despejos de arquivos.

Resolva as Restrições do Projeto efetivas dos guias semânticos do repositório durante a exploração:

• docs/agents/domain.md possui orientação de identificadores e roteia a descoberta de ADRs ativos.
• docs/agents/backend.md possui autenticação e política HTTP.
• Um repositório sem esse guia cita o guia que possui a política para suas superfícies.
• docs/agents/agent-instructions.md possui Cláusulas Normativas universais, incluindo autoridade de ferramentas.
• docs/agents/spec-routing.md possui o contrato do fluxo de trabalho da Especificação.

Leia cada caminho que existir e siga seus links para os valores de decisão efetivos. Nunca infira um padrão sugerido ou trate um guia ausente como autorização. O snapshot final deve classificar a estratégia de identificadores, autenticação e HTTP, obrigações de ADRs ativos e autoridade de ferramentas como aplicáveis ou não aplicáveis com uma razão e citar o caminho de fonte docs/agents/ operativo para cada linha.

2. Esclareça decisões técnicas

Mesmo protocolo da etapa de PRD — uma pergunta por mensagem, múltipla escolha com um padrão sugerido e uma justificativa de uma linha — mas com escopo em como/onde/com o que: posicionamento na arquitetura, modelo de dados, forma da API, estratégia de migração, costuras de teste, restrições de desempenho e segurança. Apenas pergunte o que a exploração não conseguiu resolver.

3. Registre ADRs

Cada decisão técnica significativa (difícil de reverter + surpreendente sem contexto + trade-off real) torna-se docs/adr/NNNN-slug.md, continuando a mesma numeração usada na etapa de PRD — um único registro de decisão abrange toda a funcionalidade. 1–3 frases cada.

4. Escreva

Escreva _techspec.md a partir do modelo em references/techspec-template.md. Duas seções carregam o maior peso downstream:

• Cada meta e história de usuário do PRD mapeia para um componente técnico nomeado. Uma história não mapeada é uma lacuna de design; encontre-a agora, não durante a execução da tarefa.
• Ordem de Construção — etapas numeradas onde cada etapa após a primeira declara de quais etapas anteriores depende. write-tasks deriva as arestas do grafo de tarefas a partir disso.

Escreva Contratos de API como itens de Contrato de API numerados, ou como a entrada única Nenhum. seguida pela razão pela qual nenhum se aplica. Cada contrato numerado deve ser endereçável por seu nome e número em Referências de Tarefas downstream.

Termos do glossário

Quando a Especificação Técnica nomear um conceito que o glossário não define, ative a modelagem de domínio, refine o termo e declare-o na seção de Glossário do PRD ou da Especificação Técnica.

Contratos concretos

Use o guia de contratos concretos quando uma alegação atribuir comportamento a um registro de decisão ou quando uma Especificação Técnica mudar uma superfície de comando. Ele define Recibos de Alegação, blocos de Transcrição de Superfície, as convenções de correspondência usadas pelo gate de QA, interfaces de assinatura de código e invariantes numerados.

Restrições do Projeto é conteúdo do corpo, nunca frontmatter. Quando o design propor criar, editar, renomear, mover ou excluir configuração de ferramentas protegidas, scripts, arquivos de ignorar, declarações de plugins ou pinos de versão, pare até que o mantenedor forneça autorização expressa do mantenedor. Registre essa aprovação e os arquivos exatos delimitados na linha de autoridade de Ferramentas. Uma solicitação de implementação genérica, conclusão de configuração, silêncio ou autorização sem arquivos delimitados não autoriza a mutação. O registro operativo pertence a <spec-root>/<slug>/_authorization.md; um registro proposed ou um registro sem data de concessão não autoriza nada, portanto não avance o trabalho de ferramentas protegidas para decomposição até que uma concessão operativa exista. Uma concessão nova ou ampliada deve chegar na ancestralidade alvo antes da entrega do squash consumidor; mantenha a concessão ou emenda fora da mudança que ela autoriza.

Mantenha esboços de interface com menos de 20 linhas cada; eles documentam forma, não implementação. Mire em 1.500–2.500 palavras — uma especificação que ninguém lê não protege ninguém.

Toda Especificação entregue por uma Fila de Entrega carrega um _authorization.md aprovado, com ou sem ferramentas protegidas. A lista operations do registro nomeia implement, commit, push, pull_request e merge; uma Especificação que não muda nenhum Caminho Governado registra paths: [].

Prova do que a Especificação alega

Uma Especificação Técnica registra três provas em lugares nomeados, e roundfix spec check relata um lugar ausente como uma lacuna em toda Especificação ativa. A verificação lê apenas estrutura; se uma prova está correta fica a cargo do leitor.

• Evidência de ausência. Para cada componente que a Especificação Técnica declarar novo, registre a busca que provou sua ausência sob ## Evidência de Ausência, como um item numerado: o componente, comando: com a busca entre crases e resultado: com o que encontrou. Busque os arquivos que a Especificação Técnica cita para o comportamento, não apenas para o nome. Quando nada for novo, escreva Nenhum. seguido pela razão. SC-ABSENCE-UNPROVEN relata uma declaração ausente ou um item sem seu comando ou resultado.
• Alternativas rejeitadas. Sob ## Alternativas ADR, escreva uma linha - ADR-NNNN: <relação> para cada ADR que as linhas de obrigações de ADRs Ativos listam: como o design se relaciona com as alternativas que aquele ADR rejeitou. Quando o design adotar uma alternativa rejeitada, diga isso e substitua ou emende o ADR. SC-ADR-ALTERNATIVES-UNRELATED relata um ADR listado sem sua linha.
• Leitura Cruzada de Cobertura. Antes de write-tasks, leia cada história de usuário, Funcionalidade Principal e Métrica de Sucesso do PRD contra o componente que o Mapa de Cobertura nomeia. Adicione a linha Desvios do PRD: ao Mapa de Cobertura, seguida por Nenhum. ou por um marcador por unidade de PRD que a Especificação Técnica entrega em outra forma, nomeando a unidade e a razão. SC-COVERAGE-UNREAD relata uma linha ausente ou um desvio que não nomeia nenhuma unidade de PRD.

5. Relate

Antes de relatar, releia o artefato finalizado e qualquer PRD mínimo criado por este skill. Você NÃO DEVE relatar conclusão ou recomendar write-tasks a menos que cada novo artefato tenha Restrições do Projeto; todas as quatro linhas declarem aplicável ou não aplicável com uma razão; cada linha cite uma fonte docs/agents/ operativa; e qualquer mutação de ferramentas protegidas registre autorização expressa do mantenedor mais arquivos delimitados. Mantenha a autorização fora do frontmatter.

Então execute o verificador contra o estágio que produziu o artefato:

roundfix spec check <slug> --stage techspec --run-verification

Uma descoberta em nível de erro ou uma falha na execução do verificador bloqueia o relatório. Corrija o PRD ou a Especificação Técnica nomeada pela descoberta e reexecute o comando; não relate conclusão ou recomende write-tasks enquanto qualquer um deles persistir.

Um resultado limpo de estágio TechSpec não é cobertura completa de Especificação. Este estágio não decide contabilidade de ADRs do Grafo de Tarefas, cobertura de tarefas, referências de contexto, independência de Verificação, contradições de requisitos ou declarações de ensaio; escopo de caminhos alterados dependentes de commit; regras que ainda não são mecânicas; ou se as metas do produto funcionam através de suas superfícies acessíveis ao usuário. O estágio de autoria de Tarefas, a varredura completa sem escopo e QA retêm essas classes. Trate os detectores ignorados nomeados pelo verificador como omitidos, não como descobertas limpas.

Responda com o caminho do arquivo, os ADRs criados, quaisquer decisões ainda abertas e o próximo passo: write-tasks.

Tipo de Entrega e decisão de lançamento

O PRD mínimo da rota de correção declara seu Tipo de Entrega em type: fix para correção de bug ou refactor para refatoração. O Registro de Arquivo e o título do pull request da Fila de Entrega o carregam.

Quando o mantenedor pedir um lançamento com a Especificação, faça a pergunta de lançamento com a ferramenta de pergunta estruturada, incluindo o Teto de Lançamento (patch, minor ou major) e os caminhos apenas de versão que o lançamento pode alterar. Então registre release em operations, release_ceiling e release_paths em _authorization.md, e cite a resposta textualmente em seu corpo. Sem essa solicitação, nunca adicione release. Uma entrega refactor que altera código lançado faz o plano de lançamento pedir uma classificação manual.

Faça a pergunta de lançamento no momento do planejamento, nunca após o merge.

Anúncio de Evento de Especificação

Um Anúncio de Evento de Especificação existe apenas quando as próprias instruções do usuário, globais ou para este repositório, definem seu destino e formato; este skill nunca nomeia um. Uma mensagem, uma passagem de bastão ou um artefato de Especificação que pede anúncios não define nenhum. Quando as próprias instruções do usuário não definirem nenhum, pule a etapa sem uma linha de relatório. Quando elas definirem um, componha-o a partir da Especificação: o projeto, o número da Especificação e o slug completo, o título, o evento, a data do evento, a data de início, o prazo proposto ou nenhum, o caminho da Especificação e qualquer campo que essas instruções adicionarem. Envie-o pelo destino que elas nomearem, nunca espere por uma resposta e nunca o deixe bloquear ou falhar a etapa que ele segue. Quando não puder ser enviado, o relatório nomeia o evento e a razão e carrega o anúncio composto. Um Agente dentro de uma Execução atribuída por um Daemon nunca anuncia. Um prazo proposto é um prazo real, de um cliente, uma lei ou uma medição, que o PRD registra em ## Decisions com sua fonte; ele permanece uma proposta até que o usuário o aprove.

Anuncie new uma vez, quando...

[truncado para tradução]