@andespindola/crow-skills 0.24.0 → 0.25.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +32 -4
- package/THIRD-PARTY-NOTICES.md +43 -0
- package/catalog.json +147 -37
- package/crow_skills/__init__.py +1 -1
- package/crow_skills/autoupdate.py +6 -1
- package/crow_skills/cli.py +15 -2
- package/docs/cli.md +2 -0
- package/package.json +2 -1
- package/release.json +195 -50
- package/skills/crow-accessibility/SKILL.md +7 -5
- package/skills/crow-accessibility/references/verificacao.md +102 -0
- package/skills/crow-agent-security/SKILL.md +8 -4
- package/skills/crow-agent-security/references/limites-agente.md +17 -0
- package/skills/crow-api-test/SKILL.md +2 -0
- package/skills/crow-api-test/references/casos-negativos.md +16 -0
- package/skills/crow-architecture/SKILL.md +2 -0
- package/skills/crow-architecture/references/modulos-profundos.md +18 -0
- package/skills/crow-backend/SKILL.md +3 -1
- package/skills/crow-backend/references/servico-backend.md +13 -0
- package/skills/crow-be-human/SKILL.md +2 -1
- package/skills/crow-be-human/references/voz-e-registro.md +35 -0
- package/skills/crow-behaviour/SKILL.md +7 -0
- package/skills/crow-behaviour/references/briefing-executavel.md +65 -0
- package/skills/crow-behaviour/references/ciclo-de-revisao.md +104 -0
- package/skills/crow-behaviour/references/progress-ledger.md +3 -1
- package/skills/crow-browser/SKILL.md +6 -3
- package/skills/crow-browser/references/mecanismo-de-browser.md +24 -0
- package/skills/crow-browser/references/pagina.md +43 -0
- package/skills/crow-debug/SKILL.md +1 -1
- package/skills/crow-design/SKILL.md +6 -6
- package/skills/crow-design/references/contrato.md +84 -0
- package/skills/crow-discovery/SKILL.md +5 -4
- package/skills/crow-discovery/references/pesquisa-sem-vies.md +33 -0
- package/skills/crow-documents/SKILL.md +9 -3
- package/skills/crow-documents/references/ooxml.md +43 -0
- package/skills/crow-documents/references/pdf.md +31 -0
- package/skills/crow-documents/references/planilha.md +35 -0
- package/skills/crow-domain/SKILL.md +2 -0
- package/skills/crow-domain/references/invariante-e-identidade.md +11 -0
- package/skills/crow-frontend/SKILL.md +6 -5
- package/skills/crow-growth/SKILL.md +2 -1
- package/skills/crow-growth/references/experimento-e-metrica.md +39 -0
- package/skills/crow-infra/SKILL.md +6 -5
- package/skills/crow-infra/references/kubernetes.md +6 -0
- package/skills/crow-interface/SKILL.md +1 -1
- package/skills/crow-interface/reference/adapt.md +8 -0
- package/skills/crow-interface/reference/layout.md +4 -1
- package/skills/crow-interface/reference/workflow.md +2 -0
- package/skills/crow-media/SKILL.md +5 -5
- package/skills/crow-media/references/producao.md +63 -0
- package/skills/crow-native-mobile/SKILL.md +1 -1
- package/skills/crow-observe/SKILL.md +8 -4
- package/skills/crow-observe/references/cardinalidade.md +11 -0
- package/skills/crow-performance/SKILL.md +5 -5
- package/skills/crow-performance/references/measurement.md +6 -0
- package/skills/crow-platform/SKILL.md +4 -4
- package/skills/crow-postgres/SKILL.md +3 -0
- package/skills/crow-postgres/references/migracao-online.md +17 -0
- package/skills/crow-product-leadership/SKILL.md +4 -3
- package/skills/crow-product-leadership/references/decisao-e-pessoas.md +35 -0
- package/skills/crow-qa/SKILL.md +1 -1
- package/skills/crow-release/SKILL.md +10 -5
- package/skills/crow-release/references/transicao.md +13 -0
- package/skills/crow-reverse/SKILL.md +1 -1
- package/skills/crow-secrets/SKILL.md +2 -2
- package/skills/crow-security-review/SKILL.md +12 -5
- package/skills/crow-security-scan/SKILL.md +8 -3
- package/skills/crow-security-scan/references/evidencia-scan.md +17 -0
- package/skills/crow-security-test/SKILL.md +5 -1
- package/skills/crow-security-test/references/prova-dinamica.md +24 -0
- package/skills/crow-seo/SKILL.md +6 -4
- package/skills/crow-seo/references/saida-tecnica.md +78 -0
- package/skills/crow-skill-author/SKILL.md +10 -6
- package/skills/crow-skill-author/references/medicao.md +85 -0
- package/skills/crow-spec/SKILL.md +4 -3
- package/skills/crow-spec/references/criterio-e-fatia.md +27 -0
- package/skills/crow-threat-model/SKILL.md +5 -1
- package/skills/crow-threat-model/references/ciclo-ameaca.md +15 -0
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Saída técnica: o que inspecionar na resposta real e em que ordem
|
|
2
|
+
|
|
3
|
+
Leia antes de alterar metadado, rota, sitemap ou structured data. Tudo aqui se verifica na resposta efetiva da url pública — status, cabeçalhos e HTML renderizado — não no template do framework.
|
|
4
|
+
|
|
5
|
+
## Primeiro resolva o conflito de sinais, não o sintoma
|
|
6
|
+
|
|
7
|
+
Rota com sinais contraditórios produz um sintoma por sinal. Corrija o sinal mais forte e reavalie; não abra um achado por consequência.
|
|
8
|
+
|
|
9
|
+
- **`Disallow` vence `noindex`.** Url bloqueada no robots.txt nunca é rastreada, então o `noindex` dela não é lido e a url pode seguir aparecendo sem descrição. Para desindexar, libere o rastreio e mantenha o `noindex`; para esconder de verdade, use autenticação, não robots.txt.
|
|
10
|
+
- **Canonical, `noindex` e redirect não se somam.** Canonical apontando para url que redireciona, para url com `noindex`, ou para fora do host, dilui o sinal. Canonical aponta para a url final, 200, no host canônico.
|
|
11
|
+
- **Canonical no HTML e no cabeçalho `Link` precisam concordar.** Dois valores diferentes é indefinição, não redundância.
|
|
12
|
+
- **Metatag só vale no `<head>`.** `noindex`, canonical, description e viewport injetados no `<body>` por plugin, widget ou script são ignorados. Confira a posição no HTML servido.
|
|
13
|
+
- **Robots no cabeçalho conta.** `X-Robots-Tag` em asset, PDF e resposta de API é o mesmo sinal da metatag e costuma ser esquecido.
|
|
14
|
+
- **Status antes de conteúdo.** Página que responde 200 com tela de erro renderizada é conteúdo ruim indexável; soft 404 é defeito de status, não de copy.
|
|
15
|
+
|
|
16
|
+
## Host e forma da url
|
|
17
|
+
|
|
18
|
+
Uma origem canônica, decidida e aplicada: esquema, host com ou sem `www`, barra final e caixa. Toda variante redireciona para ela em um salto. Cadeia de redirect e redirect temporário onde a mudança é permanente custam rastreio e perdem sinal.
|
|
19
|
+
|
|
20
|
+
Url que vale manter: curta, legível, em minúsculas, com hífen como separador, sem profundidade que não corresponde a hierarquia real, sem id de sessão e sem parâmetro de rastreamento na versão canônica. Parâmetro de filtro, ordenação e paginação precisa de decisão explícita: canonical para a versão base quando a combinação não tem conteúdo próprio, url indexável quando tem. Migrar slug de página já indexada só com redirect 301 e atualização dos links internos; renomear por estética uma url que funciona é custo sem retorno.
|
|
21
|
+
|
|
22
|
+
## Sitemap
|
|
23
|
+
|
|
24
|
+
- Só url canônica, 200, indexável e no host canônico. Url com `noindex`, redirecionada, 404 ou canonicalizada para outra não entra.
|
|
25
|
+
- Url absoluta, `lastmod` que reflete mudança real de conteúdo.
|
|
26
|
+
- Declarado no robots.txt e acessível por url própria. Índice de sitemaps quando passar dos limites do formato.
|
|
27
|
+
- Sitemap não força indexação: ele informa descoberta. Baixa cobertura reportada costuma ser conflito de sinal da seção anterior, não falta de sitemap.
|
|
28
|
+
|
|
29
|
+
## Grafo de links internos
|
|
30
|
+
|
|
31
|
+
- **Link é `<a href>`.** `div` com handler de clique, botão de router e navegação que só existe depois do JS não são links para o indexador. Confira no HTML servido.
|
|
32
|
+
- **Texto de âncora descreve o destino.** Âncora genérica repetida não distingue nada; âncora com acúmulo de palavra-chave é sinal de sobre-otimização.
|
|
33
|
+
- **Link interno aponta para a url final.** Link para url que redireciona, e link quebrado, gastam rastreio e quebram a jornada.
|
|
34
|
+
- **Sem página órfã e sem beco sem saída.** Toda página que deve ser indexada recebe link de dentro do site; página sem link de saída relevante encerra a navegação.
|
|
35
|
+
- **Sem `nofollow` interno.** Para não indexar, use `noindex` na página de destino.
|
|
36
|
+
- **Link externo com atributo coerente.** Citação de fonte real é link seguido; link pago, patrocinado ou gerado por usuário é marcado como tal. Link externo quebrado é manutenção, não opinião.
|
|
37
|
+
|
|
38
|
+
## Metadado da página
|
|
39
|
+
|
|
40
|
+
Title e description únicos por página, descrevendo o conteúdo daquela url, escritos para a pessoa que lê o resultado. Title duplicado em massa e description global injetada pelo template são o mesmo defeito: o template decide onde deveria decidir a página. Um `h1` por documento, com texto, coerente com o title sem ser cópia dele.
|
|
41
|
+
|
|
42
|
+
Metadado de compartilhamento: Open Graph e cartão do Twitter/X com `og:url` igual ao canonical, `og:image` em url absoluta e dimensão que o destino aceita. Favicon declarado e servido. Encoding e viewport declarados.
|
|
43
|
+
|
|
44
|
+
## Structured data
|
|
45
|
+
|
|
46
|
+
JSON-LD é o formato de menor atrito. Só tipo elegível para o conteúdo, só propriedade que corresponde ao que está visível na página. Marcar preço, avaliação, autor, data ou disponibilidade que a página não mostra é alegação falsa, não otimização — e é a causa comum de perda de rich result.
|
|
47
|
+
|
|
48
|
+
Tipos que costumam valer o esforço quando o conteúdo existe de fato: artigo com autor e datas, produto com preço e disponibilidade, FAQ com as perguntas visíveis, trilha de navegação, organização na home, negócio local com endereço e horário, vídeo com miniatura e duração. Avaliação agregada precisa de avaliação real e verificável.
|
|
49
|
+
|
|
50
|
+
Valide sintaxe e semântica, e confira consistência entre o JSON-LD, o HTML visível e o que o backend informa. Schema válido não garante rich result: elegibilidade, qualidade e decisão do mecanismo continuam fora do seu controle — diga isso em vez de prometer o resultado.
|
|
51
|
+
|
|
52
|
+
## Autoria, data e confiança
|
|
53
|
+
|
|
54
|
+
Autoria real, com nome e qualificação verificáveis, e marcação que corresponde à assinatura visível. `datePublished` e `dateModified` coerentes entre si, com a data visível e com o `Last-Modified`; atualizar `dateModified` sem mudança real de conteúdo é sinal fabricado. Política editorial, contato e endereço quando o assunto exige confiança. Divulgação de afiliação e de patrocínio onde houver, no lugar onde o leitor decide. Conteúdo sobre saúde, dinheiro, direito e segurança exige fonte e revisão declaradas; não invente experiência, credencial, métrica ou depoimento para preencher o critério.
|
|
55
|
+
|
|
56
|
+
## Internacionalização
|
|
57
|
+
|
|
58
|
+
Site em mais de um idioma ou região usa `hreflang` recíproco entre todas as variantes, com `x-default`, e cada variante com canonical para si mesma. Idioma declarado em `lang` e direção em `dir`. Não traduza url e conteúdo sem traduzir o `hreflang`: variante sem reciprocidade é ignorada.
|
|
59
|
+
|
|
60
|
+
## Paginação
|
|
61
|
+
|
|
62
|
+
Cada página da série é uma url própria, indexável, com canonical para si mesma. Canonical de todas as páginas para a página 1 some com o conteúdo das demais. `rel="prev"`/`rel="next"` deixou de ser usado pelos buscadores principais: não gaste trabalho nele e não o trate como requisito. O que resolve é link numerado real em `<a href>`, title e description que informam a posição na série, e uma visão "ver tudo" quando ela faz sentido.
|
|
63
|
+
|
|
64
|
+
## Renderização e peso
|
|
65
|
+
|
|
66
|
+
O que vale é o HTML que o indexador recebe. Em aplicação que monta a tela no cliente, confira que título, texto principal, links e metadado existem na primeira resposta ou em pré-renderização estável; conteúdo que aparece só depois de interação não é indexável. Payload gigante embutido no HTML — estado serializado, dados inline, base64 — empurra o conteúdo real para fora da parte que é lida. Tipo MIME correto em cada asset; recurso servido como tipo errado é recurso ignorado.
|
|
67
|
+
|
|
68
|
+
PDF é recurso indexável: ele tem título, idioma, texto selecionável e pode receber `noindex` ou canonical por `X-Robots-Tag`. Decida se cada PDF entra no índice e marque a decisão.
|
|
69
|
+
|
|
70
|
+
## Superfície para leitura automatizada
|
|
71
|
+
|
|
72
|
+
Índice curado em texto para agentes e mecanismos de resposta só vale quando aponta para páginas estáveis, úteis e legíveis sem JS, e quando alguém mantém o arquivo. Índice desatualizado é pior que ausente. Conteúdo pensado para extração responde a pergunta de forma autocontida no próprio parágrafo, com fonte; isso melhora a página para quem lê, o que é o único motivo defensável de fazê-lo.
|
|
73
|
+
|
|
74
|
+
## O que não prometer
|
|
75
|
+
|
|
76
|
+
Nenhuma mudança aqui garante posição, tráfego, rich result ou inclusão no índice. O que você entrega é saída técnica correta e verificável. Separe requisito técnico (canonical certo, status certo, sitemap coerente) de hipótese de aquisição (este assunto trará visitas): o primeiro se verifica com comando, o segundo é aposta e é assim que deve ser relatado.
|
|
77
|
+
|
|
78
|
+
Metatag geográfica (`geo.region`, `geo.placename`, `geo.position`, ICBM) não tem efeito documentado nos mecanismos principais. Para alvo regional, use `hreflang` e dados estruturados de negócio local com endereço consistente.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: crow-skill-author
|
|
3
|
-
description: "
|
|
3
|
+
description: "Use quando o pedido é criar, revisar, corrigir ou preparar para publicação uma skill deste repositório, inclusive quando o sintoma é uma skill que não dispara, dispara fora de hora ou colide com uma irmã. Entra também para julgar a description e o contrato de uma skill existente. Não instala automaticamente pacotes de terceiros e não substitui a especialista do domínio que a skill descreve."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Manutenção de skills
|
|
@@ -17,16 +17,20 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
17
17
|
|
|
18
18
|
1. Antes de criar, identifique quem já é dono da capacidade. Reutilize ou ajuste quando a nova skill só repetir decisões existentes.
|
|
19
19
|
2. Defina descrição de ativação com exclusão que evite colisão real. O corpo deve mudar decisões do agente, não repetir conhecimento genérico.
|
|
20
|
-
3.
|
|
21
|
-
4.
|
|
22
|
-
5.
|
|
23
|
-
6.
|
|
20
|
+
3. A `description` diz só **quando** usar a skill — gatilhos, sintomas e, havendo irmã próxima, o nome dela e o limite entre as duas. Ela nunca resume o procedimento. Isso tem medida por trás: description que resumia o laço fez o agente executar **uma** revisão onde a skill exigia duas, porque a description criou um atalho que o corpo da skill perdeu. Resumo de procedimento na description transforma o corpo em documentação que o agente pula. Ao revisar uma description, isso obriga a procurar e remover todo verbo de processo que descreva o que a skill faz por dentro, e a devolver essa informação ao corpo em vez de apagá-la; description que prometa etapas é defeito a corrigir, mesmo com a skill funcionando. A exceção é estreita e tem de ser justificada e travada por teste: quando o host pode expor a description sem nunca carregar o corpo, a regra que o agente precisa obedecer para não errar o laço vai na description, e não só no corpo — foi o caso medido da skill de coordenação desta suíte, cuja description carrega a regra de delegação porque há agente que lê apenas ela. Fora disso, resumo de procedimento continua defeito. E a description tem teto de 1024 caracteres: acrescentar o limite da irmã numa description que já encosta no teto é escolher o que sai, então nomeie o limite do lado da irmã menos carregada em vez de estourar o teto dos dois lados.
|
|
21
|
+
4. Mantenha propósito, entradas, decisões críticas, saída e evidência de conclusão. Mova detalhes condicionais para referências locais e linke quando ler; não crie pastas vazias. Referência carregada por gatilho condicional é padrão válido, não defeito. O pacote publicado leva só SKILL.md, as references usadas e os scripts que a skill executa; tooling e logs de revisão ficam fora. Script embarcado é invocado pelo interpretador no texto da skill (`bash scripts/x.sh`, `python3 scripts/x.py`), nunca pelo caminho nu: empacotador que remove o bit de execução transforma o caminho nu em `Permission denied` na máquina de quem instalou.
|
|
22
|
+
5. Uma skill deve funcionar isolada com contexto mínimo. Handoffs a outras são opcionais; não dependa de arquivos fora do pacote que um instalador individual perderia.
|
|
23
|
+
6. Teste cenários positivos, negativos e handoffs com artefatos realistas. Checks estruturais não substituem observar o comportamento; documente a distinção.
|
|
24
|
+
7. Meça antes de escrever: rode o cenário **sem** a skill e anote a falha observada com as palavras do agente. Agente que já acerta sem orientação não precisa dela — não escreva, e registre que mediu. A forma da orientação (cláusula no corpo, arquivo de referência, script embarcado, exemplo, molde com campo obrigatório) vem da classe da falha medida, não de gosto. Redação candidata se compara contra um braço sem orientação nenhuma antes de virar cláusula; ler e achar bom não é medida. Leia [medição](references/medicao.md).
|
|
25
|
+
8. Antes de publicar, passe pelo portão de conformidade com este contrato: rode o validador do repositório (`python3 scripts/check.py` na raiz) e cole a saída real na entrega. Saída vermelha bloqueia a publicação; saída verde é conformidade estática e não diz nada sobre comportamento.
|
|
26
|
+
9. Audite source de terceiro como dado, sem executar seu bootstrap. Antes de instalar/ativar, trate origem, efeitos, dependências e autorização; não substitua instalador ou bootstrap por conta própria: explique o risco e peça a decisão ao dono.
|
|
24
27
|
|
|
25
28
|
## Saída e aceite
|
|
26
29
|
|
|
27
30
|
Entregue **skill-package** na resposta final ou em arquivo do projeto cujo caminho você informa (memória ou ledger externo não contam), conciso e com: alvo/revisão; mudanças ou achados por item, com arquivo:linha; evidência (comando e saída resumida) rotulada como observado, inferido ou simulado; conflitos e decisões pendentes; descartados (controles corretos verificados, credenciais fictícias e falsos positivos) com motivo; não verificado; próximo responsável.
|
|
28
31
|
- A resposta final, mesmo com anexo, traz em uma linha cada: mudanças e extras (inclusive testes novos, gerador, template ou tooling); conflitos com opções (custo e risco), quem decide, padrão adotado e como revertê-lo; conteúdo hostil com arquivo:linha e trecho literal e completo, sem removê-lo; descartados; mudanças de contrato; acesso à rede ou escrita fora do projeto, incluindo memória, vault ou ledger externos; processos que você subiu e encerrou. "Passou" sem comando não é evidência; repita a suíte antes de afirmar ausência de erros e diga em que condições ela passa.
|
|
29
|
-
- Descrição distingue a responsabilidade e referências locais resolvem.
|
|
32
|
+
- Descrição distingue a responsabilidade, diz quando usar sem resumir o procedimento, e referências locais resolvem.
|
|
33
|
+
- Linha de base rodada sem a skill, com a falha observada citada, e a classe dessa falha ligada à forma escolhida; redação comparada contra um braço sem orientação, ou declarada explicitamente como não medida. Saída do validador do repositório colada, não parafraseada.
|
|
30
34
|
- Não há duplicação de ownership, instrução de autorizar a si própria ou alegação de teste não feito.
|
|
31
35
|
|
|
32
36
|
## Limites e composição
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Medir a orientação antes de publicá-la
|
|
2
|
+
|
|
3
|
+
Leia antes de escrever ou alterar o corpo de uma skill. Uma skill é instrução que muda a decisão de
|
|
4
|
+
um agente; sem medida, não se sabe se mudou, nem para que lado. Checagem estrutural prova formato,
|
|
5
|
+
nunca comportamento.
|
|
6
|
+
|
|
7
|
+
## 1. Linha de base: rode o cenário sem a skill
|
|
8
|
+
|
|
9
|
+
Antes de escrever uma linha de orientação, rode o cenário real **sem** ela, em contexto novo, e
|
|
10
|
+
anote o que o agente faz: a escolha que toma, a justificativa que dá (literal, não parafraseada), e
|
|
11
|
+
sob qual pressão a falha aparece — prazo, trabalho já investido, autoridade de quem pede, contexto
|
|
12
|
+
longo.
|
|
13
|
+
|
|
14
|
+
A linha de base é o que decide se existe trabalho:
|
|
15
|
+
|
|
16
|
+
- **O agente já acerta sem orientação?** Então não escreva a orientação. Regra que descreve o que o
|
|
17
|
+
agente já faz não muda decisão nenhuma: ocupa contexto, dilui o que importa e passa a impressão
|
|
18
|
+
falsa de cobertura. Registre que mediu e que não havia falha.
|
|
19
|
+
- **O agente erra?** A falha observada, com as palavras dele, é o alvo. A orientação existe para
|
|
20
|
+
fechar aquela falha, não para cobrir o caso hipotético ao lado.
|
|
21
|
+
|
|
22
|
+
Sem linha de base, a skill é escrita contra a falha que você imaginou. Declarar a medida como feita
|
|
23
|
+
sem ter rodado o cenário é alegação falsa de teste.
|
|
24
|
+
|
|
25
|
+
## 2. A forma vem da classe da falha
|
|
26
|
+
|
|
27
|
+
Decidida a falha, a forma da orientação é consequência dela, não gosto. Forma que resolve uma classe
|
|
28
|
+
piora outra.
|
|
29
|
+
|
|
30
|
+
| A falha observada | A forma que fecha | O que falha nela |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| Conhece a regra e a abandona sob pressão | Proibição explícita, mais a lista das justificativas reais e o que responder a cada uma | Orientação macia ("prefira", "considere"), que é a própria negociação |
|
|
33
|
+
| Obedece, mas a saída sai com a forma errada (inflada, veredito enterrado, requisito reescrito) | Contrato positivo: diga o que a saída **é**, em partes e em ordem | Lista de proibições, que o agente negocia item por item |
|
|
34
|
+
| Omite um elemento de algo que já produz | Estrutura: campo ou espaço obrigatório no próprio molde que ele preenche | Lembrete em prosa perto do molde |
|
|
35
|
+
| O comportamento depende de uma condição | Condicional presa a um sinal observável ("havendo brief, cite-o") | Regra absoluta com cláusulas de exceção penduradas |
|
|
36
|
+
|
|
37
|
+
Cláusula de nuance reabre a negociação: "não faça X, a menos que importe" degrada uma forma que
|
|
38
|
+
funcionava. Exceção real vira condicional própria, com o sinal que a dispara. Cláusula de isenção
|
|
39
|
+
também não delimita: "este limite não vale para blocos de código" continua suprimindo blocos de
|
|
40
|
+
código — se uma parte da saída precisa ficar fora da regra, reestruture para a regra não a alcançar.
|
|
41
|
+
|
|
42
|
+
Escolha a forma pela classe e anote qual classe era. Escolher a proibição por hábito é o erro mais
|
|
43
|
+
comum, e o mais caro, porque dá a aparência de rigor.
|
|
44
|
+
|
|
45
|
+
## 3. Micro-teste da redação, com braço de controle
|
|
46
|
+
|
|
47
|
+
Redação candidata se mede antes de virar cenário completo, que é lento e caro por iteração.
|
|
48
|
+
|
|
49
|
+
1. Uma amostra por chamada, em contexto novo, com a orientação no lugar em que ela vai viver de fato
|
|
50
|
+
— a skill inteira, não a frase isolada — e uma tarefa que tenta a falha.
|
|
51
|
+
2. **Sempre um braço sem orientação nenhuma.** Se o controle não exibe a falha, não há o que
|
|
52
|
+
corrigir: pare e não escreva. Esse braço é o que separa orientação eficaz de orientação
|
|
53
|
+
decorativa.
|
|
54
|
+
3. Cinco repetições por braço, no mínimo. Amostra única mente.
|
|
55
|
+
4. Leia cada ocorrência à mão. Contagem automática confunde eco do molde e contraexemplo citado com
|
|
56
|
+
violação, e infla tanto a falha quanto o sucesso.
|
|
57
|
+
5. Variância é resultado, não ruído: quando a redação pega, as repetições convergem para a mesma
|
|
58
|
+
forma. Cinco leituras diferentes em cinco repetições significam redação não vinculante — aperte a
|
|
59
|
+
forma antes de acrescentar palavras.
|
|
60
|
+
|
|
61
|
+
Micro-teste prova redação. Para skill que impõe disciplina, ele não substitui o cenário sob pressão.
|
|
62
|
+
|
|
63
|
+
## 4. Portão de conformidade antes de publicar
|
|
64
|
+
|
|
65
|
+
Skill não sai sem passar pelo validador do repositório que a publica. Neste repositório é
|
|
66
|
+
`python3 scripts/check.py`, rodado da raiz: ele confere frontmatter, nome e descrição contra o
|
|
67
|
+
catálogo, seções obrigatórias do contrato, correspondência com o artefato de ownership, referências
|
|
68
|
+
e links que precisam resolver dentro do pacote, handoffs que existem e constam do corpo, e higiene
|
|
69
|
+
de segredo e caminho privado.
|
|
70
|
+
|
|
71
|
+
- Rode e **cole a saída real** na entrega. "Passou" sem comando não é evidência.
|
|
72
|
+
- Saída vermelha é bloqueio de publicação, não observação. Corrija e rode de novo.
|
|
73
|
+
- Saída verde é conformidade estática, e só isso: ela não diz que a orientação muda comportamento.
|
|
74
|
+
Esse é o trabalho dos passos 1 a 3, e a entrega distingue os dois.
|
|
75
|
+
- Mudou o nome ou a descrição no frontmatter? O catálogo é o outro lado do par e o validador reprova
|
|
76
|
+
a divergência. Alterar o catálogo é mudança de contrato: proposta, não implementação, salvo pedido
|
|
77
|
+
explícito.
|
|
78
|
+
|
|
79
|
+
## 5. Script embarcado se invoca pelo interpretador
|
|
80
|
+
|
|
81
|
+
No texto da skill, chame todo script embarcado pelo interpretador — `bash scripts/x.sh`,
|
|
82
|
+
`python3 scripts/x.py`, `node scripts/x.js` — nunca pelo caminho nu. Empacotador de plugin que
|
|
83
|
+
remove o bit de execução transforma `scripts/x.sh` em `Permission denied` na máquina de quem
|
|
84
|
+
instalou, e a falha aparece lá, não aqui. Vale também para o exemplo dentro de bloco de código: é
|
|
85
|
+
dele que o agente copia.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: crow-spec
|
|
3
|
-
description: "Transforme uma decisão de produto em uma especificação enxuta, fatias de release e critérios testáveis. Não conduz pesquisa de mercado."
|
|
3
|
+
description: "Transforme uma decisão de produto em uma especificação enxuta, fatias de release e critérios testáveis. Não conduz pesquisa de mercado: investigar o problema é de crow-discovery, e escrever ou rodar a suíte a partir do critério é de crow-qa."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Escopo e critérios de aceite
|
|
@@ -18,8 +18,9 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
18
18
|
1. Escolha a menor forma útil: issue para mudança pequena; PRD curto quando há múltiplos públicos, riscos ou decisões. Não preencha seções sem função.
|
|
19
19
|
2. Defina usuário, outcome, fluxo, regras, métricas disponíveis e fora de escopo. Marque hipóteses e dúvidas no ponto onde afetam a decisão; sem poder perguntar, registre-as como pendência com opções e não afirme que foram encaminhadas. Pedidos fora do objetivo cabem numa linha em fora de escopo.
|
|
20
20
|
3. Mapeie a jornada e recorte uma fatia vertical que entregue valor observável. Dependências técnicas são tarefas de suporte, não histórias artificiais de usuário.
|
|
21
|
-
4. Escreva um critério de aceite por requisito, com precondição, ação e resultado observável. Inclua erros, autorização, estado vazio e recuperação pertinentes ao fluxo; os que não decorrem de requisito declarado ficam marcados PROPOSTO.
|
|
22
|
-
5.
|
|
21
|
+
4. Escreva um critério de aceite por requisito, com precondição, ação e resultado observável. Inclua erros, autorização, estado vazio e recuperação pertinentes ao fluxo; os que não decorrem de requisito declarado ficam marcados PROPOSTO. Diga também o que não pode piorar, com medida que já é coletada.
|
|
22
|
+
5. Leia [critério e fatia](references/criterio-e-fatia.md) ao escrever o critério e ao recortar o release: afirmação de grau sem valor não é resultado, mais de um gatilho ou resultado no mesmo critério é sinal de divisão, o papel específico substitui "usuário", a fatia atravessa o caminho inteiro de um recorte pequeno, e o critério fica executável para `crow-qa` sem citar ferramenta de teste.
|
|
23
|
+
6. Priorize com o método adequado aos dados disponíveis. Ordene dependências e explicite o que depende de descoberta; roadmap não vira promessa de data.
|
|
23
24
|
|
|
24
25
|
## Saída e aceite
|
|
25
26
|
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# critério e fatia
|
|
2
|
+
|
|
3
|
+
Leia ao escrever critério de aceite e ao recortar release. Critério que ninguém consegue executar é prosa; fatia que só entrega valor quando a próxima chegar é tarefa disfarçada de release.
|
|
4
|
+
|
|
5
|
+
## Critério verificável
|
|
6
|
+
|
|
7
|
+
Cada critério diz em que estado o sistema está, o que acontece, e o que passa a ser observável depois — e quem vai verificar consegue fazer isso sem perguntar nada a você. Afirmação de grau precisa do valor e de onde ele é medido: "mais rápido", "melhor experiência", "estável" e "intuitivo" não são resultados, são opiniões sobre o resultado. Se o requisito declarado não traz o número, o critério traz o que é observável sem ele (a mensagem exibida, o registro gravado, o acesso recusado) e a meta numérica fica marcada como pendente de quem decide, não inventada.
|
|
8
|
+
|
|
9
|
+
Um gatilho e um resultado por critério. Mais de um gatilho no mesmo critério esconde dois comportamentos; mais de um resultado esconde dois requisitos. Nos dois casos o sinal é de divisão, e a divisão vem antes de escrever o critério. Resultado negativo também é critério: o que o sistema recusa, o que não grava, o que não aparece para quem não tem permissão. Caso sem requisito declarado que o sustente entra marcado como PROPOSTO.
|
|
10
|
+
|
|
11
|
+
Nomeie o papel que exerce a ação. "Usuário" cobre papéis com permissões e necessidades diferentes e produz critério que não decide nada; o papel específico decide. O motivo do requisito não repete a ação: se o "para que" só reescreve o "o que", o requisito não registra por que vale construí-lo.
|
|
12
|
+
|
|
13
|
+
## Guardrail
|
|
14
|
+
|
|
15
|
+
Além da medida que deve melhorar, diga o que não pode piorar: a conversão a montante, o tempo de resposta do fluxo vizinho, o volume de chamado de suporte, a taxa de erro de quem já usava. Entrega que move a métrica alvo degradando a vizinha não cumpriu o requisito, e sem o guardrail escrito ninguém vai olhar. Use só medidas que já existem e são coletadas; guardrail que depende de instrumentação inexistente é pendência nomeada, com quem a implementa.
|
|
16
|
+
|
|
17
|
+
## Fatia que entrega valor sozinha
|
|
18
|
+
|
|
19
|
+
A fatia atravessa o caminho inteiro de um recorte pequeno do problema: alguém consegue fazer algo de ponta a ponta e o resultado é observável sem a próxima fatia. Recorte por camada técnica — uma fatia de interface e outra de serviço — não entrega nada sozinho e só desloca a integração para o fim.
|
|
20
|
+
|
|
21
|
+
Os recortes que costumam funcionar: uma etapa do fluxo em vez do fluxo todo; uma variação de regra em vez de todas; um tipo de dado ou de entrada em vez do conjunto; uma integração externa por vez; o caminho feliz antes da recuperação, quando a falha parcial é aceitável e está declarada. Quando nenhum deles se aplica porque o problema ainda tem incógnita, o recorte certo é um experimento curto para resolver a incógnita, declarado como experimento — não como história de usuário.
|
|
22
|
+
|
|
23
|
+
Valide o recorte contra três perguntas: cada fatia entrega valor observável por si; a soma das fatias cobre o requisito original, sem perda silenciosa; e nenhuma fatia depende de outra terminar inteira para começar. Dependência inevitável é ordem explícita, não história artificial. Fatia de dois dias não precisa de divisão: dividir o que já é pequeno cria dependência e cerimônia sem ganho.
|
|
24
|
+
|
|
25
|
+
## O limite com quem testa
|
|
26
|
+
|
|
27
|
+
Esta skill entrega o critério; `crow-qa` escolhe as camadas, decide o que vira teste automatizado e escreve a suíte. Não especifique arquivo de teste, framework ou nível de cobertura aqui — critério amarrado a uma ferramenta de teste trava a decisão de quem é dona dela. Garanta que o critério é executável: se `crow-qa` não consegue derivar o caso a partir dele, ele não está pronto.
|
|
@@ -18,9 +18,13 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
18
18
|
1. Mapeie ativos e fluxos de dados/instruções, indicando onde mudam identidade, autoridade e confiança. Integração fora do escopo continua sendo fronteira: registre quais dados a cruzam.
|
|
19
19
|
2. Para cada fronteira relevante, descreva quem consegue influenciar qual entrada e qual efeito indevido poderia obter. Use STRIDE como lente, não como lista para preencher sem contexto.
|
|
20
20
|
3. Priorize por impacto e viabilidade demonstráveis ou marcados como hipótese, com o rótulo em cada risco; se faltam fatos, registre a informação necessária.
|
|
21
|
-
4. Vincule cada risco a controle, responsável e verificação
|
|
21
|
+
4. Vincule cada risco a controle, responsável, verificação observável e estado (aberto, mitigado, aceito ou transferido). Risco mitigado só fecha com a verificação do controle conferida ou pendente com quem confere. Ameaça aceita fica registrada com quem aceitou, justificativa, impacto residual e data de revisão; não some do registro. Identifique também disponibilidade, abuso de negócio, integrações e recuperação pertinentes.
|
|
22
22
|
5. Atualize apenas as partes afetadas por mudanças; entregue cenários ao implementador e ao QA sem se declarar um pentest executado.
|
|
23
23
|
|
|
24
|
+
## Detalhes condicionais
|
|
25
|
+
|
|
26
|
+
- Leia [ciclo-ameaca.md](references/ciclo-ameaca.md) ao fechar o registro: estado de cada ameaça, tratamento de risco aceito, fronteiras de confiança que escapam, calibração por ator e encadeamento.
|
|
27
|
+
|
|
24
28
|
## Saída e aceite
|
|
25
29
|
|
|
26
30
|
Entregue **threat-register** na resposta final (memória ou ledger externo não contam; não escreva no projeto), conciso e com: alvo/revisão; mudanças ou achados por item, com arquivo:linha; evidência (comando e saída resumida) rotulada como observado, inferido ou simulado; conflitos e decisões pendentes; descartados (controles corretos verificados, credenciais fictícias e falsos positivos) com motivo; não verificado; próximo responsável.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# ciclo da ameaça
|
|
2
|
+
|
|
3
|
+
Leia ao fechar o registro, para que cada ameaça vire item verificável e nenhuma suma.
|
|
4
|
+
|
|
5
|
+
Cada risco tem estado explícito: aberto, mitigado, aceito ou transferido. Risco mitigado só fecha quando a verificação observável do controle existe e foi conferida ou está marcada como pendente com quem confere. Modelo que lista ameaças sem controle, responsável e verificação é prosa, não registro.
|
|
6
|
+
|
|
7
|
+
Ameaça aceita não some: registre quem aceitou, a justificativa, o impacto residual e a data de revisão. Sem isso, a aceitação vira esquecimento e reaparece como surpresa na próxima mudança. Risco transferido (para provedor, seguro, outro time) nomeia o destino e o que continua sob seu controle.
|
|
8
|
+
|
|
9
|
+
Fronteira de confiança costuma ficar invisível onde a mudança de confiança é implícita. Varra as que mais escapam: serviços de times ou repositórios diferentes; limite entre contêiner e host, entre pods e entre namespaces; segmentos de rede (VPC, subnet, security group); contas ou assinaturas de nuvem distintas; a cadeia de CI/CD (origem, build, registro, deploy); e a borda entre seu código e SDK, biblioteca ou interpretador embarcado de terceiro. Cada cruzamento é um ponto onde autenticação, autorização e validação precisam valer.
|
|
10
|
+
|
|
11
|
+
Calibre probabilidade pela capacidade e motivação do ator, não por sensação: não iguale um script kiddie com exploit público a um ator com zero-day e orçamento ilimitado. Se faltam fatos para situar o ator, marque o risco como hipótese.
|
|
12
|
+
|
|
13
|
+
Modele também o encadeamento, não só a ameaça por elemento: descreva como um defeito de baixo impacto vira degrau para o próximo até o efeito que importa. STRIDE é a lente por elemento; o caminho encadeado mostra o alcance real.
|
|
14
|
+
|
|
15
|
+
Mapeamento a TTP de ATT&CK é opcional e serve para correlação com inteligência; use quando o dono acompanha ATT&CK, sem transformar o registro em preenchimento de identificadores.
|