ptbr-writer

whitepaper

o artigo, em português: a tese, os três pilares, o que se mediu e o que não se mediu.

a prévia não aparece em todo celular. abra o PDF ou baixe o PDF. em inglês: Whitepaper (EN).

uso

chame a skill pelo nome, ou descreva a tarefa com suas palavras.

• /ptbr-writer
• /ptbr
• reescreva este runbook em português controlado
• tire a ambiguidade deste texto
• revise este comunicado

níveis de rigor

sem nível pedido, a skill escolhe um e diz qual assumiu. um nível planejado ainda não está na skill, e não custa contexto a quem a instala.

estritoIMPLEMENTADO

runbooks, procedimentos, saídas para agentes.

descritivoIMPLEMENTADO

documentação de sistema.

leveIMPLEMENTADO

comunicados internos.

científicoIMPLEMENTADO

artigos, propostas, relatórios técnicos com fontes.

smart-noteIMPLEMENTADO

notas para um segundo cérebro; combina com outro nível (smart-note + estrito).

retóricoPLANEJADO

texto que precisa convencer: proposta, justificativa, comunicado de decisão

ensaísticoPLANEJADO

ensaio: o autor pensa por escrito, em primeira pessoa, à maneira de The Essays (Os Ensaios), de Michel de Montaigne

crônicoPLANEJADO

crônica: o cotidiano observado de perto, em tom de conversa com o leitor

anedóticoPLANEJADO

anedota: um caso curto e concreto que ilustra uma ideia

machado-writerPLANEJADO

o estilo de Machado de Assis (1839–1908): ironia, digressão, o narrador que conversa com o leitor. Obra em domínio público; o texto produzido cita Machado de Assis (REUSE.md)

saramago-writerPLANEJADO

o estilo de José Saramago (1922–2010): períodos longos, pontuação mínima, diálogo sem travessão. Obra protegida por direito autoral: imita o estilo, nunca copia trecho (REUSE.md)

talvez venha um orwell-writer, como a skill orwell-writing, mas feito para os grandes escritores da língua portuguesa: um nível por autor, para imitar estilos idiossincráticos de escrita. o estilo de saramago já tem um linter de prosa, em lint/saramago.

⚠ aviso: um nível de autor imita um estilo, nunca copia texto, e respeita os direitos do autor. obra em domínio público, de quem morreu há muito tempo, pode servir de base, e o autor é citado sempre que o texto for usado. obra protegida serve só de modelo de estilo. as regras estão no REUSE.md.

regras

cada regra corrige um tipo de ambiguidade. a tabela de violações da saída cita a regra pelo id.

1. PTW-1

   Quem faz, aparece

   Sujeito explícito. Evite -se apassivador, o mesmo e clíticos de terceira pessoa ambíguos.

   origem: PTC-1, de kayquer/portugues-tecnico-controlado, por @kayquer

2. PTW-2

   Uma proposição por frase

   Corte gerúndios conectores e subordinadas que escondem uma segunda ação.

   origem: PTC-2, de kayquer/portugues-tecnico-controlado, por @kayquer

3. PTW-3

   Modalidade e quantidade explícitas

   deve = obrigação. Probabilidade por número ou intervalo, nunca por modal vago.

   origem: PTC-3, de kayquer/portugues-tecnico-controlado, por @kayquer

4. PTW-4

   Verbo pleno

   realizar a validação → validar.

   origem: PTC-4, de kayquer/portugues-tecnico-controlado, por @kayquer

5. PTW-5

   Sintaxe plana

   Cadeia de de curta, adjetivo pós-nominal, nada entre verbo e objeto.

   origem: PTC-5, de kayquer/portugues-tecnico-controlado, por @kayquer

6. PTW-6

   Termos congelados

   Um conceito, um termo. Fixa a variante brasileira.

   origem: PTC-6, de kayquer/portugues-tecnico-controlado, por @kayquer

7. PTW-7

   Números, datas e unidades

   Vírgula decimal. Datas ISO 8601. Unidades padronizadas.

   origem: PTC-7, de kayquer/portugues-tecnico-controlado, por @kayquer

8. PTW-8

   Ortografia PT-BR vigente

   Acordo de 1990, com atenção a prefixos técnicos (microsserviço, autosserviço).

   origem: PTC-8, de kayquer/portugues-tecnico-controlado, por @kayquer

9. PTW-9

   Toda afirmação tem marca

   No nível científico, cada afirmação leva (v), (v, só título) ou ⚠. A skill preserva as marcas e nunca remove um ⚠. Afirmação reescrita perde o (v): marque ⚠ e avise.

   origem: ouro-paper: toda afirmação tem marca, de marola-dev/marola-research, por @h0ffmann · AGENTS.md: Audience and evidence, de h0ffmann/ww3-gpu, por @h0ffmann

10. PTW-10

    Nenhuma referência inventada

    A skill nunca adiciona, completa ou corrige citação ou DOI de memória. Referência incompleta vira ⚠ na tabela de violações.

    origem: ouro-paper: nunca inventar referência, de marola-dev/marola-research, por @h0ffmann

11. PTW-11

    Número com unidade e origem

    No nível científico, número sem unidade, ou sem comando ou fonte, é sinalizado. Adjetivo de quantidade (muito mais rápido) vira número ou ⚠.

    origem: ouro-paper: todo número tem seu comando, de marola-dev/marola-research, por @h0ffmann · AGENTS.md: Audience and evidence, de h0ffmann/ww3-gpu, por @h0ffmann

12. PTW-12

    Sem alegação de pioneirismo

    inédito, pela primeira vez, até onde sabemos, novo método: estreite para o que foi consultado e quando, ou liste como não sabido.

    origem: .vale/styles/research/PriorityClaims, de marola-dev/marola-research, por @h0ffmann

13. PTW-13

    Fato separado de análise

    Cada frase é fato com fonte ou leitura do autor, e diz qual. A fonte não diz não é não é assim.

    origem: ouro-paper: fatos e análise separados, de marola-dev/marola-research, por @h0ffmann

14. PTW-14

    Palavras inteiras e por extenso

    Separe e junte palavras (bomd ia vira bom dia). Troque abreviação de internet pela palavra (vc vira você, pq vira porque). O Acordo de 1990 fica com a PTW-8.

    origem: pedido do dono do repo, de h0ffmann/ptbr-writer, por @robkler

15. PTW-15

    Pontuação

    Vírgula depois de vocativo e de saudação. Ponto final no fim da frase. ? em pergunta. Vírgula antes de mas. Nunca vírgula entre sujeito e verbo.

    origem: pedido do dono do repo, de h0ffmann/ptbr-writer, por @robkler

16. PTW-16

    Maiúsculas e concordância

    Maiúscula no início da frase e em nome próprio. Concordância verbal e nominal (os relatórios estão prontos).

    origem: pedido do dono do repo, de h0ffmann/ptbr-writer, por @robkler

17. PTW-17

    Frase reorganizada

    Reescreva inteira a frase confusa, longa ou ambígua, no tom pedido. Não mude o sentido nem acrescente informação. A frase reescrita já leva as correções das PTW-8 e PTW-14 a 16. Não reescreva a frase que já está correta e clara.

    origem: pedido do dono do repo, de h0ffmann/ptbr-writer, por @robkler

formato de saída

toda resposta da skill vem nesta ordem.

1. Nível e destinatário assumidos.
2. Tabela de violações: regra, trecho original, reescrita.
3. Texto final.
4. Nota sobre o que foi mantido de propósito.
5. Lista de ⚠: afirmações sem checagem e referências a buscar, no nível científico.
6. Linha de tempo de leitura no texto final: Leitura estimada: ~N min (P palavras, L links, B blocos de código), ou < 1 min; em inglês, Estimated reading time: .... Com Bash e o comando de tempo de leitura (o pedido ptbr o dá), rode <comando> [--lang en] <arquivo>; sem eles, calcule à mão: palavras da prosa ÷ 238 por minuto, × 1,15 se a frase média passa de 20 palavras, × 1,15 se mais de 25% das palavras têm 10 letras ou mais, + 10 s por linha de código, + 5 s por link, arredondado para cima. Nunca invente o número.

smart-note

para quem mantém um segundo cérebro. a ideia vem de how to take smart notes, do zettelkasten e do fichário analógico de pirsig: o texto sai cru, e também como conhecimento indexável, com tags e links.

Combina com outro nível: aplica as regras dele e entrega em notas. Duas saídas, RAW (só o texto) e nota (indexável, com front matter); sem pedido, entregue as duas.

1. Uma ideia, uma nota: uma afirmação, um fato ou uma pergunta. Cinco ideias, cinco notas.
2. Palavras próprias. Cite literal só o que precisa ficar exato, entre aspas, com a fonte.
3. Nome permanente <id>-<slug>.md; id é a hora UTC da criação, AAAAMMDDhhmm. O id não muda; o título pode.
4. Front matter: id, title, type, status, source, tags, created (ISO 8601).
5. type: fleeting (ideia crua, como veio), literature (o que uma fonte diz, com link ou DOI), permanent (afirmação própria, feita de outras notas).
6. status: unverified, partial, verified, open-question ou approved. approved é a palavra do dono, não checagem de fato; só o dono dá, e a nota diz quando.
7. Links: toda nota liga a pelo menos uma outra com [[<id>-<slug>]], que existe. Sem vizinha conhecida, proponha o link e marque ⚠.
8. Verdade: afirmação factual fica unverified até a fonte ser lida e citada na nota. Nunca invente fonte, citação ou número.
9. Pessoas: quem não é figura pública aparece por apelido (friend1, prof1), nunca pelo nome.
10. Tags: minúsculas, com hífen, poucas; reuse as que o cofre já tem.

limites

o que a skill não faz, em nenhum nível.

A skill não muda tese, autoria nem conclusões: quem decide é o humano. Ela não busca fontes; marca o que não foi checado.

receitas

o desenvolvimento roda com nix e just. cada linha é uma receita do justfile.

just opencode

Run OpenCode with this repo's configuration (expects a llamacpp server at 127.0.0.1:8080).

just opencode-qwen

Serve Qwen3.6-27B (Q4_K_M) with llama.cpp CUDA and run OpenCode against it.

just opencode-status

Health-check the local llamacpp server.

just opencode-stop

Stop the llamacpp server on port 8080.

just opencode-logs

Tail the llamacpp log.

just nix-check

Validate flake.nix and flake.lock without building.

just nix-update

Update flake.lock.

just fmt

Format the justfile.

just site

Build the site into site/dist/ in picasso's gleam-website toolchain: content, tests, prerender.

just site-serve

Build the site and serve it on http://localhost:8000.

just pins

Check that every picasso pin (flake.lock's gleam-website and code-graph, to-pdf.sh, tools.lock) is the forks/picasso submodule's revision.

just saramago

Lint prose against Saramago's punctuation: no dash, quotes, ? ! ; : or ellipsis.

just saramago-check

Self-test of the Saramago linter: the fixture in his manner passes, the plain one trips every rule.

just picasso-init

The pinned picasso (forks/picasso), whose code graph the site publishes beside this repo's: once per clone.

just figure-init

The pinned Archify (vendor/archify, sparse to archify/): once per clone. Not part of the plugin.

just figure

Draw every docs/archify/<slug>.json to docs/img/<slug>.png, and its English twin docs/archify/en/<slug>.json to docs/img/en/<slug>.png: Archify validates and checks it (finalize),

just _figure-lock

The inputs of each figure (its source, the look, the crop, the Archify pin), one line per slug (en/<slug> for a twin).

just figure-check

Cheap and offline: each docs/archify/<slug>.json has its PNG, and both match the last just figure.

just route

Basic quality gate: justfile parses, required files exist, toolchain pins agree, linters self-test.

just tools-fetch

The plugin's and the routing skill's static binaries (picasso labs/ptbr-tools) at picasso REV: build, copy, write tools.lock.

just tools-check

Each committed binary matches tools.lock (the rev there is the source of truth: tools-fetch writes it, nothing else reads it).

just plugin-check

Check the Claude Code plugin: manifests parse, every skill link resolves, the version has a CHANGELOG entry.

just release-due

What ships in the plugin changed since the last v* tag: lists the files and exits 1; installs keep the old text until a release.

just plugin-smoke

Install the plugin from this checkout into an empty Claude Code config and check what a third party gets.

just plugin-eval

Run the plugin's eval cases on your own Claude login, once each: just plugin-eval --case 'estrito*'.

just pdf-bench

What the .pdf output downloads and builds on a machine with Nix and no pandoc, timed into an empty store.

just release

Release X.Y.Z in two runs: a chore/release-vX.Y.Z PR (plugin.json, CHANGELOG), then, after its merge, the tag on main.

just release-check

The tag a release pushes must be the plugin's version: just release-check v0.2.0 (release.yml runs it).

just reading-time

Write each README's reading time (the plugin's calculator) under its language line.

just _reading-badge

The reading-time badge of one README: the calculator's minutes in a shields.io badge, linked to the section that explains it.

just labels

Create or update the GitHub labels from the tables of ISSUE_LABELS.md (needs gh logged in).

just ext-build

Chrome extension: build into extension/dist.

just ext-build-firefox

The same extension for Firefox (128+), into extension/dist-firefox.

just ext-ollama

Serve a model with Ollama for the extension's provider "Ollama (local)", at 127.0.0.1:11434.

just ext-ollaya

Serve a decision model with Ollaya for the extension's provider "Ollaya (local)", at 127.0.0.1:11435.

just ext-test

Chrome extension: type check (tsconfig has noEmit) and unit tests.

just ext-e2e

Chrome extension: end-to-end tests (Playwright) against extension/dist-test.

just whitepaper

The whitepaper, in pt-BR and English: docs/whitepaper/{pt-BR,en}.md -> pandoc (docs/whitepaper/template.tex,

just whitepaper-check

Cheap and offline: both whitepapers exist and keep to the 8-page cap.

just doi

The DOIs Zenodo minted for ptbr-writer, newest first, from Zenodo's public API (no token):

just node-check

The node on PATH has the fixes of the October 2026 security release (#83): the minimum of its line,

figuras

os desenhos do README, como páginas que se abrem e se leem sozinhas. cada uma sai de um arquivo em docs/archify.

• Fluxo do plugin do Claude Code: um pedido ptbr
• Fluxo da extensão de navegador: do campo ao sublinhado
• Fluxo do modelo local (LLM ou SLM): baixar sob demanda, muito experimental
• De onde vem o .pdf

e o grafo do código deste repositório, gerado a cada build: grafo do código (busca, zoom e comunidades; sai do code-graph do h0ffmann/picasso). os nós que usam o picasso levam ao grafo do picasso, no commit que este repositório fixa.

ELI5

pedidos reais, gerados pelo próprio plugin: o prompt, o PDF que ele escreveu e os tokens que gastou.

awesome-ptbr-writer

outros projetos para quem escreve texto técnico em português. o primeiro é o PTC original, de onde este fork vem; os outros foram achados numa lista curada, que vai ao lado.

• kayquer/portugues-tecnico-controlado o original: 8 regras de português técnico controlado, inspiradas no ASD-STE100, com modo bilíngue EN/PT fonte
• fabricioctelles/skills skill "humanizar" para agentes: remove padrões de texto de IA em português do Brasil fonte
• vale-cli/vale linter de prosa com estilos próprios, base para regras de estilo pt-BR na documentação fonte
• languagetool-org/languagetool corretor gramatical e de estilo com suporte a pt-BR, local ou via API fonte
• hunspell/hunspell motor de verificação ortográfica que usa dicionários pt-BR fonte
• ajdavidl/Portuguese-NLP índice de recursos e ferramentas de PLN para português, com foco em pt-BR fonte

roadmap: prontidão para produção

o objetivo: outro repositório instala a skill e mantém sua documentação técnica em PT-BR e EN gastando menos tokens, sem reescrever regras de estilo no próprio código.

1. em andamento

   SKILL.md

   regras PTW e níveis de rigor; as regras ainda estão marcadas como em desenvolvimento · SKILL.md

2. em andamento

   evals

   um caso de regressão por regra científica, escrito e ainda não rodado por um harness ⚠ · evals/cientifico.md

3. em andamento

   skill científica

   skill própria para texto científico, com regras CIE; casos de regressão em evals/cientifico-cie.md, escritos e ainda não rodados ⚠ · skills/cientifico/SKILL.md

4. feito

   roteamento

   route escolhe a skill e o nível antes de carregar uma skill, para que só ela entre no contexto · skills/ptbr-routing/routes.tsv

5. feito

   plugin

   plugin do Claude Code: instalado com um comando, na versão da release (v0.3.0); o OpenCode lê o SKILL.md direto · plugins/ptbr-writer/.claude-plugin/plugin.json

6. feito

   distribuição

   uma versão para código e plugin: a tag vX.Y.Z vira release (release.yml) e outros repositórios fixam o marketplace nela; v0.3.0 é a versão oficial · CHANGELOG.md

7. em andamento

   extensão do Chrome

   extensão de navegador que sublinha num campo de texto o que o nível pede para mudar; dev local, carregada sem compactação, ainda fora da Chrome Web Store; também roda no Firefox 128+ · extension/build.mjs

8. em andamento

   FOSS (Ollama, Ollaya)

   providers locais de código aberto na extensão, sem chave e sem nuvem: o Ollama (MIT) escreve a troca e o Ollaya (Apache-2.0) aponta a regra ou escolhe o estilo; latência e acerto em pt-BR não medidos ⚠ · extension/src/providers.ts

9. planejado

   retórica

   skill de retórica a partir do Fédon e do Fedro, de Platão, e do Phaedrus de Robert M. Pirsig; só o esqueleto existe, sem regras · skills/retorica/SKILL.md

10. em andamento

    opencode

    skills e plugin do ask-levels para o OpenCode, instalados por tag com scripts/install-opencode.sh; testado no OpenCode 1.19.0 (skills e instrução), a ferramenta question não foi medida ⚠; o script entra na próxima release ⚠ · scripts/install-opencode.sh