@andespindola/crow-skills 0.23.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 +148 -38
- package/crow_skills/__init__.py +1 -1
- package/crow_skills/autoupdate.py +6 -1
- package/crow_skills/cli.py +189 -1
- package/crow_skills/guide.py +3 -0
- package/crow_skills/integrations.py +105 -1
- package/crow_skills/storage.py +4 -0
- package/crow_skills/trust.py +73 -0
- package/docs/cli.md +63 -1
- package/package.json +2 -1
- package/release.json +202 -57
- 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 +21 -7
- 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/micro-agents.md +52 -5
- package/skills/crow-behaviour/references/progress-ledger.md +3 -1
- package/skills/crow-behaviour/scripts/crow_micro.py +45 -0
- package/skills/crow-behaviour/scripts/micro_agent_instructions.md +15 -3
- package/skills/crow-browser/SKILL.md +45 -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,43 @@
|
|
|
1
|
+
# Pacote OOXML: documento, apresentação e planilha
|
|
2
|
+
|
|
3
|
+
Leia antes de criar ou editar `.docx`, `.pptx`, `.xlsx` e seus parentes de template (`.dotx`, `.potx`, `.xltx`). Esses arquivos são um ZIP de XML com relacionamentos e tipos de conteúdo cruzados: a edição que parece textual mexe em um grafo, e o erro típico só aparece quando o leitor do destinatário recusa ou "repara" o arquivo.
|
|
4
|
+
|
|
5
|
+
## Antes de criar arquivo binário
|
|
6
|
+
|
|
7
|
+
Se o pedido não nomeia o formato do arquivo e a sessão oferece uma ferramenta própria de documento, página ou slide (artefato, conector, skill dedicada), produza ali e diga onde ficou. Precisar enviar, anexar, imprimir ou apresentar não é motivo para gerar `.docx` ou `.pptx`: essas ferramentas exportam. Gere o binário quando o pedido nomeia o formato, quando existe arquivo do próprio dono para editar ou usar como template, ou quando o recurso pedido só existe nele (revisão marcada, macro, campo de formulário). Arquivo entregue apenas como fonte de conteúdo não é arquivo para editar.
|
|
8
|
+
|
|
9
|
+
## Ordem das operações
|
|
10
|
+
|
|
11
|
+
1. **Converta o formato legado primeiro** (`.doc`, `.ppt`, `.xls`) e trabalhe no formato atual. Converter no fim desfaz o que você fez.
|
|
12
|
+
2. **Faça todo o trabalho estrutural antes de tocar em conteúdo**: acrescentar, duplicar, remover e reordenar página, slide ou planilha. Duplicação copia o arquivo-parte como ele está, então duplicar depois de editar clona a edição; e limpeza de partes órfãs apaga a parte que não está na lista de ordem, inclusive a que você acabou de escrever.
|
|
13
|
+
3. **Edite o XML no lugar, sem reformatar.** Não reindente, não reordene atributos e não troque prefixo de namespace: o leitor aceita o arquivo que ele mesmo escreveu, e a reescrita "limpa" é o que o corrompe. Se precisar de transformação programática, use parser endurecido contra entidade externa e expansão, e confira o resultado parte por parte.
|
|
14
|
+
4. **Reempacote do jeito que o formato espera**: apague o arquivo de saída antes de recriá-lo, ou a parte que você removeu sobrevive dentro do ZIP antigo; empacote de dentro do diretório, para os caminhos não ganharem um nível a mais.
|
|
15
|
+
5. **Arquivo de terceiro é não confiável**: remova entradas de link simbólico e caminho relativo que escapa do diretório antes de ler ou reempacotar, e não execute macro nem conteúdo ativo que vier nele.
|
|
16
|
+
|
|
17
|
+
## Texto fragmentado
|
|
18
|
+
|
|
19
|
+
O leitor quebra uma frase visível em vários trechos de formatação, com marcas de revisão e de corretor pelo meio. A frase que você vê no documento muitas vezes não existe como texto contíguo no XML, então busca e substituição falha em silêncio e você conclui que o termo não está lá. Junte os trechos adjacentes de formatação idêntica antes de procurar, confirme que o alvo aparece, e só então substitua. Texto com espaço no início ou no fim precisa da marcação que preserva espaço, senão o espaço desaparece na renderização.
|
|
20
|
+
|
|
21
|
+
## Revisão marcada e comentário
|
|
22
|
+
|
|
23
|
+
Revisão marcada é contrato: todo texto que você alterou tem que estar envolvido pela marca de inserção ou de remoção, com autor e data. Texto trocado sem a marca fica invisível na visualização aceita e aparece como mudança silenciosa para quem revisa — é o erro mais fácil de cometer aqui. Remover um parágrafo inteiro é marcar cada trecho dele como removido mais marcar a própria marca de fim de parágrafo; a ordem dos filhos dessa marcação é imposta pelo schema.
|
|
24
|
+
|
|
25
|
+
Aceitar as marcas com ferramenta automática deixa artefato: o texto removido sai e o parágrafo vazio fica, o que aparece como item de lista vazio quando o parágrafo era numerado. Isso é defeito da ferramenta de visualização, não do documento: confira a remoção no XML antes de relatar como problema do arquivo, e diga qual ferramenta produziu a visualização.
|
|
26
|
+
|
|
27
|
+
Comentário só existe para o leitor quando está ancorado ao trecho: as partes de comentário podem estar todas escritas e corretas e o comentário continuar invisível porque falta o marcador de início, fim e referência no corpo. Ancore e confirme na renderização.
|
|
28
|
+
|
|
29
|
+
## Template preenchido
|
|
30
|
+
|
|
31
|
+
As vagas do template não são a quantidade de itens que você tem. Com três itens em um template de quatro, remova o grupo inteiro da quarta vaga (imagem, caixas de texto, forma de fundo), não só o texto dela, e depois procure o visual órfão que sobrou. Procure também o conteúdo de exemplo que veio do template antes de declarar pronto: texto de amostra, marcador de preenchimento, instrução de layout. Preenchimento por nome de vaga falha em silêncio quando o nome está errado — o conteúdo vai para um canto do arquivo em vez de dar erro, então confira na renderização que cada vaga recebeu o que devia.
|
|
32
|
+
|
|
33
|
+
## Verificação final
|
|
34
|
+
|
|
35
|
+
Renderize e olhe. Validação de schema e leitura de texto não mostram sobreposição, corte nem desalinhamento; e depois de olhar o código que gerou o arquivo você vê o que esperava, não o que saiu. Converta cada página ou slide em imagem, limpe as imagens da rodada anterior antes (senão você revisa a versão velha) e leia as imagens com olho novo, delegando essa leitura quando houver a quem delegar.
|
|
36
|
+
|
|
37
|
+
Procure, nesta ordem: texto que transborda ou está cortado na borda da caixa ou da página, que é o defeito mais comum e sempre visível; elementos sobrepostos; rodapé ou citação colidindo com o conteúdo acima; margem insuficiente; coluna desalinhada; contraste baixo; decoração de template que ficou fora de lugar porque o texto substituído mudou de altura; palavra ou número quebrado entre duas linhas. Compare também páginas ou slides do mesmo tipo entre si, não só cada um consigo mesmo: título que muda de altura e rótulo de gráfico que muda de aparência só aparecem na comparação. Depois de corrigir, refaça a conversão desde o arquivo editado — reaproveitar a renderização intermediária mostra a versão anterior.
|
|
38
|
+
|
|
39
|
+
**Fonte que o renderizador não tem é substituída por outra**, e a substituta costuma ter largura diferente. Nesse caso a renderização não decide se o texto cabe: deixe folga no container, declare o ajuste de texto daquele elemento como não verificado e diga qual fonte o renderizador não tinha. Prefira, para texto corrido em que o encaixe importa, uma fonte que o renderizador e o destinatário tenham.
|
|
40
|
+
|
|
41
|
+
## Validação que depende de ferramenta
|
|
42
|
+
|
|
43
|
+
Validar o pacote contra o schema do formato, converter para imagem e recalcular planilha exigem ferramenta externa (conversor de escritório headless, rasterizador, validador com o bundle de schemas). Esta skill não instala nenhuma delas e não inventa substituto. Sem a ferramenta, mantenha a obrigação e marque o resultado: diga qual verificação não rodou, por falta de qual ferramenta, e registre o item como **não verificado** na saída, em vez de afirmar que o arquivo está válido. Validador que passa também não prova arquivo válido: ele não cobre tudo que o leitor do destinatário repara, então "passou no validador" entra como evidência do que ele checou, não como garantia de abertura.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# PDF
|
|
2
|
+
|
|
3
|
+
Leia ao gerar, preencher, extrair ou recortar PDF.
|
|
4
|
+
|
|
5
|
+
## Um sistema de coordenadas, declarado
|
|
6
|
+
|
|
7
|
+
No espaço de usuário do PDF a origem fica no **canto inferior esquerdo**: `y = 0` é a base da página e `y` cresce para cima; a unidade é o ponto, 72 por polegada. Esta skill afirma esse sistema e nenhum outro.
|
|
8
|
+
|
|
9
|
+
A confusão não vem do formato, vem das ferramentas: biblioteca de extração costuma devolver a distância **do topo** (campo com nome de topo), e imagem rasterizada tem origem no canto superior esquerdo com `y` crescendo para baixo. São três sistemas e nenhum conversor adivinha qual você usou. Então, sempre: declare em qual sistema cada número está antes de calcular, converta tudo para um só antes de escrever, e nunca some coordenada de extração com coordenada de desenho sem a conversão pela altura da página.
|
|
10
|
+
|
|
11
|
+
**Verifique em vez de confiar na memória**: desenhe uma marca numa coordenada pequena de `y`, renderize a página em imagem e olhe. Marca embaixo confirma origem na base; marca no topo diz que aquele número estava no sistema do topo e a conversão está faltando. Faça essa checagem uma vez por ferramenta nova e registre o resultado na saída — é uma linha de evidência observada, e sai de graça.
|
|
12
|
+
|
|
13
|
+
## Formulário
|
|
14
|
+
|
|
15
|
+
Se o PDF tem campos de formulário reais, preencha os campos: o valor fica editável, o leitor o renderiza com a fonte do campo e nada depende de posição. Só quando não há campo nenhum é que o preenchimento vira anotação posicionada, e aí a posição é o problema inteiro.
|
|
16
|
+
|
|
17
|
+
Para posicionar, prefira as coordenadas extraídas da estrutura do PDF (rótulos, linhas, quadrados de marcação) à estimativa visual; a estimativa é o último recurso, para página digitalizada sem camada de texto. Em qualquer dos dois casos, a posição só vale depois de renderizar a página preenchida e olhar: valor fora da linha, sobreposto ao rótulo ou cortado na borda é o defeito normal aqui, não a exceção. Misturar os dois caminhos na mesma página exige converter os estimados para o sistema dos extraídos antes de gravar.
|
|
18
|
+
|
|
19
|
+
## Extração
|
|
20
|
+
|
|
21
|
+
Página sem camada de texto não devolve texto: o resultado vazio é diagnóstico, não erro de código. Confirme se existe camada de texto antes de concluir que o documento está vazio, e se não existir, diga que o caminho é reconhecimento de caractere na imagem e trate o resultado como leitura aproximada, com a taxa de erro assumida, nunca como transcrição fiel.
|
|
22
|
+
|
|
23
|
+
Tabela extraída de PDF vem com célula mesclada desfeita, cabeçalho repetido por página e número colado à unidade. Confira o total contra a própria tabela antes de usar os valores, e relate a célula que você reconstruiu por inferência.
|
|
24
|
+
|
|
25
|
+
## Fonte e glifo
|
|
26
|
+
|
|
27
|
+
Caractere que a fonte embarcada não tem sai como caixa preta ou vazio, e isso aparece na renderização, não no código. Índice e expoente são o caso recorrente: resolva-os pela marcação de texto da biblioteca em vez de colar o caractere Unicode correspondente, e confira na imagem.
|
|
28
|
+
|
|
29
|
+
## Antes de entregar
|
|
30
|
+
|
|
31
|
+
Renderize e olhe cada página que você gerou ou alterou. PDF bonito não prova número nem decisão: a conferência dos valores é contra a fonte, não contra a aparência. Senha e permissão de documento, quando pedidas, são verificadas abrindo o arquivo resultante; declare o que não pôde ser verificado como **não verificado**, inclusive marcação de acessibilidade, que não se prova olhando a página.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Planilha
|
|
2
|
+
|
|
3
|
+
Leia ao criar ou editar planilha. O que distingue uma planilha entregue de um relatório com números é que ela recalcula: se o valor não se refaz quando a entrada muda, você entregou um texto em forma de grade.
|
|
4
|
+
|
|
5
|
+
## Fórmula, não resultado
|
|
6
|
+
|
|
7
|
+
Escreva a fórmula na célula, não o número que você calculou por fora. Total, média, projeção e rateio moram na célula como expressão sobre as células de entrada. Toda premissa fica na própria célula rotulada e é referenciada por quem a usa, em vez de aparecer como literal no meio de uma fórmula; fórmula igual em toda a série de períodos, porque célula editada sozinha no meio da linha é o erro silencioso mais comum; denominador que pode ser zero recebe guarda.
|
|
8
|
+
|
|
9
|
+
Documente premissa e número cravado onde o leitor vê — comentário na célula ou célula vizinha ao fim da tabela — e cite a fonte real quando houver; quando o número veio do dono, diga isso. Planilha que você cria para alguém preencher leva uma legenda curta dizendo quais células editar e uma linha de exemplo com valores realistas; arquivo que você foi chamado para editar não recebe linha de exemplo.
|
|
10
|
+
|
|
11
|
+
## Recálculo antes de entregar
|
|
12
|
+
|
|
13
|
+
Biblioteca de planilha grava a fórmula como texto e **não grava valor em cache**. Até recalcular, toda célula de fórmula lê como vazia para qualquer coisa que leia o cache: previsualizador, conversor, leitura por valor. Então: recalcule com o motor disponível, leia o relatório de erro que ele produz, corrija o que ele nomeia e recalcule de novo. Saída sem erro de execução não é o mesmo que saída sem erro de fórmula — leia o conteúdo do relatório, não o código de saída.
|
|
14
|
+
|
|
15
|
+
**Recálculo verde prova que a fórmula avalia, não que ela está certa.** Intervalo com um a mais ou referência à linha errada produzem arquivo limpo com número errado. Escreva duas ou três fórmulas primeiro, confira contra o valor que você espera, e só então monte a grade.
|
|
16
|
+
|
|
17
|
+
Erro que você introduziu é idêntico ao erro que você herdou. Antes de atribuir um erro ao arquivo original, abra o original e olhe aquela célula.
|
|
18
|
+
|
|
19
|
+
**Vínculo para outro arquivo se perde** quando a planilha é reescrita por biblioteca e recalculada: a referência aponta um arquivo separado que não está aqui, o valor em cache era a única coisa que sustentava o dado, a reescrita o remove e o recálculo deixa erro no lugar. Copie os valores dessas células antes de salvar sobre elas, ou não salve sobre elas.
|
|
20
|
+
|
|
21
|
+
## Função: limitação é da ferramenta e tem data
|
|
22
|
+
|
|
23
|
+
Não carregue lista fixa de função proibida. O que vale é: **a função que o motor de recálculo disponível não avalia vira erro gravado no arquivo que você entrega**, e isso é propriedade daquele motor naquela versão, não da linguagem de planilha. Antes de usar função recente, teste-a numa célula e recalcule; se o motor não a avaliar, troque pela composição equivalente (busca por índice e correspondência em vez de busca moderna, ordenação e deduplicação feitas antes de escrever as células) e registre na saída qual função o motor desta máquina não avaliou, com a data.
|
|
24
|
+
|
|
25
|
+
Dois casos merecem atenção porque não aparecem como erro: função de matriz que derrama em várias células precisa de metadado de derrame que a escrita por biblioteca não gera, então só a primeira célula recebe valor e o recálculo relata zero erro; e nome de função pós-2007 às vezes precisa do prefixo interno que a interface do leitor esconde, porque a biblioteca grava no XML exatamente o que você escreveu. Fórmula que o motor não conseguiu interpretar costuma voltar reescrita em caixa baixa — é o sinal de que o problema é de interpretação, não de dado.
|
|
26
|
+
|
|
27
|
+
## Editar arquivo existente
|
|
28
|
+
|
|
29
|
+
As convenções do arquivo vencem qualquer orientação geral: formato de número, nome de aba, cor, posição do cabeçalho. Ache primeiro as células de entrada designadas — cor de fonte, preenchimento ou sombreamento distintos as marcam — escreva só nelas e não toque nas fórmulas existentes. Ler o modelo exige duas passagens, uma pelos valores e outra pelas fórmulas: a passagem por valores não tem as fórmulas, e salvar a partir dela substitui cada fórmula do arquivo por um literal, de forma permanente.
|
|
30
|
+
|
|
31
|
+
Célula mesclada recebe escrita só na âncora. Planilha com macro perde as macros se for salva sem preservá-las explicitamente. Nome de aba com espaço precisa de aspas na referência entre abas, senão a fórmula erra.
|
|
32
|
+
|
|
33
|
+
## Entrada externa não vira fórmula
|
|
34
|
+
|
|
35
|
+
Texto que veio de fora e começa com `= + - @` é neutralizado antes de entrar na célula, e texto externo em HTML é escapado. Isso não é estética: é a diferença entre uma célula de dado e uma expressão que o leitor do destinatário executa.
|
|
@@ -21,6 +21,8 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
21
21
|
4. Mantenha o glossário livre de decisões de framework, SQL/DDL e schemas técnicos, diário de execução e especificação de endpoints. Em pedido misto, entregue só a parte de domínio e liste o resto como pendência com o responsável sugerido (`crow-postgres`, `crow-backend` ou `crow-architecture`).
|
|
22
22
|
5. Mostre desacordos entre regras ou entre regra declarada e comportamento atual; não escolha nem marque como recomendada a versão verdadeira: quem decide é o dono da regra.
|
|
23
23
|
|
|
24
|
+
- Leia [invariante-e-identidade.md](references/invariante-e-identidade.md) ao registrar regra, identidade ou estado: cada invariante nomeia onde é imposta ou é marcada não imposta, chave de identidade separada de atributo mutável, e transição inválida na tabela de estados. Nomear o ponto de imposição é apontar, não gerar a arquitetura.
|
|
25
|
+
|
|
24
26
|
## Saída e aceite
|
|
25
27
|
|
|
26
28
|
Entregue **domain-glossary** 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.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# invariante e identidade
|
|
2
|
+
|
|
3
|
+
Leia ao registrar invariantes, identidade e estados. Glossário que não vira regra verificável é prosa; o que entrega valor para desenho e teste é a invariante amarrada a onde ela é imposta.
|
|
4
|
+
|
|
5
|
+
Cada invariante nomeia onde é imposta, ou é marcada como não imposta. "Um pedido pago não volta a pendente" só serve se disser que isso é garantido por constraint no banco, por checagem na aplicação, ou por nada — e "por nada" é o achado mais importante, porque é a regra que o sistema diz ter e não tem. Nomear o ponto de imposição é apontar, não desenhá-lo: o desenho da constraint é de `crow-postgres`, a checagem de aplicação é de `crow-backend`. A skill liga a regra ao lugar e deixa a implementação para o dono.
|
|
6
|
+
|
|
7
|
+
Identidade é o que faz duas referências serem a mesma coisa. Diga qual é a chave de identidade de cada conceito (o que decide igualdade) e distinga identidade de atributo que muda: um usuário continua o mesmo ao trocar e-mail; dois registros com o mesmo e-mail podem ou não ser o mesmo usuário — o domínio decide, e a resposta vira regra. Separe também identidades que a prosa confunde: conta, usuário, membro e organização só viram termos distintos quando o domínio exige, mas aí a fronteira entre eles é explícita.
|
|
8
|
+
|
|
9
|
+
Estado e transição viram tabela verificável. Para cada estado de origem, diga quais transições são válidas e o que cada uma proíbe, aplicando cada transição inclusive ao próprio destino (cancelar o já cancelado, aprovar o já aprovado) e aos casos de borda: duplicidade, cancelamento parcial, concorrência, expiração, mudança de propriedade. A transição inválida que o sistema deve recusar é tão parte do registro quanto a válida.
|
|
10
|
+
|
|
11
|
+
Desacordo não é resolvido aqui. Quando duas regras conflitam, ou a regra declarada diverge do comportamento observado no código, mostre os dois lados com a fonte de cada um e não marque a verdadeira: quem decide é o dono da regra. Detalhe de implementação observado vai para a resposta, não para o glossário, que fica livre de framework, SQL, schema e especificação de endpoint.
|
|
@@ -16,10 +16,11 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
16
16
|
## Trabalho
|
|
17
17
|
|
|
18
18
|
1. Localize a rota e os estilos/componentes compartilhados afetados. Meça o alcance da alteração antes de mexer em tokens globais, registre-o na saída e prefira escopo local.
|
|
19
|
-
2. Implemente a menor composição que expresse os estados necessários. Use componentes compostos ou variantes explícitas quando flags booleanas estiverem multiplicando estados.
|
|
20
|
-
3. Valide dados externos nas bordas; tipos de compilação não substituem validação em runtime. Trate erro, carregamento, vazio, retry e cancelamento pertinentes.
|
|
21
|
-
4. Respeite a versão do framework; não aplique APIs de React 19 a React 18. Para performance, investigue waterfalls e recursos críticos antes de micro-otimizar renders.
|
|
22
|
-
5. Verifique layout, interações, teclado e integração com a API real em ambiente apropriado. Relate mocks usados e verificações não executadas.
|
|
19
|
+
2. Implemente a menor composição que expresse os estados necessários. Use componentes compostos ou variantes explícitas quando flags booleanas estiverem multiplicando estados. Estado que mais de um ramo da árvore precisa sobe para um provider com interface declarada (estado, ações, metadados) e a UI consome essa interface, não a implementação: irmão fora da subárvore lê e age por essa interface, sem prop drilling, sem sincronizar por efeito e sem ler de ref na hora do submit.
|
|
20
|
+
3. Valide dados externos nas bordas; tipos de compilação não substituem validação em runtime. Trate erro, carregamento, vazio, retry e cancelamento pertinentes. Derive durante o render o que dá para derivar: efeito que só copia prop para estado, ou que executa a lógica de uma interação, vira derivação ou handler do evento. Valor que só existe no cliente (hora local, locale, aleatório, leitura de storage) não pode divergir do HTML do servidor por acidente: resolva-o depois da hidratação ou marque como esperada apenas aquela divergência, no elemento dela; nunca silencie a divergência que é defeito.
|
|
21
|
+
4. Respeite a versão do framework; não aplique APIs de React 19 a React 18. Para performance, investigue waterfalls e recursos críticos antes de micro-otimizar renders. Com componentes de servidor, trate server action como endpoint público, com autenticação e autorização nela própria e não no componente que a chama; não guarde estado mutável de requisição em módulo, que é compartilhado entre requisições e entre usuários; e mande ao cliente só os campos que a UI usa, nunca o registro inteiro com segredo ou campo interno.
|
|
22
|
+
5. Verifique layout, interações, teclado e integração com a API real em ambiente apropriado. Relate mocks usados e verificações não executadas. A prontidão da verificação é asserção sobre o estado visível — o elemento que a jornada promete, com o conteúdo que ela promete; sinal de rede ociosa não é prontidão (a documentação do Playwright desencoraja esperar por ele) e espera por tempo fixo também não.
|
|
23
|
+
6. Exercite a jornada na menor largura suportada e nos pontos em que o layout muda, não só no desktop: overflow horizontal, alvo de toque, foco visível, e altura de viewport em mobile (`dvh`/`svh` no lugar de `100vh`, ou desconte a chrome persistente). Componente que aparece em contextos de largura diferente responde por container query, não por breakpoint global, e espaçamento e direção usam propriedades lógicas quando a interface tem outra direção de leitura. Campo de formulário leva `autocomplete`, tipo e teclado certos, e o erro aparece depois da interação, não a cada tecla.
|
|
23
24
|
|
|
24
25
|
Recursos da máquina: antes de subir dev server, build ou suíte, consulte `crow-skills resources --json` quando existir e respeite `maxParallelHeavyJobs` e use `maxWorkersPerJob` só para baixar os workers que o bundler ou o runner já usam (`--maxWorkers`); sob pressão `critical`, não inicie processo pesado novo. Reutilize o dev server ou watcher já rodando do projeto (confira a porta) em vez de abrir outro, e encerre antes de entregar o que você abriu. Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).
|
|
25
26
|
|
|
@@ -28,7 +29,7 @@ Recursos da máquina: antes de subir dev server, build ou suíte, consulte `crow
|
|
|
28
29
|
Entregue **ui-change** 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.
|
|
29
30
|
- 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.
|
|
30
31
|
- Critérios da jornada funcionam além do happy path.
|
|
31
|
-
- Nenhuma regressão compartilhada identificada foi ignorada; a evidência vem em três linhas: Funcional, Visual e Acessibilidade.
|
|
32
|
+
- Nenhuma regressão compartilhada identificada foi ignorada; a evidência vem em três linhas: Funcional, Visual e Acessibilidade. A linha Visual nomeia as larguras em que a jornada foi exercitada; largura não exercitada fica como não verificado.
|
|
32
33
|
|
|
33
34
|
## Limites e composição
|
|
34
35
|
|
|
@@ -19,7 +19,8 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
19
19
|
2. Confira origem, período, coorte e definição de receita, churn, CAC/LTV ou outra medida usada. Separe observado, estimado e desconhecido. Para taxas, mostre a série de períodos e a média, não um ponto isolado; confronte metas com essa linha de base e com restrições contratuais.
|
|
20
20
|
3. Compare alternativas com custo, valor ao cliente, risco e evidência. Use o mesmo denominador entre variantes. Não trate score de priorização como verdade nem misture ARR, caixa e receita reconhecida.
|
|
21
21
|
4. Proponha a menor mudança/experimento, guardrails e condição de manter, ajustar ou encerrar. Em experimento, diga se a diferença é distinguível de zero e compare amostra planejada com realizada. Para descontinuação, inclua dependentes, comunicação e migração.
|
|
22
|
-
5.
|
|
22
|
+
5. Leia [experimento e métrica](references/experimento-e-metrica.md) antes de desenhar o experimento, de afirmar ganho ou de avaliar mudança de preço: amostra e regra de parada fixadas antes do primeiro dado, resultado bom não encerra o teste, novidade e sazonalidade declaradas, média agregada aberta por coorte e segmento, métrica que um resultado ruim consegue derrubar, e referência de mercado só com fonte citada.
|
|
23
|
+
6. Entregue decisão recomendada e incertezas; uma hipótese de preço/canal não autoriza modificar cobrança, disparar campanha ou encerrar serviço.
|
|
23
24
|
|
|
24
25
|
## Saída e aceite
|
|
25
26
|
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# experimento e métrica
|
|
2
|
+
|
|
3
|
+
Leia ao desenhar experimento, ao ler métrica e ao avaliar mudança de preço. A promessa da skill é não inventar métrica; cumpri-la exige recusar também o número que existe mas não sustenta a conclusão.
|
|
4
|
+
|
|
5
|
+
## Antes de ligar o experimento
|
|
6
|
+
|
|
7
|
+
Fixe, por escrito e antes do primeiro dado: a métrica de resultado, a linha de base dela, o menor efeito que vale detectar, o tamanho de amostra por braço que esse efeito exige, a duração que a amostra implica no tráfego real e a regra de parada. Mudança pequena demais para o tráfego disponível não é testável — nesse caso diga isso e decida por outro caminho (evidência qualitativa, medir mais acima no fluxo, agrupar superfícies, ou não mudar), em vez de rodar um teste que não consegue responder.
|
|
8
|
+
|
|
9
|
+
Uma variável por braço. Mais de um braço exige mais amostra e multiplica as comparações; cada comparação extra aumenta a chance de um resultado parecer real por acaso, e isso precisa estar no desenho, não descoberto na leitura. Se a análise por segmento é parte do objetivo, a amostra é dimensionada pelo menor segmento, não pelo total.
|
|
10
|
+
|
|
11
|
+
## Parada
|
|
12
|
+
|
|
13
|
+
Olhar o resultado e encerrar quando ele está bom fabrica vencedor: a diferença flutua, e quem para no melhor momento escolhe a flutuação. Honre a amostra e a duração planejadas. A exceção é dano: guardrail claramente pior derruba o braço antes do fim, e isso é interrupção por segurança, não leitura de resultado.
|
|
14
|
+
|
|
15
|
+
Experimento que chegou ao fim está fechado. Estender um teste encerrado até a diferença virar significante é o mesmo erro com outra aparência; o que se faz com uma suspeita remanescente é um teste novo, declarado como novo.
|
|
16
|
+
|
|
17
|
+
Duração cobre o ciclo inteiro do negócio, não só a amostra: semana completa quando o comportamento varia por dia, ciclo de faturamento ou de compra quando ele manda no número. Teste muito curto captura novidade — mudança visível move o número só por ser diferente, e o efeito decai; teste muito longo acumula campanha, sazonalidade e release de outra pessoa dentro da janela. Diga em qual das duas pontas o seu está.
|
|
18
|
+
|
|
19
|
+
## Ler o resultado
|
|
20
|
+
|
|
21
|
+
Diferença distinguível de zero não é valor de negócio: reporte o tamanho do efeito e a faixa de incerteza junto, e decida com os dois. Inconclusivo não é "não tem efeito" — é faixa que ainda admite ganho e perda relevantes; diga qual faixa. Achado em segmento que não estava no plano é exploratório e vira hipótese para um teste próprio, nunca conclusão.
|
|
22
|
+
|
|
23
|
+
Sem grupo comparável não há efeito medido, só variação observada. Um antes e depois sem controle confunde a mudança com estação, campanha, release e composição de quem entrou no período; quando não há grupo comparável, diga que a comparação não é possível e nomeie o que a contamina.
|
|
24
|
+
|
|
25
|
+
## Métrica que decide alguma coisa
|
|
26
|
+
|
|
27
|
+
Escolha a medida que um resultado ruim consegue derrubar. Total acumulado, visitas, downloads e cadastros só sobem e por isso não distinguem decisão nenhuma; servem de contexto, não de resultado.
|
|
28
|
+
|
|
29
|
+
Média agregada esconde o que importa. Taxa estável no total pode ser coorte nova degradando enquanto a antiga sustenta o número; média por cliente que sobe pode ser perda dos clientes pequenos, não melhora de monetização. Mostre por coorte e por segmento antes de afirmar melhora, e diga qual composição mudou.
|
|
30
|
+
|
|
31
|
+
Contagem e valor não são a mesma perda: perder poucos clientes grandes é mais caro que perder muitos pequenos, e a decisão muda conforme você pondera por um ou por outro — diga por qual. Taxa periódica não se multiplica para virar anual, ela composta; converta pela composição, não por multiplicação. Separe receita bruta de líquida quando desconto, reembolso ou inadimplência mexem no número, e olhe concentração: faturamento preso em poucos contratos muda o risco de toda a conclusão.
|
|
32
|
+
|
|
33
|
+
Comparação com referência de mercado só entra com fonte citada. Faixa de referência sem fonte, meta de velocidade de experimento e proporção "ideal" repetida de memória não são evidência; se a conta é sua, mostre a fórmula, as premissas e a faixa, e rotule como estimada.
|
|
34
|
+
|
|
35
|
+
## Mudança de preço, pacote ou plano
|
|
36
|
+
|
|
37
|
+
Modele a perda junto com o ganho: queda de conversão, churn por segmento, efeito no tempo de retorno do custo de aquisição e receita de expansão que a mudança bloqueia. Projeção só com o lado bom não é análise.
|
|
38
|
+
|
|
39
|
+
Cliente existente é caso próprio: contrato vigente, aviso prévio e opção de manter a condição anterior entram como alternativa com custo, não como regra fixa, e a comunicação é ação pendente de quem decide. Preço do concorrente é um dado, não a decisão: estrutura de custo, valor entregue e base de clientes são outros. Hipótese de preço não autoriza alterar cobrança.
|
|
@@ -15,12 +15,13 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
15
15
|
|
|
16
16
|
## Trabalho
|
|
17
17
|
|
|
18
|
-
1. Confirme conta/tenant, região, ambiente, namespace e propriedade dos recursos; referencie o existente em vez de recriar ou assumir posse. Conta ou ambiente não confirmado é bloqueador; recurso de outro ambiente é declarado, não alterado.
|
|
19
|
-
2. Escolha a solução mais simples que cumpra disponibilidade, dados, escala, custo e operação. Use comparação de provedores só se houver decisão em aberto.
|
|
18
|
+
1. Confirme conta/tenant, região, ambiente, namespace e propriedade dos recursos; referencie o existente em vez de recriar ou assumir posse. Conta ou ambiente não confirmado é bloqueador; recurso de outro ambiente é declarado, não alterado. O inventário do existente é completo e identificado: tipo, identificador real, região, topologia (rede, sub-rede, endpoint privado, identidade) e a configuração que o novo recurso vai assumir (tier/tamanho, versão, exposição pública, criptografia). Para cada item declare o papel — referenciado e integrado, mantido fora de escopo, ou irrelevante. Recurso que já existe é referenciado; redeclará-lo como novo é o caminho mais curto para duplicar ou tomar posse do que é de outro dono.
|
|
19
|
+
2. Escolha a solução mais simples que cumpra disponibilidade, dados, escala, custo e operação. Use comparação de provedores só se houver decisão em aberto. Confirme capacidade antes de fechar o desenho: cota consumida contra o limite na região alvo, se o limite é ajustável e qual o prazo do pedido, e combinações de tamanho, tier e região que o provedor não aceita. Cota ou disponibilidade regional ausente é bloqueador de desenho, não erro a descobrir no apply; limite que a consulta não reporta é desconhecido, não infinito.
|
|
20
20
|
3. Descreva ou produza IaC no padrão existente, separando plano de apply. Mostre recursos afetados e mudanças de identidade, exposição ou dados. Corrija só o defeito; recursos, variáveis ou testes novos entram como proposta. Credencial fixa sai para variável ou perfil e vai a `crow-secrets`.
|
|
21
|
-
4.
|
|
22
|
-
5.
|
|
23
|
-
6.
|
|
21
|
+
4. Compare o declarado com o real antes de alterar. Recurso mudado fora do IaC faz o apply reverter configuração que alguém colocou de propósito, ou destruir o que o template não conhece. Divergência encontrada é relatada com os dois lados, qual deles está certo e quem decide, nunca normalizada em silêncio pelo apply. Onde um controlador reconcilia o estado, mudança aplicada à mão é desvio que ele desfaz ou remove: a alteração entra pela fonte que o controlador lê.
|
|
22
|
+
5. Valide syntax/schema, configurações e políticas com ferramentas compatíveis; sem a ferramenta, declare não validado, e plan simulado não é evidência. Para K8s leia o checklist condicional; para VM/serverless use os critérios do provedor e repo.
|
|
23
|
+
6. Antes de mutar, revise diff/plan e riscos de substituição/destroy. Modo de apply que apaga por omissão (sincronizar estado completo, prune, substituir conjunto) remove o que não está no template, inclusive recurso de outro dono: prefira o modo aditivo e, se o diff propõe destruir ou substituir recurso referenciado, pare e relate em vez de aplicar. Propriedade imutável depois de criada (zona, redundância, rede, nome, criptografia) só muda recriando o recurso: diga isso antes, com o efeito sobre dados e indisponibilidade. Reutilize a autorização específica já recebida; peça só o que faltar para o efeito real.
|
|
24
|
+
7. Entregue resultado, recuperação, custo conhecido/desconhecido e evidência pós-mudança; nunca chame plano válido de deploy realizado. Postura declarada não é postura configurada: redundância de zona, probe de saúde, backup e failover entre regiões são lidos do recurso no ar, com o comando que leu, não do que o desenho pretendia.
|
|
24
25
|
|
|
25
26
|
Recursos da máquina: validações locais pesadas (cluster local, containers, plan de muitos módulos) rodam uma por vez, com paralelismo reduzido (`terraform plan -parallelism=N`, abaixo do padrão 10, nunca acima) por `crow-skills resources --json` quando existir. Derrube clusters e containers locais que você criou. Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).
|
|
26
27
|
|
|
@@ -1,3 +1,9 @@
|
|
|
1
1
|
# kubernetes
|
|
2
2
|
|
|
3
3
|
Leia apenas para workload Kubernetes confirmado. Fixe versão/distribuição, namespace, CNI e método (Helm/Kustomize/YAML/GitOps). Cheque selector/label/ports, probes, requests/limits, PDB/rollout, securityContext, ServiceAccount/RBAC, NetworkPolicy e storage. Valide manifests renderizados contra schema e políticas da versão alvo, com dry-run/diff quando autorizado. AKS Automatic tem constraints de produto que precisam de fonte atual; não confunda readiness read-only com provisionamento ou apply. Não colete valores de Secrets. Operação com estado exige caminho de backup/restauração, não só rollout undo.
|
|
4
|
+
|
|
5
|
+
Fixe também o nível de admissão em vigor (Pod Security Admission, Kyverno, OPA/Gatekeeper): manifest válido contra o schema ainda é recusado ou mutado na admissão, e descobrir isso no apply é tarde. Imagem referenciada por tag móvel faz o rollout entregar conteúdo diferente a cada réplica e impede voltar à versão anterior: use digest ou tag imutável, e a identidade do artefato é a mesma que a do release.
|
|
6
|
+
|
|
7
|
+
Rollout com probe correta ainda derruba requisição se o pod para de aceitar conexão antes de sair dos endpoints do Service: reserve a janela de drenagem no desligamento e dê ao prazo de término folga sobre ela mais o tempo de esvaziar conexão longa. Prontidão se prova por asserção sobre o estado real do rollout e pela jornada respondendo, não por espera de tempo fixo nem por porta aberta.
|
|
8
|
+
|
|
9
|
+
Onde um controlador GitOps é o dono do cluster, ele reconcilia: `kubectl apply` à mão volta atrás no próximo ciclo, e recurso removido da fonte é apagado se a poda estiver ligada. Mude pela fonte que ele lê e confira a sincronização, em vez de aplicar direto. Identidade do pod para API de nuvem é vínculo entre ServiceAccount e identidade do provedor: sem esse vínculo a falha aparece como permissão negada em runtime, não como erro de manifest.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: crow-interface
|
|
3
|
-
description: "
|
|
3
|
+
description: "Use quando há interface web ou nativa para construir, revisar, criticar, auditar, refinar ou explorar em variantes interativas, com brief pronto ou sem brief. Não é para fixar do zero o contrato visual que ainda não existe, que é de crow-design, nem para implementar backend ou integração de dados da aplicação, que é de crow-frontend: crow-design decide, esta constrói e julga o construído."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Experiência de interface
|
|
@@ -265,6 +265,14 @@ body {
|
|
|
265
265
|
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
|
|
266
266
|
```
|
|
267
267
|
|
|
268
|
+
Never cap `maximum-scale` or set `user-scalable=no`: blocking pinch zoom removes the magnification some people depend on, and no layout problem justifies it.
|
|
269
|
+
|
|
270
|
+
#### Full-height sections: `vh` lies on mobile
|
|
271
|
+
|
|
272
|
+
`100vh` is the viewport with the browser chrome retracted, so a section sized that way is taller than what the user sees and jumps as the toolbar shows and hides while scrolling. Size full-height sections with `100dvh` for a region that should track the chrome, or `100svh` for one that must fit with the chrome visible, keeping `100vh` only as the fallback declaration before it.
|
|
273
|
+
|
|
274
|
+
Persistent UI inside the page counts against the same budget. A sticky header stacked in normal flow above a `100dvh` hero makes the first screen taller than the viewport: subtract the chrome (`calc(100dvh - var(--header-height))`) or overlay the header instead of stacking it. Verify this at the real viewport, not at the emulated one alone — the toolbar's behavior is what breaks it.
|
|
275
|
+
|
|
268
276
|
#### Responsive Images: Get It Right
|
|
269
277
|
|
|
270
278
|
##### srcset with Width Descriptors
|
|
@@ -56,7 +56,10 @@ Choose the simplest structural model that expresses those relationships. Use lay
|
|
|
56
56
|
- Use `gap` for sibling rhythm when it expresses the relationship more directly than child margins.
|
|
57
57
|
- Keep touch targets usable even when their visible marks are small.
|
|
58
58
|
- Use depth only when it clarifies state or hierarchy.
|
|
59
|
-
- Make optical corrections only after inspecting the rendered result.
|
|
59
|
+
- Make optical corrections only after inspecting the rendered result. Mathematical centering is not optical centering: an icon beside a label, a glyph inside a circle, and text inside a control usually need a correction of a pixel or two to read as aligned.
|
|
60
|
+
- Align the shared parts of a repeated set. When cards, pricing columns, or comparison panels sit side by side, their titles, their supporting text, the start of their lists, and their actions land on the same lines, whatever the content length above. Variable content that scatters those lines reads as broken even when every card is individually correct; fix it with a shared track or a reserved block, not by truncating the content.
|
|
61
|
+
- Settle full-height and full-bleed as decisions, not inheritance. A hero meant to run edge to edge must not inherit the page gutter or the shared max-width container; constrain only its inner text column. Size full-height regions per [adapt.md](adapt.md)'s viewport-unit section rather than `100vh`.
|
|
62
|
+
- Read the cascade after moving spacing. Section- and element-level selectors of similar specificity cancel each other most often on padding and margin, so the rule you wrote may not be the rule that applies. Confirm from the computed value, not from the stylesheet.
|
|
60
63
|
|
|
61
64
|
Variation is not a goal by itself. Repetition should support recognition; break it only when content or priority changes.
|
|
62
65
|
|
|
@@ -34,6 +34,8 @@ Em mundo novo, a direção aprovada é o contexto dos comps antes do código. DE
|
|
|
34
34
|
|
|
35
35
|
Registre alvo, revisão/fingerprint quando possível, modo, configuração, método, resultado e limites. Um teste não executado é pendente. Scan limpo não prova design, screenshot não prova gesto, teste web não prova native e ausência de erro não prova interação correta.
|
|
36
36
|
|
|
37
|
+
Captura visual só vale se a tela estava pronta, e prontidão é asserção sobre o estado visível: o elemento que a inspeção vai julgar existe, as fontes do sistema visual já resolveram, as imagens da região decodificaram e nada está em transição. Sinal de rede ociosa não é prontidão — a documentação do Playwright desencoraja usá-lo para isso — e espera por tempo fixo também não: ela passa na máquina rápida, falha na carregada, e o número que funcionou não é o do próximo ambiente. Captura feita antes disso mede fonte de fallback, imagem faltando e layout no meio do caminho, e o achado que ela produz é inventado. Declare em que viewport, escala e tema a captura foi feita, e trate evidência inválida como recapture, não como defeito do build.
|
|
38
|
+
|
|
37
39
|
Assessment de design vem antes de expor achados mecânicos ao julgador. Use agentes independentes quando disponíveis e autorizados pelas instruções aplicáveis; não invente APIs, nomes de agente ou requisito universal de perguntar. Leia a definição de papel fornecida em `agents/` e passe um pacote autocontido usando a API real. Quando indisponível, use o papel correspondente em `reference/degraded/`, sequencialmente, declarando a perda de independência.
|
|
38
40
|
|
|
39
41
|
Agrupe capturas por rodada. O budget ordinário de acabamento tem inspeção, lote de correções e confirmação; não é proibição de um pré-scan e pós-scan úteis numa mudança tipográfica/espacial. Reutilize scans válidos do mesmo fingerprint/configuração. Alterações invalidam somente a evidência afetada. Handoff automático para polish não inicia nova caça após critérios resolvidos; transmita pendências específicas.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: crow-media
|
|
3
|
-
description: "
|
|
3
|
+
description: "Use quando o entregável é um arquivo de imagem, áudio ou vídeo a criar ou editar a partir de brief e assets autorizados, e quando o resultado precisa ser medido antes de ser entregue. Entra também para diagnosticar perda de qualidade, dessincronismo, legenda ausente ou arquivo que não abre no destino. Não exige fornecedor, modelo ou CLI específico, não produz o documento que a mídia ilustra, que é de crow-documents, e não decide a direção visual, que é de crow-design."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Artefatos de imagem, áudio e vídeo
|
|
@@ -16,10 +16,10 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
16
16
|
## Trabalho
|
|
17
17
|
|
|
18
18
|
1. Reutilize o brief e materiais válidos. Meça as fontes (ex.: `ffprobe`) antes de fixar especificações; se o brief contradiz as fontes, entregue opções rotuladas. Diferencie edição de criação e fixe duração/dimensões/fps/áudio quando necessários ao destino.
|
|
19
|
-
2. Escolha a ferramenta disponível apropriada; preflight de CLI/provider não autoriza atualizar pacotes, usar credenciais de outro tenant ou enviar conteúdo sensível.
|
|
20
|
-
3. Para vídeo composto, use uma fonte de storyboard/script e tokens. Resolva assets com proveniência; para cada asset de terceiros registre licença, compatibilidade com o uso e texto de atribuição. Não faça vários especialistas reinventarem a narrativa.
|
|
21
|
-
4. Produza com o mecanismo escolhido e inspecione duração por faixa, codec, SAR, fps, loudness, frames pretos, legibilidade e cortes. Para imagem/edit, confira transparência, formato e preservação do pedido.
|
|
22
|
-
5. Valide o arquivo final e sua entrega/download. Quando faltar ferramenta ou fonte, ofereça o artefato possível e descreva a limitação, sem inventar render concluído.
|
|
19
|
+
2. Escolha a ferramenta disponível apropriada; preflight de CLI/provider não autoriza atualizar pacotes, usar credenciais de outro tenant ou enviar conteúdo sensível. Nunca escreva sobre a fonte: saída em arquivo novo. Decida o caminho inteiro antes e recodifique uma vez — cada geração em codec com perda degrada e a perda acumula; operação que não muda pixel nem amostra copia o stream. Leia as [regras de produção](references/producao.md) para as armadilhas de corte em keyframe, concatenação, cadeia de áudio, cor e mídia longa.
|
|
20
|
+
3. Para vídeo composto, use uma fonte de storyboard/script e tokens. Resolva assets com proveniência; para cada asset de terceiros registre licença, compatibilidade com o uso e texto de atribuição, e para cada asset derivado registre de qual arquivo e comando ele saiu. Referência de direção encontrada numa busca não é asset autorizado. Não faça vários especialistas reinventarem a narrativa.
|
|
21
|
+
4. Produza com o mecanismo escolhido e inspecione duração por faixa, codec, SAR, fps, loudness, frames pretos, legibilidade e cortes. Para imagem/edit, confira transparência, perfil de cor, formato e preservação do pedido. Correção de cor se mede e se propõe com antes e depois; aplicá-la por padrão destrói intenção cromática da cena.
|
|
22
|
+
5. Valide o arquivo final e sua entrega/download, nomeando cada saída por caminho completo mais os companheiros. Mídia longa se segmenta e se remonta: saída truncada por limite da ferramenta volta sem erro, e entregá-la como completa é afirmação falsa. Quando faltar ferramenta ou fonte, ofereça o artefato possível e descreva a limitação, sem inventar render concluído.
|
|
23
23
|
|
|
24
24
|
Recursos da máquina: render e transcodificação são jobs pesados: um por vez, salvo recomendação maior de `crow-skills resources --json` quando existir, com threads do encoder limitadas (`ffmpeg -threads N`) pelo `maxWorkersPerJob`. Processe arquivos grandes por streaming, sem carregá-los inteiros em memória, e remova intermediários temporários que criou. Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).
|
|
25
25
|
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Produção de mídia: fonte preservada, operação medida, arquivo final conferido
|
|
2
|
+
|
|
3
|
+
Leia antes de transformar um arquivo que você não gerou e antes de afirmar que um render ficou pronto. As armadilhas aqui custam qualidade que não volta.
|
|
4
|
+
|
|
5
|
+
## A fonte é irrecuperável; trate-a como tal
|
|
6
|
+
|
|
7
|
+
- **Nunca escreva sobre a fonte.** Saída em arquivo novo, fonte intocada, inclusive em "ajuste rápido". Pipeline que sobrescreve perde o único original que existia.
|
|
8
|
+
- **Meça antes de especificar.** Duração, resolução, SAR/DAR, fps e modo (constante ou variável), codec e perfil, profundidade de bits, espaço de cor, canais e taxa de amostragem do áudio, loudness. Especificação escrita sem medir a fonte produz destino que a fonte não alcança.
|
|
9
|
+
- **Cada recodificação perde.** Toda geração em codec com perda degrada, e a perda acumula: cortar, depois recortar, depois concatenar em três passos recodificando dá três gerações. Decida o caminho inteiro antes e recodifique uma vez, no fim.
|
|
10
|
+
- **Operação que não muda pixel nem amostra não recodifica.** Corte, concatenação e troca de container copiam o stream. Recodifique só quando a operação exige: mudar resolução, aspecto, fps, codec, ou aplicar efeito.
|
|
11
|
+
- **Upscale não cria informação.** Ampliar e depois entregar como se fosse captura nativa é alegação falsa sobre o arquivo. Declare o que foi ampliado e a partir de quê.
|
|
12
|
+
|
|
13
|
+
## Armadilhas da operação sem recodificação
|
|
14
|
+
|
|
15
|
+
- **Corte com cópia de stream só acerta em keyframe.** O ponto de entrada vai para o keyframe anterior, então o corte pedido e o corte obtido divergem — às vezes por segundos. Se o ponto exato importa, recodifique o trecho; se não importa, cole o ponto obtido no relato em vez de repetir o pedido.
|
|
16
|
+
- **Concatenação com cópia exige parâmetros idênticos.** Mesmo codec, perfil, resolução, fps, e mesmo layout de áudio. Fontes diferentes concatenadas assim produzem arquivo que abre e falha no meio, ou que dessincroniza. Normalize antes, ou recodifique na junção.
|
|
17
|
+
- **Container esconde o problema.** Arquivo que o player local abre pode falhar no destino: perfil de codec não suportado, fps variável, áudio em canal inesperado. Teste no destino real, não só no player do sistema.
|
|
18
|
+
- **Corte não destrutivo quando existir.** Em composição, página ou timeline, recortar por janela de reprodução ou máscara no render mantém a fonte inteira e reversível. Produzir arquivo físico só quando a entrega é o arquivo.
|
|
19
|
+
|
|
20
|
+
## Áudio
|
|
21
|
+
|
|
22
|
+
- **Ordem da cadeia importa.** Subtraia antes de somar: filtro corretivo primeiro, nível depois, relação entre faixas depois, caráter e teto no fim. Compressor antes de um corte de graves passa o tempo perseguindo ruído de fundo.
|
|
23
|
+
- **Não se diagnostica o espectro absoluto de uma voz desconhecida.** Fundamental, formante e queda natural no fim da frase variam mais entre duas pessoas do que a maioria dos defeitos. Compare sempre dentro do próprio arquivo: contra o original limpo, se existir, ou contra as pausas — o que se ouve numa pausa é aditivo, e o espectro da pausa é o canal, não a voz. Comparar com média publicada ou com voz sintetizada de controle produz diagnóstico errado. Sem original e sem silêncio utilizável, um defeito tonal estático é indeterminado: diga isso e ofereça as leituras compatíveis, em vez de escolher uma e construir uma cadeia sobre ela.
|
|
24
|
+
- **Música sob voz não se resolve baixando a música.** Abaixar a cama inteira funciona e custa toda a presença dela durante a locução. Ceda à voz as faixas de frequência que ela ocupa e devolva o resto, e faça a cessão seguir o envelope da fala, não uma profundidade fixa — profundidade fixa afina a música também nas pausas.
|
|
25
|
+
- **O processamento vai na faixa que cede, apontando para a que manda.** Faixa processada contra si mesma é defeito, não escolha sutil. Quando há várias falas, aponte para o grupo delas, não para cada clipe: lista de clipes precisa estar exaustivamente certa e envelhece na próxima edição.
|
|
26
|
+
- **Efeito com cauda alonga a faixa.** Reverb e delay fazem o resultado terminar depois da duração nominal. Isso é esperado; reserve a cauda na mixagem em vez de cortá-la.
|
|
27
|
+
- **Mixagem se confere ouvindo o render, não lendo o grafo.** E o que não dá para conferir entra como não verificado.
|
|
28
|
+
|
|
29
|
+
## Imagem, cor e tratamento
|
|
30
|
+
|
|
31
|
+
- **Correção se mede e se propõe, não se aplica em silêncio.** Medir exposição, balanço e contraste é evidência; aplicá-los por padrão não é. Uma "correção" que puxa a cena para cinza neutro destrói pôr do sol, neon e qualquer intenção cromática. Mostre a medida e a proposta, com antes e depois, e deixe a decisão com o dono.
|
|
32
|
+
- **Não suba o nível de representação sem necessidade.** Ajuste paramétrico reversível resolve exposição, sombras, contraste e temperatura. Congelar isso numa tabela de cor ou num bitmap achatado é irreversível e some com o parâmetro; use a forma pesada só quando o pedido a exige ou quando o dono forneceu o arquivo.
|
|
33
|
+
- **Transparência e espaço de cor sobrevivem à conversão ou não.** Confira canal alfa, perfil de cor e matiz depois de cada conversão de formato; alfa perdido só aparece sobre fundo diferente do que você testou.
|
|
34
|
+
- **Formato e tamanho casam com o destino.** Entregar no dobro da dimensão de exibição desperdiça, e abaixo dela borra. Nome de arquivo descreve o conteúdo.
|
|
35
|
+
- **Máscara geométrica não substitui recorte real.** Círculo, polígono ou gradiente aproximando a silhueta de um objeto fotográfico lê pior que não recortar.
|
|
36
|
+
|
|
37
|
+
## Vídeo composto
|
|
38
|
+
|
|
39
|
+
Uma fonte de verdade para roteiro e storyboard, e tokens para o visual. Não deixe vários especialistas reinventarem a narrativa: quem produz a cena lê o roteiro aprovado, não o reescreve.
|
|
40
|
+
|
|
41
|
+
Antes de concluir, inspecione: duração por faixa e total, sincronismo de áudio e imagem no começo e no fim, fps e codec do arquivo entregue, loudness, frames pretos ou congelados no corte, legibilidade do texto na menor tela do destino, legenda sincronizada quando houver fala, e área segura. Frame preto no fim e dessincronismo progressivo são os dois defeitos que passam em inspeção por amostragem.
|
|
42
|
+
|
|
43
|
+
## Mídia longa e saída truncada
|
|
44
|
+
|
|
45
|
+
Transcrição, análise e descrição de arquivo longo batem em limite de saída da ferramenta e voltam cortadas sem erro. Segmente a entrada, processe por partes com sobreposição nas bordas, remonte e confira que a última fala do arquivo está no resultado. Entregar transcrição truncada como completa é afirmação falsa sobre o arquivo, e é silenciosa.
|
|
46
|
+
|
|
47
|
+
Arquivo grande se processa por streaming, não carregado inteiro em memória. Pré-dimensione quando a ferramenta tem limite de tamanho, e diga que a entrada foi reduzida.
|
|
48
|
+
|
|
49
|
+
## Diagrama e artefato revisável
|
|
50
|
+
|
|
51
|
+
Quando o artefato precisa ser revisado, versionado e corrigido, a fonte em texto (Mermaid, DOT, PlantUML, SVG escrito) vale mais que o bitmap: ela entra em diff e a correção é cirúrgica. Renderize para imagem ou PDF quando o pedido é o arquivo, ou quando o destino não lê a fonte. Entregue a fonte junto do render e diga as suposições que você fez sobre entidades, relações e ordem.
|
|
52
|
+
|
|
53
|
+
## Proveniência e direitos
|
|
54
|
+
|
|
55
|
+
- **Cada asset de terceiro registra origem, licença, compatibilidade com o uso e o texto de atribuição exigido.** Imagem encontrada numa busca, pin, feed ou banco de referências não é asset autorizado: ela pode servir como referência de direção e não entra no entregável.
|
|
56
|
+
- **Asset derivado aponta para a fonte.** Recorte, upscale, grade e conversão registram de qual arquivo saíram e com qual comando; sem isso ninguém reproduz nem reverte.
|
|
57
|
+
- **Voz, rosto e identidade de pessoa real exigem consentimento explícito e registrado**, por uso e por peça.
|
|
58
|
+
- **Fonte tipográfica tem licença própria.** Índice de fontes e nome de família não autorizam embutir o arquivo.
|
|
59
|
+
- **Não exija fornecedor.** Escolha entre as ferramentas presentes. Quando o pedido só é alcançável com serviço externo, credencial ou instalação nova, diga o que falta, entregue o artefato possível e pare — não instale, não atualize pacote, não use credencial de outro contexto e não envie conteúdo sensível para um serviço só para completar o preflight.
|
|
60
|
+
|
|
61
|
+
## Entrega
|
|
62
|
+
|
|
63
|
+
O relato nomeia cada arquivo final por caminho completo e aberto a partir da raiz do projeto, mais os companheiros (transcrição, manifest, miniatura, derivado otimizado). Nome de arquivo solto não é entrega. Diga o comando que mediu o resultado e o que ele mostrou; "renderizou" sem medida não é evidência, e render que não terminou não se relata como concluído.
|
|
@@ -19,7 +19,7 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
19
19
|
2. Implemente o fluxo e estados com trabalho pesado fora da thread de UI e cancelamento/teardown corretos. Não suponha que background execute indefinidamente. Arquivos e trabalhos têm nome único, limpeza e falha com retry limitado.
|
|
20
20
|
3. Trate permissões como escolha do usuário: solicite no momento pertinente ao recurso, respeite negativa e indique retomada explícita; não abra prompts em loop. Isole a decisão de permissão em lógica testável sem dispositivo, cobrindo concedida, negada, negada de vez e revogada depois de concedida.
|
|
21
21
|
4. Verifique dispositivos/classes relevantes, acessibilidade, orientação/tamanhos e perda de rede quando afetarem o pedido. Teste API e persistência como contratos distintos. Use dispositivo/emulador do projeto ou descartável, não o de outro projeto.
|
|
22
|
-
5. Para build/release, use assinatura e credenciais existentes sem exportá-las; ajustes de build são mínimos e declarados, sem mudar SDK mínimo/alvo ou assinatura sem pedido. Para performance, encaminhe medição à disciplina de validade.
|
|
22
|
+
5. Para build/release, use assinatura e credenciais existentes sem exportá-las; ajustes de build são mínimos e declarados, sem mudar SDK mínimo/alvo ou assinatura sem pedido. Compilar não prova assinatura: um build que compila ainda falha em assinatura, provisioning e entitlements (no iOS, Archive é sinal distinto de Build, e é ele que libera TestFlight e loja). Para release, confirme o artefato assinado no canal real de distribuição, não só a compilação local ou de CI. Para performance, encaminhe medição à disciplina de validade.
|
|
23
23
|
|
|
24
24
|
Recursos da máquina: um emulador ou simulador por vez, reutilizando o já aberto do projeto; builds Gradle/Xcode com workers reduzidos (`--max-workers`, `-jobs`; por padrão usam todas as CPUs) pelo `maxWorkersPerJob` de `crow-skills resources --json` quando existir. Sob pressão `critical`, não inicie emulador nem build. Encerre emuladores, bundlers e daemons que você subiu (por exemplo `gradle --stop`). Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).
|
|
25
25
|
|
|
@@ -16,10 +16,14 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
16
16
|
## Trabalho
|
|
17
17
|
|
|
18
18
|
1. Defina qual pergunta o sinal deve responder e quem age. Reutilize o provedor existente antes de adicionar SDK ou coletor.
|
|
19
|
-
2. Associe ambiente/release e correlação mínima: propague o ID recebido (ex.: `traceparent` W3C), saneando em vez de descartar. Redija segredos e minimize dados pessoais, preservando IDs operacionais não pessoais. Controle cardinalidade, volume e retenção.
|
|
20
|
-
3. Instrumentar não muda contrato HTTP, validação de entrada nem nomes de alerta/métrica existentes; se for preciso, deixe como proposta (mudança de contrato), salvo pedido explícito. Escolha sinais ligados à experiência: falhas de jornada, latência/filas, saturação e dependências. Diferencie alerta acionável de dashboard informativo.
|
|
21
|
-
4. Verifique captura e roteamento com evento seguro e esperado. Não dispare incidente real nem use dados pessoais para testar.
|
|
22
|
-
5. Entregue alerta/runbook com limiar, responsável, diagnóstico inicial e rollback. Ajuste ruído a partir de evidência observada.
|
|
19
|
+
2. Associe ambiente/release e correlação mínima: propague o ID recebido (ex.: `traceparent` W3C), saneando em vez de descartar. Redija segredos e minimize dados pessoais, preservando IDs operacionais não pessoais. Controle cardinalidade, volume e retenção. Quando o mesmo sinal sai por mais de um destino (span, log, bucket, armazém de dados), a redação vale por destino: desligar conteúdo no trace não desliga o que já é exportado por outro caminho, e cada destino precisa da própria prova. Separe o destino por ambiente: evento de desenvolvimento ou homologação no projeto de produção gasta cota e aciona plantão por engano. Se a leitura do sinal depende de artefato de build (source map, símbolos), publicá-lo faz parte do release ou a pilha chega ilegível.
|
|
20
|
+
3. Instrumentar não muda contrato HTTP, validação de entrada nem nomes de alerta/métrica existentes; se for preciso, deixe como proposta (mudança de contrato), salvo pedido explícito. Escolha sinais ligados à experiência: falhas de jornada, latência/filas, saturação e dependências. Cubra também o caminho de erro não tratado: exceção sem captura, rejeição assíncrona, falha na fronteira do componente de interface e requisição que volta com erro. Código que engole o erro antes do coletor faz o sistema parecer saudável; trate isso como defeito do sinal, com arquivo:linha. Diferencie alerta acionável de dashboard informativo.
|
|
21
|
+
4. Verifique captura e roteamento com evento seguro e esperado. Não dispare incidente real nem use dados pessoais para testar. Ausência de evento não é ausência de falha: coletor que não subiu, identidade sem permissão de escrita no destino, amostragem agressiva ou filtro amplo produzem painel vazio. Prove o caminho ponta a ponta até o destino final e confirme release, ambiente e campos esperados no evento que chegou; sem isso, o sinal é não verificado. Instrumentação nova não pode substituir nem silenciar a existente: depois de instalar, confira que os sinais anteriores continuam chegando.
|
|
22
|
+
5. Entregue alerta/runbook com limiar, responsável, diagnóstico inicial e rollback. Todo alerta nasce ligado a um runbook e a um sinal de usuário; alerta sem ação definida sai, em vez de ser silenciado aos poucos até ninguém olhar. O limiar vem do comportamento medido do serviço e é datado, não de número de catálogo. Agrupe eventos repetidos do mesmo incidente, e trate reabertura de problema já corrigido como alerta próprio. Ajuste ruído a partir de evidência observada.
|
|
23
|
+
|
|
24
|
+
## Detalhes condicionais
|
|
25
|
+
|
|
26
|
+
- Leia [cardinalidade.md](references/cardinalidade.md) ao criar ou alterar métrica, rótulo ou campo indexado.
|
|
23
27
|
|
|
24
28
|
## Saída e aceite
|
|
25
29
|
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# cardinalidade
|
|
2
|
+
|
|
3
|
+
Leia ao criar ou alterar métrica, rótulo ou campo indexado.
|
|
4
|
+
|
|
5
|
+
Cada combinação distinta de valores de rótulo é uma série temporal própria. Rótulo que carrega identificador de usuário, de requisição, de sessão, de pedido, URL crua com parâmetro, mensagem de erro ou endereço de origem multiplica as séries pelo tamanho do tráfego: o custo de ingestão e retenção cresce junto e o backend de métricas cai antes de o painel ficar pronto. A falha aparece como ingestão rejeitada, consulta que expira ou fatura fora de proporção, nunca como erro no código que instrumentou.
|
|
6
|
+
|
|
7
|
+
Antes de instrumentar, escreva o conjunto de valores possíveis de cada rótulo e confirme que ele é fechado e pequeno: ambiente, release, região, serviço, rota normalizada (o padrão da rota, não o caminho com o id dentro), código de status, resultado. Dado de variação alta pertence a log estruturado ou a atributo de trace, onde a busca é por evento e não por série, e o identificador que liga os dois é o de correlação.
|
|
8
|
+
|
|
9
|
+
Conteúdo de payload no sinal — corpo de requisição, prompt, resposta, documento — multiplica custo e risco ao mesmo tempo: capture amostra com taxa declarada, redija antes de sair do processo e informe a retenção. Amostragem é parte do contrato do sinal: diga a taxa na saída, porque ela muda o que o alerta consegue detectar.
|
|
10
|
+
|
|
11
|
+
Ao reduzir cardinalidade de uma métrica existente, o histórico não se converte: a série antiga morre e a nova começa vazia. Isso quebra alerta e painel que dependiam dela. Declare a mudança, o período sem comparação possível e quem precisa saber, em vez de trocar o rótulo em silêncio.
|
|
@@ -15,12 +15,12 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
15
15
|
|
|
16
16
|
## Trabalho
|
|
17
17
|
|
|
18
|
-
1. Diferencie avaliar evidência, medir e otimizar. Avaliação não autoriza medir/alterar/reverter; use só os dados disponíveis e proponha o experimento que falta. Nos modos executáveis autorizados, fixe workload, cache/warmup, concorrência e instrumento e estime o ruído no sistema inalterado.
|
|
19
|
-
2. Use profiler/trace/plano para localizar custo; isso não mede por si o ganho de uma correção. Web: rede/render/bundle; serviço: filas/spans/carga; Postgres: plano/locks/pool; nativo: threads/alocações/lifecycle. Escolha só o ramo pertinente.
|
|
20
|
-
3. Faça a menor alteração testável. Confirme que o mecanismo proposto realmente entrou em efeito.
|
|
18
|
+
1. Diferencie avaliar evidência, medir e otimizar. Avaliação não autoriza medir/alterar/reverter; use só os dados disponíveis e proponha o experimento que falta. Nos modos executáveis autorizados, fixe workload, cache/warmup, concorrência e instrumento e estime o ruído no sistema inalterado. Ruído maior que o efeito esperado é bloqueador de medição: estabilize o ambiente ou declare a mudança não mensurável com este instrumento, antes de alterar qualquer coisa.
|
|
19
|
+
2. Use profiler/trace/plano para localizar custo; isso não mede por si o ganho de uma correção. Antes de escolher o alvo, atribua o tempo por estágio (origem, rede, cache, parse/execução, render; ou aplicação, fila, dependência) e confirme que o custo apontado está no caminho que o usuário espera: topo de perfil fora da jornada é otimização sem efeito percebido. Agregue por código próprio, não por folha de framework, que mostra onde o tempo é gasto e não onde é causado. Número agregado de processo ou requisição inteira serve de sanidade, não de prova. Web: rede/render/bundle; serviço: filas/spans/carga; Postgres: plano/locks/pool; nativo: threads/alocações/lifecycle. Escolha só o ramo pertinente.
|
|
20
|
+
3. Faça a menor alteração testável. Confirme que o mecanismo proposto realmente entrou em efeito. Otimização que adia ou move custo (carga sob demanda, cache, fila, trabalho em segundo plano) não o elimina: meça também o momento em que ele reaparece e o caminho que passou a pagá-lo, não só a condição inicial.
|
|
21
21
|
4. Compare condições alternadas A/B/A/B quando viável; se o baseline deriva, estabilize ou declare o resultado inconclusivo. Latência pede percentis e n, não só média.
|
|
22
|
-
5. Apresente dispersão, custo e possíveis regressões de cauda. Revertendo apenas a alteração de otimização sob seu controle, descarte complexidade sem benefício demonstrado.
|
|
23
|
-
6. Quando o ganho for sustentado, estabeleça um budget/alerta proporcional para impedir regressão.
|
|
22
|
+
5. Apresente dispersão, custo e possíveis regressões de cauda. Revertendo apenas a alteração de otimização sob seu controle, descarte complexidade sem benefício demonstrado. Resultado negativo é resultado: registre na saída a medida que não sustentou o ganho, junto com a reversão, para a próxima tentativa não repetir o caminho.
|
|
23
|
+
6. Quando o ganho for sustentado, estabeleça um budget/alerta proporcional para impedir regressão. O limiar vem da medida que você fez neste alvo, com a condição em que vale (dispositivo, rede, dataset, concorrência); número de catálogo sem essa condição não é budget.
|
|
24
24
|
|
|
25
25
|
Recursos da máquina: medição pede máquina estável. Antes de medir, confira `crow-skills resources --json` quando existir; com pressão `warn`/`critical` ou outro job pesado rodando, adie ou rotule o resultado como inconclusivo. Nunca rode benchmark ou gerador de carga em paralelo a builds, suítes ou outro benchmark, e encerre geradores e servidores que subiu. Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).
|
|
26
26
|
|
|
@@ -1,3 +1,9 @@
|
|
|
1
1
|
# measurement
|
|
2
2
|
|
|
3
3
|
Use ao desenhar o experimento. Baseline repetido (comece com pelo menos cinco execuções), carga fixa e warmup separado. Cinco execuções são um início para investigar ruído, não suficiência estatística nem amostra adequada automaticamente a p95/p99. Relate min/mediana/max para recursos e percentis pertinentes com n para latência; informe quando a amostra não sustenta caudas. Para Core Web Vitals de campo, use p75 e distinga campo de laboratório. Controle cache, CPU/rede, temperatura e concorrência. Serviços: gerador que espera cada resposta pode esconder filas (coordinated omission). Na web, não conclua com uma única nota Lighthouse. A₂ longe de A₁ invalida a comparação B. Quando o ambiente não permite controle, rotule a medida como indicativa.
|
|
4
|
+
|
|
5
|
+
Case o instrumento com a pergunta: perfil amostrado, flame graph ou trace distribuído respondem onde está o custo; A/B em workload fixo responde se a mudança ajudou; perfil por thread ou por span responde qual estágio; profiler de alocação e snapshot de heap respondem se o gargalo é memória e não CPU. Trocar um pelo outro é a origem mais comum do ganho que não se sustenta.
|
|
6
|
+
|
|
7
|
+
Em serviço, o nível de carga faz parte da medida: latência a dez requisições por segundo não diz nada sobre duzentas. Declare a concorrência e meça a curva de latência contra vazão, não um ponto. Separe tempo de servidor de tempo de fila: serviço rápido com requisição esperando para ser aceita continua lento para quem chama. Descarte a janela de warmup explicitamente, em vez de diluí-la na média.
|
|
8
|
+
|
|
9
|
+
Na web, cache frio e cache quente são cenários distintos: relate qual dos dois você mediu e não compare um com o outro. Throttling de CPU e rede tem de ser idêntico entre as execuções, senão você comparou duas máquinas. Nota de ferramenta de laboratório varia muito entre execuções: use a mediana de várias e trate campo (p75 de sessões reais) como o alvo, laboratório como a verificação.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: crow-platform
|
|
3
|
-
description: "Coordene uma plataforma ou iniciativa que atravessa produto, design, engenharia e operação. Não use para um bug ou ajuste isolado."
|
|
3
|
+
description: "Coordene uma plataforma ou iniciativa que atravessa produto, design, engenharia e operação, mapeando as etapas que faltam e o contrato entre elas. Não use para um bug ou ajuste isolado; a coordenação da execução e a delegação são de crow-behaviour."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Entrega de plataforma
|
|
@@ -16,9 +16,9 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
16
16
|
## Trabalho
|
|
17
17
|
|
|
18
18
|
1. Identifique a menor entrega completa e o estado atual: problema aberto, especificação, implementação ou operação. Reutilize decisões válidas; não reinicie fases concluídas.
|
|
19
|
-
2. Liste somente as etapas que faltam, cada uma com id, responsável lógico, entrada, saída, condição de passagem e evidência esperada. Escolha especialistas por intenção, stack e risco, não por palavras isoladas.
|
|
19
|
+
2. Liste somente as etapas que faltam, cada uma com id, responsável lógico, entrada, saída, condição de passagem e evidência esperada. Escolha especialistas por intenção, stack e risco, não por palavras isoladas. Cada etapa nomeia o efeito que ela deve produzir na jornada e como esse efeito será observado depois de entregue; etapa sem efeito observável é candidata a corte, não a execução. Marque o grau de compromisso: etapa cujo escopo ainda depende de decisão ou descoberta pendente entra como não comprometida, com a decisão que a destrava, para o mapa não ser lido como promessa de data. Trabalho habilitador — migração, deprecação, dívida que a fatia exige — é etapa do mapa com dono e evidência, não pressuposto implícito.
|
|
20
20
|
3. Defina um contrato comum entre UI, API e dados antes de separar implementação: operações, códigos de erro e convenções como fuso e unidades. Planeje homologação e recuperação com o desenho, não só depois de terminar o código.
|
|
21
|
-
4. Entregue por fatias verticais: uma jornada atravessa interface, regra, persistência e teste. Paralelize apenas trabalho independente com ownership de arquivos definido.
|
|
21
|
+
4. Entregue por fatias verticais: uma jornada atravessa interface, regra, persistência e teste. O corte está certo quando a fatia é entregável e verificável sozinha: se ela só produz efeito junto com outra, o corte foi por camada disfarçado de fatia e precisa ser refeito. Dependência externa — outro time, fornecedor, API de terceiro, aprovação — vira fronteira de corte, e a fatia que depende dela declara o que avança enquanto ela não chega. Paralelize apenas trabalho independente com ownership de arquivos definido.
|
|
22
22
|
5. Consuma evidências dos especialistas. Reabra uma decisão somente quando a evidência ou o pedido mudar; registre quem decidiu e o impacto nas etapas consumidoras. Contradição entre requisitos aprovados bloqueia as etapas afetadas até o dono decidir; o orquestrador não a resolve.
|
|
23
23
|
|
|
24
24
|
## Saída e aceite
|
|
@@ -30,7 +30,7 @@ Entregue **delivery-map** na resposta final ou em arquivo do projeto cujo caminh
|
|
|
30
30
|
|
|
31
31
|
## Limites e composição
|
|
32
32
|
|
|
33
|
-
Não implementa todos os domínios nem impõe stack, cloud, agentes paralelos ou uma cadeia fixa de skills.
|
|
33
|
+
Não implementa todos os domínios nem impõe stack, cloud, agentes paralelos ou uma cadeia fixa de skills. Este mapa é de entrega, não de execução: decompor para executores, delegar, verificar de forma adversária e registrar passos ficam com `crow-behaviour`, e o mapa não duplica esse ciclo nem estima prazo como se fosse evidência.
|
|
34
34
|
|
|
35
35
|
Altere só o que o pedido e o achado exigem: sem reestilizar, reescrever em outra linguagem, adicionar dependências ou editar docs fora do alvo; documento de outro dono (runbook, política, RACI, decisão registrada) recebe proposta, não edição, salvo pedido explícito; liste e justifique qualquer extra; mudança de contrato (API, schema, formato) e validação mais estrita, que passa a rejeitar o que antes era aceito, ficam como proposta, não implementação, salvo pedido explícito; pedir a correção de um defeito autoriza rejeitar a entrada que o causa, não mais que isso. Não crie branch, commit ou push sem pedido ou política declarada do dono. Use só ferramentas já presentes; não baixe binários nem acesse rede além do alvo autorizado no pedido, prefira contexto isolado ao navegador ou desktop pessoal do usuário e, se faltar ferramenta, declare como não validado. Controles corretos que você verificou, credenciais visivelmente fictícias (fixtures, exemplos) e falsos positivos não são defeito: liste cada um nos descartados, com motivo. Subagentes delegados carregam esta skill; revisores não editam arquivos nem commitam no projeto (exercer a hipótese contra o alvo autorizado não é escrita).
|
|
36
36
|
|
|
@@ -21,6 +21,9 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
|
|
|
21
21
|
4. Planeje migration compatível com leitores/escritores antigos durante rollout. Faça backfill/índice online só quando suportados e necessários; explicite locks, tempo e recuperação.
|
|
22
22
|
5. Teste constraints, concorrência e negações entre papéis/tenants. Confira restauração e caminho de reversão seguro antes de operações irreversíveis.
|
|
23
23
|
|
|
24
|
+
- Leia [migracao-online.md](references/migracao-online.md) ao mexer em tabela com tráfego: lock forte que trava escrita, índice concorrente, constraint em dois tempos (`NOT VALID` depois `VALIDATE`), expand-contract para mudança incompatível, backfill em lotes, reversão e coordenação de fila.
|
|
25
|
+
- RLS, constraints e roles no banco complementam, não substituem, a autorização da aplicação; a decisão de ator × recurso × ação no servidor é de `crow-backend`.
|
|
26
|
+
|
|
24
27
|
## Saída e aceite
|
|
25
28
|
|
|
26
29
|
Entregue **db-change** 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.
|