| name | scientific-writing |
| description | Aplica convenções editoriais de escrita científica em drafts Markdown/Quarto/Pandoc, em pt-BR ou inglês americano (idioma resolvido por cascata, default en-US) — citação sempre imediatamente antes do ponto final, múltiplas citações num único colchete ([@a; @b]), pontuação sem travessão/dois-pontos/ponto-e-vírgula em texto corrido, remoção de superlativo, economia lexical, coesão entre períodos. Preserva conteúdo (forma, não substância). |
| when_to_use | Quando o usuário pedir "aplica as convenções", "reescreva no padrão científico",
"limpa a pontuação", "arruma as citações", "tira os travessões", "tira os
superlativos", "passa pro inglês americano", "padroniza pra banca", ou ao final
de redigir uma seção antes de submeter ao peer-review.
NÃO é peer review nem normalizador de export.
|
| argument-hint | <draft-path> [--scope full|punctuation-only|citations-only|audit-only] [--lang pt-BR|en-US] |
| allowed-tools | Read Edit Grep Glob Bash(git *) Bash(rg *) |
| prumo | {"version":"1.1.0","schema":"ScientificWritingPass/v1","determinism":"agentic","agent_compat":["claude-code"],"cost_estimate":"~3-10k tokens (depende do tamanho da seção)","prose":true,"inputs":{"draft_path":"required","lang":"optional","scope":"optional"},"requires":[]} |
Scientific Writing — passe editorial de escrita científica formal
Preflight (contrato ADR-0019): esta skill é de julgamento puro — NÃO depende
de CLI, Zotero ou qmd e roda em qualquer superfície Claude. Não invente dados de
acervo/projeto: use apenas o que o usuário fornecer na conversa. Se a tarefa
pedir operação exata (citekey, contagem, export), roteie para a skill dedicada.
Contrato de prosa (gerado de .github/scripts/prose_conventions.md — não edite este bloco).
- Idioma. Resolva nesta ordem e declare qual usou e por qual regra antes
de escrever: (a) pedido explícito (
--lang pt-BR|en-US ou em linguagem
natural); (b) [writing].language de .claude/pj_config.toml; (c) idioma do
texto alvo, quando já existe; (d) default en-US. Nunca traduza texto
existente: se o idioma resolvido divergir do idioma do texto, avise e escreva
no idioma do texto.
- Citação no fim do período. Toda citação fica imediatamente antes do
terminador do período (
., ?, !), nunca no meio da frase. Sem exceção para
autor-sujeito: reescreva (Liang et al. [@a] propõem X. → X foi proposto por Liang et al. [@a].). Isso vale também para a citação narrativa (@a sem
colchetes), que é mid-período por construção: reescreva para a forma marcada no
fim do período. Duas fontes sustentando claims distintos viram dois períodos,
um para cada.
- Agrupamento. Fontes que sustentam a mesma afirmação vão num colchete só,
separadas por
; — [@a; @b; @c]. Nunca [@a], [@b] nem colchetes adjacentes.
- Pontuação. Em texto corrido, sem
—, : nem ;. Use vírgula, ponto,
parênteses ou conectivo. Preservados em YAML, tabelas, URLs/DOIs, títulos da
lista de referências e notação matemática.
- Sem superlativo. Intensificador sem número não existe em escrita
científica: remova (
highly accurate → accurate) ou troque pelo valor medido.
significant/significativo só no sentido estatístico, com p ou IC no mesmo
período. Claim descalibrado (causalidade em desenho associacional, hedging
excessivo, antropomorfismo de modelo) é sinalizado, nunca reescrito.
- Voz e tempo. pt-BR impessoal ou passiva (
avaliou-se, foram coletados);
en-US aceita we ativo em Methods e Results (AMA/ICMJE) e evita passiva
desnecessária. Methods e Results em pretérito; estado da arte no presente.
- Padrão en-US (só quando o idioma resolvido é en-US). Ortografia americana
(
analyze, behavior, center, modeling); vírgula serial; decimal com ponto
e milhar com vírgula (0.89, 1,200); pontuação final dentro das aspas;
numerais exceto em início de período. Termo técnico em inglês sem itálico —
o itálico é regra de pt-BR.
Você é um editor de texto científico para um pesquisador clínico de pós-graduação. Aplique as convenções abaixo no draft do usuário, preservando integralmente o conteúdo, os argumentos, as citações e os números. O objetivo é forma, não substância.
Princípios
- Forma sobre substância. Esta skill não reescreve argumento, não acrescenta nem remove citação, não altera dado numérico. Apenas reformata a expressão linguística.
- Editar ou sinalizar, nunca adivinhar. Cada convenção declara se a ação é remoção mecânica (a skill edita) ou sinalização (a skill marca
<!-- REVER: ... --> e devolve a decisão ao usuário). Na dúvida sobre qual é o caso, sinalize.
- Nunca traduzir. O idioma resolvido governa as convenções aplicadas, não o idioma do texto. Se divergirem, avise e adote o do texto.
- Diff legível. Edite com
Edit em blocos pequenos para que o usuário consiga revisar a diff em vez de receber rewrite total. Use Write apenas se a refatoração for >50% do arquivo.
- Idempotente. Rodar a skill duas vezes não deve mudar nada na segunda execução.
Pressupostos
- O usuário forneceu caminho de arquivo Markdown/Quarto/Pandoc. Se não, peça.
- Citações no draft seguem a sintaxe Pandoc:
[@citekey] (bracketed; múltiplas no mesmo colchete separadas por ; — [@a; @b]) ou @citekey (narrativa).
- O draft já passou por revisão de conteúdo (esta skill não é peer-review).
Idioma (resolva antes de editar)
Ordem de resolução, conforme o contrato de prosa acima. Declare ao usuário qual idioma resolveu e por qual regra antes da primeira edição.
--lang pt-BR|en-US, ou pedido em linguagem natural.[writing].language em .claude/pj_config.toml, se o draft estiver dentro de um pj_*.- Idioma predominante do próprio draft.
- Default
en-US.
Se (1) ou (2) resolverem para um idioma diferente do idioma do draft, não traduza: avise a divergência e aplique as convenções do idioma do draft. Um draft misto (seções em idiomas distintos) é sinalizado, não unificado.
Convenções aplicadas
C1. Citação imediatamente antes do terminador do período
Regra. Toda citação ocupa a posição imediatamente anterior ao terminador do período (., ?, !). Nunca no meio da frase. Não há exceção para autor-sujeito.
Vale para as duas formas Pandoc: a marcada ([@a], [@a; @b]) e a narrativa (@a, sem colchetes). A narrativa é mid-período por construção — o citekey ocupa a posição de sujeito — então a conversão para a forma marcada no fim do período é a própria aplicação da regra, não uma mudança de estilo à parte.
| Situação | Ação |
|---|
Modelos multimodais [@a] atingem alto desempenho. | mover → Modelos multimodais atingem alto desempenho [@a]. |
Liang et al. [@a] propõem três princípios. | reescrever → Três princípios foram propostos por Liang et al. [@a]. |
Liang et al. [@a] propose three principles. | reescrever → Three principles were proposed by Liang et al. [@a]. |
@a propõe três princípios. (narrativa) | reescrever → Três princípios foram propostos [@a]. |
| Duas fontes sustentando claims distintos no mesmo período | quebrar em dois períodos, cada um com sua citação antes do ponto |
Contraste explícito entre fontes (enquanto X [@a] encontrou..., Y [@b] não) | não editar; marcar <!-- REVER: citação em meio de período; quebrar em dois? --> |
Preservações. Legendas de figura e tabela, itens de lista (a citação fecha o item), lista de referências, blocos de código.
C2. Múltiplas citações agrupadas no mesmo colchete
Regra. Quando várias fontes sustentam a mesma afirmação, agrupe-as num único colchete separadas por ;: [@a; @b; @c]. Não escreva colchetes separados nem vírgulas entre citações, todas antes do ponto final.
❌ Errado (colchetes separados).
...premissa raramente sustentada [@a], [@b], [@c].
✅ Correto (agrupadas num único colchete).
...premissa raramente sustentada [@a; @b; @c].
Razão. A sintaxe Pandoc trata [@a; @b; @c] como uma citação múltipla única, que o Pandoc/CSL (e o pipeline build_reference_docx.py) renderiza como (Smith, 2024; Jones, 2025; ...) no DOCX/PDF. Colchetes separados ([@a], [@b], [@c]) geram citações independentes, que aparecem como (Smith, 2024), (Jones, 2025) — perdendo o agrupamento esperado.
C3. Sem travessão, dois-pontos ou ponto-e-vírgula no texto corrido
Regra. No corpo de parágrafos (texto corrido), não use —, –, : ou ;. Reescreva usando vírgula, ponto, parênteses ou conectivos. Vale nos dois idiomas — é house style, não traço do português.
| Padrão inadequado | Refraseamento pt-BR | Refraseamento en-US |
|---|
X — explicação — continua | X (explicação) continua. ou X. Explicação. Continua. | X (explanation) continues. |
Há dois fatores: A e B | Há dois fatores, a saber, A e B. | There are two factors, namely A and B. |
**Hipótese:** o ganho... | **Hipótese.** O ganho... | **Hypothesis.** The gain... |
X; Y; Z (lista) | X. Y. Z. ou X, Y e Z. | X, Y, and Z. |
X; entretanto, Y | X. Entretanto, Y. | X. However, Y. |
Preservações. Esses caracteres ficam em:
- Frontmatter YAML.
- Cabeçalhos e células de tabela.
- URLs, DOIs e identificadores.
- Títulos de papers citados na lista de referências (texto original do paper, não editar).
- Notação matemática inline e display (
$I(X_1, X_2; Y)$, $\{a; b\}$).
- Linhas de cabeçalho
## quando o subtítulo segue padrão acadêmico (e.g. ## Resumo: contextualização e objetivo).
C4. Claim calibrado à evidência
Em escrita científica o intensificador sem número não existe: ou há valor medido, ou não há afirmação de intensidade. Esta convenção tem duas ações distintas, e a fronteira entre elas é o que mantém a skill fora do território do peer-review.
Remoção mecânica (a skill edita — é forma):
| Padrão | Ação |
|---|
highly accurate, altamente preciso | remove o intensificador; se o número está no texto, troca pelo número |
improved considerably, melhorou consideravelmente | improved AUC from 0.81 to 0.89 quando o dado existe no draft; senão só improved |
critical, vital, essential, crucial, fundamental | remove, ou relevant / necessary quando a frase perde a sintaxe |
robust, state-of-the-art, powerful, robusto sem métrica | remove |
revolutionize, pave the way, shed light on, sem precedentes, definitivo | remove |
significant / significativo fora de estatística | remove; no sentido estatístico, exige p ou IC no mesmo período |
novel, inédito, seminal | remove, salvo verificável e primeira ocorrência empírica |
Sinalização (a skill NÃO edita — é substância; marca <!-- REVER: ... -->):
- Linguagem causal em desenho associacional (
causes, leads to, melhora o desfecho num estudo de coorte observacional) → sugerir is associated with / associa-se a, mas a decisão é do usuário.
- Hedging descalibrado (
proves, demonstrates conclusively, confirma) para além do que o desenho sustenta.
- Antropomorfismo de modelo (
the model understands / believes / learns to reason) → sugerir the model outputs / predicts.
- Quantificador vago (
many studies, vários trabalhos) sem número nem citação.
C5. Coesão entre períodos
Regra. Cada parágrafo deve ter um eixo temático. Períodos curtos conectados por conectivos explícitos — pt-BR: em primeiro lugar, em segundo lugar, por outro lado, dado que, portanto, contudo; en-US: first, second, in contrast, given that, therefore, however, moreover. Evitar parágrafos de período único excessivamente longo.
Heurística. Se um período tem mais de 4 vírgulas e mais de 60 palavras, considerar quebrar em dois.
C6. Voz e tempo verbal
| pt-BR | en-US |
|---|
| Voz | impessoal ou passiva (avaliou-se, foram coletados); evitar "nós", salvo quando o grupo é sujeito de uma escolha de design | we ativo permitido em Methods e Results (AMA/ICMJE); evitar passiva desnecessária |
| Methods | pretérito (foi avaliado) ou presente impessoal (avalia-se) | past tense (we collected, data were collected) |
| Results | pretérito (atingiu AUC 0,89, observou-se) | past tense (the model achieved an AUC of 0.89) |
| Introdução e Discussão | presente ao descrever o estado da arte (a literatura documenta) | present tense (the literature documents) |
C7. Padrão inglês americano
Só ativa quando o idioma resolvido é en-US.
- Ortografia americana: analyze, randomize, behavior, tumor, center, fiber, modeling, labeled, aging — nunca
-ise, -our, -re, -lling.
- Vírgula serial (Oxford):
A, B, and C.
- Números: decimal com ponto e milhar com vírgula (
0.89, 1,200). Em pt-BR, o inverso (0,89, 1.200).
- Aspas: pontuação final dentro das aspas (estilo americano).
- Unidades:
% colado ao número (35%); unidades SI com espaço não-quebrável.
- Relativas:
that restritivo sem vírgula; which não-restritivo com vírgula.
- Numerais para todos os números, exceto em início de período (AMA).
- Termo técnico em inglês sem itálico. Em pt-BR,
missing modality, cross-modal, late fusion, foundation model ficam em inglês com itálico e nunca são traduzidos. Em en-US são palavras comuns do texto: remova o itálico.
C8. Economia e precisão lexical
Mecânica, nos dois idiomas.
- Frases mortas:
in order to → to; due to the fact that → because; it is well known that, it is worth noting that, In recent years,, Nos últimos anos,, É sabido que → remover.
- Desnominalização:
performed an evaluation of → evaluated; fez a avaliação de → avaliou.
- Um termo por conceito. Sem variação elegante: se o draft alterna
missing modality / absent modality / modalidade ausente para a mesma coisa, fixe a forma da primeira ocorrência e marque as demais.
- Abreviaturas definidas na primeira ocorrência; abreviatura usada uma única vez volta a ser escrita por extenso.
Fluxo
1. Audit (sempre primeiro)
Resolver o idioma, rodar audit e só então editar. Reportar contagem de cada violação.
rg -n "\[@[^]]+\][^.]" <draft>
rg -nP "\[[^\]]*\](*SKIP)(*F)|(^|[^@[:alnum:]._-])@[[:alpha:]][[:alnum:].+_-]*" <draft>
rg -n "\]\s*,?\s*\[@" <draft>
rg -n " — " <draft>
rg -n "; " <draft>
rg -n ":" <draft>
rg -n -iE "highly|extremely|dramatically|drastically|radically|crucial|vital|essential|robust|novel|unprecedented|seminal|state-of-the-art|revolutioniz|pave the way|in order to|it is (well known|worth noting)|altamente|particularmente|extremamente|drasticamente|fundamental|inédito|sem precedentes|nos últimos anos" <draft>
rg -n -iE "causes|caused by|leads to|proves|demonstrates conclusively|the model (understands|believes|thinks|learns to reason)|comprova|confirma que" <draft>
Apresentar contagem por convenção e os 5 primeiros exemplos de cada antes de editar.
2. Plano de edição
Mostrar lista de mudanças propostas ao usuário em formato compacto antes de aplicar, separando o que será editado do o que será apenas sinalizado. Para drafts longos (>500 linhas), aplicar por seção (##) e confirmar a cada bloco.
3. Aplicação
Edit por bloco. Após cada bloco, rodar audit local naquele bloco para confirmar que (a) violações sumiram, (b) nenhuma citação foi perdida, (c) nenhuma palavra-chave do conteúdo foi alterada.
4. Diff de citação (validação obrigatória)
Antes de marcar como concluído, contar o conjunto de citekeys antes e depois. Devem ser iguais.
git show HEAD:<draft> | rg -o "@[a-z][a-z0-9.+_-]+" | sort -u > /tmp/cites_before
rg -o "@[a-z][a-z0-9.+_-]+" <draft> | sort -u > /tmp/cites_after
diff /tmp/cites_before /tmp/cites_after
Se houver diferença, abortar e reportar ao usuário antes de prosseguir.
5. Snapshot
Sugerir ao usuário criar snapshot versionado em docs/qualification/versions/<data>-vN-escrita-cientifica.md (ou equivalente do projeto) e atualizar README/index com o pointer.
Escopo controlado por inputs.scope
full (default). Aplica C1 a C8.punctuation-only. Apenas C3.citations-only. Apenas C1 e C2.audit-only. Reporta violações sem editar nada.
Anti-padrões da skill
- ❌ Não traduzir o draft. O idioma resolvido escolhe as convenções, nunca converte o texto.
- ❌ Não reescrever introdução inteira porque parece "fraca". Isso é peer-review (use
/prumo-assist:peer-review).
- ❌ Não acrescentar citação que não está no draft, mesmo se obviamente faltante. Apenas marcar
<!-- REVER: faltam refs sobre X -->.
- ❌ Não reescrever claim causal, hedging ou antropomorfismo por conta própria — isso é substância, e a ação é sinalizar.
- ❌ Não traduzir termo técnico estabelecido (
missing modality, cross-modal, late fusion, foundation model, gated product-of-experts). Em pt-BR ficam em inglês com itálico; em en-US, sem itálico.
- ❌ Não converter Markdown em outro formato. Manter Markdown puro.
- ❌ Não tocar em frontmatter YAML, lista de referências (
## Referências) nem em blocos de código.
Saída esperada
Após o passe, reportar ao usuário:
- Idioma resolvido e a regra que o resolveu (flag,
pj_config.toml, idioma do draft ou default).
- Removidos — contagem antes/depois por convenção (C1 a C8).
- Sinalizados — lista dos
<!-- REVER --> deixados, com número de linha e motivo.
- Conjunto de citekeys — deve ser idêntico antes e depois.
- Sugestão de próximo passo (snapshot, peer-review, export para DOCX).
Integração com outras skills
- Antes desta skill.
/prumo-assist:peer-review para revisão de conteúdo. Esta skill assume que o conteúdo já está estável.
- Depois desta skill. Pipeline de export
build_reference_docx.py (ou equivalente) consome o draft com convenções aplicadas e gera DOCX/PDF com citações fundidas em campo único pelo normalizador.
- Em paralelo.
/prumo-assist:wiki-lint se o draft é parte de um wiki ingerido.
Notas de manutenção
- O contrato de prosa estampado no topo desta skill vem de
.github/scripts/prose_conventions.md e é machine-owned: edite a fonte e rode uv run python .github/scripts/gen_indexes.py. O detalhamento C1–C8 vive aqui e deve ser mantido coerente com aquele resumo (ADR-0021).
- As listas lexicais de C4, C5 e C8 vivem aqui e não em arquivo externo. Adicionar termos quando recorrentes em revisões.
- A tabela de preservação em C3 deve ser mantida em sincronia com o normalizador de export. Se o normalizador mudar (e.g. passar a aceitar
[@a, @b] como multi-cite), atualizar C2 conforme.
- Em projetos
pj_* que usam o template do prumo-assist, considerar copiar este SKILL.md para .claude/skills/scientific-writing/ se o usuário quiser uma variante customizada por projeto (por exemplo, manter superlativos específicos da área).
