/aor-req — Redação de Requisitos
Redige UN, PR e SR seguindo os padrões EARS-12, atributos de qualidade INCOSE C1-C9 e sintaxe de referência cruzada canônica. A saída é em markdown.
Nota sobre habilidades vs agentes. O pacote AOR contém habilidades em
.claude/skills/aor-*/SKILL.md(invocáveis diretamente, como esta) e agentes SME em.claude/agents/aor-sme-*.md(prompts de sistema de subagente gerados apenas poraor-review/aor-review-adhoc). NÃO invoque um agente como uma habilidade — isso falhará com "skill not found".
Disciplina operacional
Aplique em toda a execução. Declare cada uma na inicialização para que o usuário a veja.
- Modo (declarado na inicialização): pergunte se esta é uma sessão exploratória (requisito único, conversacional, sem arquivos) ou uma sessão documento (especificação completa de requisitos, arquivos escritos). O padrão é exploratório se o escopo chegar como texto inline sem um caminho de arquivo, documento caso contrário. O modo controla se as Etapas 5–7 escrevem em disco.
- Reconhecimento de invocação: a primeira resposta da habilidade declara
"Executando como
aor-reqno modo . Arquivos escritos em <caminho de saída> a menos que você solicite o contrário." Elimina a ambiguidade "a habilidade realmente foi executada?". - Disciplina de perguntas e respostas: faça uma pergunta esclarecedora de cada vez. Aguarde a
resposta do usuário antes de fazer a próxima. Não empilhe perguntas.
Uma única chamada
AskUserQuestionapresentando uma decisão com múltiplas alternativas (por exemplo, um menu de múltipla escolha) é uma pergunta; apresentar duas decisões não relacionadas em uma única chamada é empilhar. - Divulgação de falha: se alguma etapa prescrita não puder ser concluída (escrita de arquivo bloqueada, invocação de subagente falhou, arquivo de referência indisponível, conclusão parcial, tempo limite, permissão negada), declare no chat. Após a divulgação, pare e pergunte se deve tentar novamente, retornar à emulação manual divulgada ou abortar — não continue silenciosamente. Uma repetição é permitida para falhas claramente transitórias (por exemplo, tempo limite de rede) antes da divulgação obrigatória.
Fluxo de trabalho
Etapa 1: Estabelecer escopo
Se o usuário passou texto de escopo ou um caminho de arquivo, use-o. Caso contrário, pergunte via AskUserQuestion: "Quais funcionalidades ou alterações devem ser especificadas?"
Distinguindo texto de escopo de um caminho de arquivo (REQ-B): trate a entrada
como um caminho se qualquer um de (a) contiver / ou \, (b) terminar com .md /
.txt / .xlsx / .csv / .docx, ou (c) for resolvido para um arquivo existente
no disco via Read(). Caso contrário, trate como texto de escopo — incluindo
descrições de múltiplas palavras como "sistema de agendamento de consultas de pacientes".
Desempate: se apenas a regra (c) corresponder (sem / ou \, sem extensão
reconhecida, mas Read() resolve) E a entrada for uma única palavra, confirme
com o usuário antes de tratar como caminho: "Vejo que um arquivo chamado
<entrada> existe. Você quis dizer esse arquivo, ou é uma descrição de escopo?"
Para entradas originadas do Excel, espere que o LLM host tenha transcrito as linhas em um buffer de markdown funcional antes que esta habilidade seja executada (o pacote não analisa Excel diretamente).
Etapa 1a: Classificar o nível
Se modo exploratório, pergunte:
"Isso é uma Necessidade do Usuário (UN), Requisito de Produto (PR) ou Requisito de Software (SR)?"
Pule etapas não utilizadas assim que o nível for conhecido: a revisão UN precisa da Etapa 2; a revisão PR precisa da Etapa 3 + Portão de Eco; a revisão SR precisa das Etapas 4–6.
Entrada multinível no modo exploratório: se o usuário fornecer um conjunto UN+PR+SR (ou qualquer combinação de vários níveis) em vez de selecionar um, trate como uma revisão multinível — percorra as Etapas 2–4 para os níveis fornecidos em ordem, mas mantenha a disciplina de escrita de arquivo exploratória (sem gravações automáticas em disco; apresente descobertas inline).
Se modo documento, o padrão é percorrer todos os três níveis (UN → PR → SR) nas Etapas 2–4, a menos que o usuário especifique o contrário.
Etapa 2: Escrever Necessidades do Usuário (UN-NNN)
Para cada necessidade distinta de parte interessada, escreva uma UN. Regras:
- Agnóstico em tecnologia, expresso pela parte interessada
- Narrativa simples (NÃO sintaxe EARS)
- Inclua declaração do problema (2-3 frases) + declaração da necessidade
- Marque uma persona via
traces_to::UN->Persona [<persona-id>] - Prioridade: Crítica | Alta | Média | Baixa
Veja templates.md para o formato.
Etapa 3: Escrever Requisitos de Produto (PR-NNN)
Para cada UN, derive PRs:
- Agnóstico em tecnologia, mensurável, objetivo
- Sintaxe EARS (veja
ears-guide.mdpara os 12 padrões) - Cada PR rastreia para trás:
derived_from::PR->UN [UN-NNN] - Cada PR rastreia para frente:
traces_to::PR->SR [SR-NNN] - Todo PR de caminho feliz deve ter pelo menos um companheiro Se/Então (Indesejado) PR
- A mesma regra de companheiro Se/Então se aplica no nível SR na Etapa 4 — todo SR de caminho feliz deve ter um companheiro SR Se/Então especificando a recuperação em nível de implementação
- Todo PR EARS-N (negativo/
shall not) deve ter pelo menos um companheiro PR positivo (Ubíquo, Orientado a Eventos ou Orientado a Estado) especificando o comportamento correto esperado; a mesma regra se aplica no nível SR
"Caminho feliz" definido (REQ-E): um PR é de caminho feliz se usar um dos
padrões EARS positivos — Ubíquo, Orientado a Eventos, Orientado a Estado,
Opcional, Complexo, EARS-E, EARS-T, EARS-P. Excluídos: Comportamento Indesejado,
EARS-N (negativo/shall not), EARS-F (declarativo de modo de falha).
Execute a Decomposição Adversarial de Erros para cada UN:
- Como ele falha silenciosamente?
- Como ele falha ruidosamente?
- Como ele falha sob carga?
- Como ele falha sob malícia?
- Como ele falha ao longo do tempo?
Cada modo de falha se torna um PR Se/Então EARS (marque com [ADV] no
cabeçalho; o identificador permanece canônico, por exemplo, PR-007 [ADV]) ou uma nota para um
registro de risco separado.
Exemplo trabalhado. UN: "preservar todo arquivo enviado". Modo de falha: "falha silenciosamente quando o espaço livre em disco está esgotado". PR resultante:
### PR-007 [ADV]: Rejeitar upload quando a pressão do disco estiver alta
Se o espaço livre em disco cair abaixo de 5%, então o sistema deve rejeitar novos uploads
com HTTP 507 Armazenamento Insuficiente e retornar um cabeçalho Retry-After.
derived_from::PR->UN [UN-001]
traces_to::PR->SR [SR-014]
Observe que o modo de falha é concreto e quantificado (5%, HTTP 507, Retry-After) — isso é o que torna o PR verificável (C7).
Etapa 4: Escrever Requisitos de Software (SR-NNN)
Para cada PR, derive SRs:
- Específico da implementação: nomeie serviços, APIs, bancos de dados, códigos de erro
- Sintaxe EARS com nomes de componentes específicos
- Cada SR rastreia para trás:
derived_from::SR->PR [PR-NNN] - Cada SR rastreia para frente:
traces_to::SR->TC [TC-NNN] - Use granularidade de cláusula (
SR-NNN.c1,.c2) para consolidar comportamentos relacionados sob um único ID de SR - Todo SR de caminho feliz deve ter pelo menos um companheiro SR Se/Então (Indesejado) (veja a Etapa 3 para a definição de "caminho feliz")
- Todo SR EARS-N deve ter pelo menos um companheiro SR positivo
Etapa 5: Tabelas de Especificação de Campos
Para funcionalidades com entrada/exibição de dados, adicione tabelas de especificação de campos na seção SR:
| ID do Campo | Nome | Rótulo | Tipo | Mín | Máx | Unidade | Padrão | Obrigatório | Exposição na UI | Regra de Validação | Mensagem de Erro | SR Pai |
|---|
Valores de Exposição na UI: editável | somente-exibição | oculto.
Etapa 6: Portão de Eco
Para cada cláusula SR, escreva uma asserção testável de uma linha:
VERIFICAR: [SR-NNN.c1] — [reformulação do requisito como uma asserção testável]
Se você não puder escrever a asserção, o requisito é intestável — reescreva-o.
Etapa 7: Verificação de completude
Execute a lista de verificação em completeness.md antes de declarar a redação concluída.
Manipulação de grandes entradas
Quando a entrada exceder ~200 itens de origem (por exemplo, uma grande colagem do Excel):
- Divida em lotes de 50 linhas.
- Para cada lote: a. Leia o lote. b. Transcreva para UN/PR/SR em markdown de acordo com as etapas acima. c. Anexe ao arquivo de trabalho (não sobrescreva). d. Relate o progresso: "Lote de completo; requisitos redigidos."
- Após todos os lotes, execute a verificação de completude no arquivo completo.
Se um lote contiver entrada ambígua, pause e peça esclarecimento antes de continuar — não pule linhas silenciosamente.
Caminhos de saída
Padrão: ./requirements/SPECIFICATION.md para o UN/PR/SR consolidado.
O usuário pode substituir.
Ao atualizar um arquivo existente, preserve os IDs existentes — anexe novos com o próximo número sequencial.
Sintaxe de referência cruzada (folha de dicas)
relation_type::SOURCE->TARGET [ID-list]
| Tipo | Direção | Uso |
|---|---|---|
traces_to | para frente | UN→PR, PR→SR, SR→TC, UN→Persona |
derived_from | para trás | PR→UN, SR→PR, TC→SR |
validates | verificação | TC→SR |
mitigates | controle de risco | SR→RISK |
conflicts_with | contradição | any→any |
Formato do identificador
Regex: ^(UN|PR|SR|TC)-\d{3}(\.[A-Z])?$
- IDs base:
UN-001,PR-001,SR-001 - Sub-IDs (tabular EARS-P):
PR-010.A,PR-010.B - Notação de cláusula:
SR-001.c1,SR-001.c2
Arquivos de referência
ears-guide.md— os 12 padrões EARStemplates.md— templates markdown para seções UN/PR/SRcompleteness.md— lista de verificação de saída (cobertura UN→PR→SR)