wizz-method 1.0.3 → 1.2.0

package/src/skills-lib/copywriting/references/natural-transitions.md

@@ -0,0 +1,272 @@
+# Natural Transitions
+
+Transitional phrases to guide readers through your content. Good signposting improves readability, user engagement, and helps search engines understand content structure.
+
+Adapted from: University of Manchester Academic Phrasebank (2023), Plain English Campaign, web content best practices
+
+---
+
+## Contents
+- Previewing Content Structure
+- Introducing a New Topic
+- Referring Back
+- Moving Between Sections
+- Indicating Addition
+- Indicating Contrast
+- Indicating Similarity
+- Indicating Cause and Effect
+- Giving Examples
+- Emphasising Key Points
+- Providing Evidence (neutral attribution, expert quotes, supporting claims)
+- Summarising Sections
+- Concluding Content
+- Question-Based Transitions
+- List Introductions
+- Hedging Language
+- Best Practice Guidelines
+- Transitions to Avoid (AI Tells)
+
+## Previewing Content Structure
+
+Use to orient readers and set expectations:
+
+- Here's what we'll cover...
+- This guide walks you through...
+- Below, you'll find...
+- We'll start with X, then move to Y...
+- First, let's look at...
+- Let's break this down step by step.
+- The sections below explain...
+
+---
+
+## Introducing a New Topic
+
+- When it comes to X,...
+- Regarding X,...
+- Speaking of X,...
+- Now let's talk about X.
+- Another key factor is...
+- X is worth exploring because...
+
+---
+
+## Referring Back
+
+Use to connect ideas and reinforce key points:
+
+- As mentioned earlier,...
+- As we covered above,...
+- Remember when we discussed X?
+- Building on that point,...
+- Going back to X,...
+- Earlier, we explained that...
+
+---
+
+## Moving Between Sections
+
+- Now let's look at...
+- Next up:...
+- Moving on to...
+- With that covered, let's turn to...
+- Now that you understand X, here's Y.
+- That brings us to...
+
+---
+
+## Indicating Addition
+
+- Also,...
+- Plus,...
+- On top of that,...
+- What's more,...
+- Another benefit is...
+- Beyond that,...
+- In addition,...
+- There's also...
+
+**Note:** Use "moreover" and "furthermore" sparingly. They can sound AI-generated when overused.
+
+---
+
+## Indicating Contrast
+
+- However,...
+- But,...
+- That said,...
+- On the flip side,...
+- In contrast,...
+- Unlike X, Y...
+- While X is true, Y...
+- Despite this,...
+
+---
+
+## Indicating Similarity
+
+- Similarly,...
+- Likewise,...
+- In the same way,...
+- Just like X, Y also...
+- This mirrors...
+- The same applies to...
+
+---
+
+## Indicating Cause and Effect
+
+- So,...
+- This means...
+- As a result,...
+- That's why...
+- Because of this,...
+- This leads to...
+- The outcome?...
+- Here's what happens:...
+
+---
+
+## Giving Examples
+
+- For example,...
+- For instance,...
+- Here's an example:...
+- Take X, for instance.
+- Consider this:...
+- A good example is...
+- To illustrate,...
+- Like when...
+- Say you want to...
+
+---
+
+## Emphasising Key Points
+
+- Here's the key takeaway:...
+- The important thing is...
+- What matters most is...
+- Don't miss this:...
+- Pay attention to...
+- This is critical:...
+- The bottom line?...
+
+---
+
+## Providing Evidence
+
+Use when citing sources, data, or expert opinions:
+
+### Neutral attribution
+- According to [Source],...
+- [Source] reports that...
+- Research shows that...
+- Data from [Source] indicates...
+- A study by [Source] found...
+
+### Expert quotes
+- As [Expert] puts it,...
+- [Expert] explains,...
+- In the words of [Expert],...
+- [Expert] notes that...
+
+### Supporting claims
+- This is backed by...
+- Evidence suggests...
+- The numbers confirm...
+- This aligns with findings from...
+
+---
+
+## Summarising Sections
+
+- To recap,...
+- Here's the short version:...
+- In short,...
+- The takeaway?...
+- So what does this mean?...
+- Let's pull this together:...
+- Quick summary:...
+
+---
+
+## Concluding Content
+
+- Wrapping up,...
+- The bottom line is...
+- Here's what to do next:...
+- To sum up,...
+- Final thoughts:...
+- Ready to get started?...
+- Now it's your turn.
+
+**Note:** Avoid "In conclusion" at the start of a paragraph. It's overused and signals AI writing.
+
+---
+
+## Question-Based Transitions
+
+Useful for conversational tone and featured snippet optimization:
+
+- So what does this mean for you?
+- But why does this matter?
+- How do you actually do this?
+- What's the catch?
+- Sound complicated? It's not.
+- Wondering where to start?
+- Still not sure? Here's the breakdown.
+
+---
+
+## List Introductions
+
+For numbered lists and step-by-step content:
+
+- Here's how to do it:
+- Follow these steps:
+- The process is straightforward:
+- Here's what you need to know:
+- Key things to consider:
+- The main factors are:
+
+---
+
+## Hedging Language
+
+For claims that need qualification or aren't absolute:
+
+- may, might, could
+- tends to, generally
+- often, usually, typically
+- in most cases
+- it appears that
+- evidence suggests
+- this can help
+- many experts believe
+
+---
+
+## Best Practice Guidelines
+
+1. **Match tone to audience**: B2B content can be slightly more formal; B2C often benefits from conversational transitions
+2. **Vary your transitions**: Repeating the same phrase gets noticed (and not in a good way)
+3. **Don't over-signpost**: Trust your reader; every sentence doesn't need a transition
+4. **Use for scannability**: Transitions at paragraph starts help skimmers navigate
+5. **Keep it natural**: Read aloud; if it sounds forced, simplify
+6. **Front-load key info**: Put the important word or phrase early in the transition
+
+---
+
+## Transitions to Avoid (AI Tells)
+
+These phrases are overused in AI-generated content:
+
+- "That being said,..."
+- "It's worth noting that..."
+- "At its core,..."
+- "In today's digital landscape,..."
+- "When it comes to the realm of..."
+- "This begs the question..."
+- "Let's delve into..."
+
+See the seo-audit skill's `references/ai-writing-detection.md` for a complete list of AI writing tells.

package/src/skills-lib/database-and-deps/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: database-and-deps
+description: >
+  Segurança de banco de dados e dependências. Usar quando: revisar queries de banco, checar SQL injection,
+  auditar permissões de banco, criptografar PII, revisar pacotes vulneráveis, configurar Dependabot/Renovate,
+  auditar RPCs Supabase, verificar menor privilégio no banco.
+---
+
+# Database and Dependencies Security
+
+## Banco de dados
+
+### SQL Injection
+- Use sempre queries parametrizadas ou ORM com binding correto
+- Nunca concatene input do usuário em SQL
+- Mesmo com ORM: raw queries precisam de atenção
+- Teste com payloads: `' OR '1'='1`, `'; DROP TABLE users;--`
+
+### Stack Supabase — como prevenir SQLi
+O Supabase client já é parametrizado por design:
+```ts
+// SEGURO — query-builder: valores passados como args separados
+const { data } = await supabase
+  .from("captou_leads")
+  .select("*")
+  .eq("workspace_id", workspaceId)  // parametrizado
+  .ilike("name", `%${search}%`)     // parametrizado (não concatenado em SQL)
+
+// SEGURO — RPC com params nomeados
+await supabase.rpc("find_captou_extraction_job_by_run_id", { run_id: runId })
+
+// PERIGOSO — raw SQL com interpolação (evitar)
+await supabase.rpc("exec_sql", { sql: `SELECT * WHERE id = '${id}'` })
+```
+
+**Ressalva importante:** o corpo das funções RPC vive no Postgres (fora do repo). Auditar no dashboard do Supabase se alguma RPC usa `EXECUTE format('... %s', input)` com input do usuário — isso é SQL injection server-side.
+
+### Princípio do menor privilégio
+- Usuário da aplicação: apenas SELECT/INSERT/UPDATE/DELETE nas tabelas necessárias
+- Nunca use usuário root/admin da aplicação
+- Crie usuário separado para migrations (com ALTER TABLE, CREATE, DROP)
+- Read replicas: usuário somente leitura
+- Supabase: `SUPABASE_SERVICE_ROLE_KEY` bypassa RLS — só usar em server-side para operações admin; para operações de usuário, usar a `anon key` + RLS
+
+### Dados sensíveis em banco
+- Criptografe PII (CPF, dados de cartão) em repouso com AES-256
+- Não armazene dados de cartão (use tokenização via gateway de pagamento)
+- Logs e audit trail: guarde quem acessou/modificou dados sensíveis
+- Backups criptografados: a cópia do banco não pode ser mais fraca que o banco
+- `deleted_at timestamp` para soft delete — nunca apague dados reais; isto também é auditoria
+
+### Checklist de segurança de banco
+- [ ] Nenhuma query monta SQL com template literal/concatenação?
+- [ ] `grep -r "\.sql\|\.query(\|raw(" src/` → revisar manualmente?
+- [ ] RPCs Supabase auditadas no dashboard (sem `EXECUTE format(...)` inseguro)?
+- [ ] RLS ativo nas tabelas de domínio? (`SELECT tablename, rowsecurity FROM pg_tables`)
+- [ ] `SUPABASE_SERVICE_ROLE_KEY` usada apenas em server-side?
+
+## Dependências
+
+### Vulnerabilidades em pacotes
+- `npm audit` / `pnpm audit` / `pip audit`: rode em CI em cada PR
+- Dependabot ou Renovate: automatize atualizações de segurança
+- Lock files (`package-lock.json`, `pnpm-lock.yaml`): sempre commite, garante reprodutibilidade
+
+### Supply chain attacks
+- Prefira pacotes com muitos downloads e manutenção ativa
+- Verifique integridade: `npm install --ignore-scripts` para pacotes suspeitos
+- SBOM (Software Bill of Materials): documente todas as dependências em produção
+
+### Atualizações
+- Dependências de segurança: atualize imediatamente
+- Dependências menores: sprint a sprint
+- Major versions: planeje com antecedência, não deixe acumular
+
+### Checklist de dependências
+- [ ] `pnpm audit` (ou `npm audit`) rodado e sem HIGH/CRITICAL abertos?
+- [ ] Lock file commitado?
+- [ ] Dependabot ou Renovate configurado no repo?
+- [ ] Pacotes de dev não vão para produção (`devDependencies` correto)?

package/src/skills-lib/database-scaling/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: database-scaling
+description: Escalar banco de dados — sharding, réplicas de leitura, connection pooling, índices, N+1, particionamento. Use quando o pedido envolver banco lento, performance de queries, escala de dados.
+---
+
+# Database Scaling
+
+## Identificando o gargalo de banco
+- Queries lentas: ative slow query log (> 100ms é sinal de alerta)
+- Connections esgotadas: use connection pooling (PgBouncer, RDS Proxy)
+- CPU alta no banco: índices faltando ou queries ineficientes
+- I/O alto: volume de dados crescendo mais rápido que o hardware
+
+## Índices
+
+### Quando criar
+- Colunas usadas em WHERE, ORDER BY, JOIN
+- Colunas de foreign key que não têm índice automático
+- Combinações de colunas usadas juntas em filtros
+
+### Quando não criar
+- Tabelas pequenas (< 10k linhas) raramente se beneficiam
+- Colunas com poucos valores distintos (ex: status com 3 opções)
+- Índices demais degradam escrita (todo INSERT/UPDATE precisa atualizar índices)
+
+## Read Replicas
+- Separe queries de leitura (relatórios, listagens) para réplica
+- Escreva sempre no primário
+- Atenção ao replication lag em dados críticos
+
+## Sharding
+- Última opção, após esgotar otimizações de query e hardware
+- Shard por ID do usuário ou tenant é o padrão mais comum
+- Aumenta muito a complexidade de queries que cruzam shards
+
+## Particionamento (PostgreSQL)
+- Particione tabelas grandes por data (logs, eventos, transações)
+- Facilita DELETE de dados antigos (drop partition em vez de DELETE em massa)
+- Melhora performance de queries com filtro de data
+
+## Conexões e pool
+- Limite de conexões do Postgres: default 100, aumente com cuidado
+- PgBouncer em transaction mode: centenas de clientes, dezenas de conexões reais
+- Nunca abra conexão sem fechar (connection leak mata o banco)