Writing Voice & Skill Overhaul — Design Spec

Context

The write-article skill and writing-voice.md guide produce technically correct articles that follow the rules but feel AI-generated. The first automated post (requestAnimationFrame, 2026-03-19) revealed specific gaps: the output is too polished, voice markers feel placed rather than organic, personal opinions are absent, transitions are formulaic, and the personal context feels forced. This overhaul addresses these gaps by restructuring both the voice guide and the skill workflow.

Problem Analysis

Comparing 5 hand-written posts against the automated output revealed that rules produce rule-following behavior. The current guide says “use rhetorical questions to engage” — so the AI places rhetorical questions at transition points. Miguel uses rhetorical questions because he is genuinely working through a problem. The motivation matters, not just the surface pattern.

Key gaps:

  • Thinking-out-loud quality: Natural posts have winding asides, parenthetical tangents, confessional moments
  • Opinion density: Natural posts embed strong takes mid-explanation; automated output plays it safe
  • Variance: Natural posts have extreme paragraph length variance (1-sentence to 8+ sentences); automated output defaults to uniform 4-5 sentence paragraphs
  • Transitions: Natural posts sometimes start sections abruptly; automated output always bridges smoothly
  • Headers: Natural headers are playful (“E o que é o tal DDD?”, “Dores de cabeça pelas abstrações”); automated headers are outline-style (“O Problema:”, “A Solução:”)

Changes

1. writing-voice.md — Four New Sections

1a. Voice Library

15-20 real fragments from published posts, organized by rhetorical function:

  • Confession: Admissions of ignorance or past failure. Use within first 3 paragraphs to establish vulnerability.
    • “Eu ja tinha estudado a teoria e até comecei o livro azul algumas vezes, mas nos vários momentos, não investi energia suficiente”
    • “Para ser honesto, se estivéssemos pensando que o nosso usuário está esperando pelo upload…”
  • Thinking-aloud: Working through a problem in real time. Use at section transitions, after dense code.
    • “Poderíamos sim fazer o processo todo para cada arquivo antes de chamar o próximo, mas queria evidenciar o problema…”
    • “Uffa, então nesse momentos também podemos representar esse modelo não só como um diagrama mas também como uma ideia”
  • Opinion: Strong stances embedded mid-explanation. Never in standalone opinion sections.
    • “temos que evitar abstrações tentando prever futuros ‘reusos’”
    • “temos que encontrar uma maneira de comunicarmos esse modelo entre todas as partes envolvidas”
  • Self-correction: Showing wrong thinking, then correcting. After showing code, critique it, then show corrected version.
    • “nesse caso eu estava tentando prever um pouco os próximos passos, então vamos voltar atrás”
    • "’É só adicionar uma linha’, pensei eu.”
  • Reader-winking: Acknowledging the reader’s state. Use in openings or when topic gets dense.
    • “ou apenas está passando por aqui pra ver onde vou chegar”
    • “Como já dito, a implementação dos métodos não são triviais e estão no repositório para consulta”
  • Exhaustion/breath: Cognitive pauses at section boundaries.
    • “Uffa,”
    • “Bom, de certa forma…”
    • “Certo,”

Instruction: “Use these fragments as templates for tone and rhythm, not as text to copy. They show the emotional register and sentence shape for each situation.”

1b. Anti-Pattern Catalog

AI Pattern (AVOID) Miguel’s Version Why
“Vem comigo que essa história é boa” Just start telling the story Never promise entertainment
“Para entender X, precisamos entender Y” “E como representar essa abstração?” Ask a question or just start the next topic
“Essa solução é genérica — funciona para qualquer campo” “Se amanhã quiséssemos focar no campo de Start time…” Show flexibility through hypothetical
“Neste artigo vamos discutir…” Start with the personal situation No meta-commentary about the article itself
Consistent 4-5 sentence paragraphs Mix of 1-sentence and 8+ sentence paragraphs Variance signals human writing
Perfect chronological debugging narrative Include dead ends, confusion, time wasted Show the mess
Outline-style headers (“O Problema:”, “A Solução:”) Conversational headers (“E o que é o tal DDD?”, “Dores de cabeça”) Headers should sound like talking

1c. Variance Requirements

Minimum thresholds per article:

  • 1 single-sentence paragraph
  • 1 paragraph with 7+ sentences of continuous reasoning
  • 1 abrupt section transition (no bridge)
  • 1 “Pensei eu” / self-correction moment
  • 1 deliberate incompleteness (“não vou me aprofundar”)
  • 3 opinion-bearing sentences
  • 1 confession/admission within the first 20% of the article

1d. Header Style

Headers must be conversational or elliptical, never outline-style. Examples from real posts:

  • “E o que é o tal DDD?” (not “O que é DDD”)
  • “Objetos valorosos” (not “Value Objects”)
  • “Juntos somos mais fortes” (not “Agregados”)
  • “Dores de cabeça pelas abstrações” (not “Problemas com Abstrações”)

2. SKILL.md — Workflow Changes

2a. Brainstorm Phase: Add Extraction Questions (5-9)

After existing questions (audience, narrative, depth, series):

  1. Frustration: What annoyed you about this topic? A tool that misbehaved? Docs that failed you?
  2. Wrong assumptions: What did you think was true before working on this? What surprised you?
  3. Tangential thoughts: Is there something related but off-topic you keep thinking about?
  4. Hot take: Do you have a strong opinion about some aspect? Something the community gets wrong?
  5. The “Pensei eu” moment: Walk me through the exact sequence when your assumption broke.

Rule: “These answers become raw material that MUST appear in the draft. Frustrations show up as-is, not sanitized. Wrong assumptions are shown first, then the correction.”

2b. Structure Phase: Story Arc, Not Outline

Replace “Propose an article outline with H2 sections” with:

“Propose a story arc:

  1. Opening confession/context (what was Miguel dealing with)
  2. First wrong approach (where he went wrong)
  3. Moment of realization
  4. Deep dive (which may meander)
  5. Opinionated takeaway
  6. Honest closing (what he still doesn’t know)

Only after the user approves the arc, propose H2 section headers. Headers must sound like Miguel’s actual headers — conversational or elliptical, never outline-style.”

2c. Add Phase 4.5: Roughen

Between Write and Translate:

  1. Break one smooth transition — replace with abrupt start, “Bom,” or single-word sentence
  2. Add one tangent — 2-3 sentences exploring a branch, then “mas não quero entrar muito nisso agora”
  3. Vary paragraph lengths — find three uniform paragraphs, merge two or split one
  4. Strengthen one opinion — add “com certeza,” “sinceramente,” or explicit criticism
  5. Add one self-doubt — follow confident statement with “pelo menos é o que acredito nesse momento”
  6. Remove one perfect explanation — make slightly incomplete, add aside acknowledging not everyone may follow

2d. Integrated Humanizer Checklist (runs before Roughen)

The LLM checks its own output against:

  1. Transition uniformity: >2 consecutive sections start with rhetorical question or logical bridge? Break one.
  2. Opinion deficit: <3 opinion-marker sentences? Add opinions.
  3. Confession deficit: First 20% has no admission of ignorance/failure? Add confession.
  4. Paragraph variance: All paragraphs 3-6 sentences? Need 1-sentence and 7+ sentence variety.
  5. Self-correction deficit: No wrong-thinking-before-right? Add “Pensei eu” moment.
  6. Tangent deficit: Never starts and abandons a thought? Add one.
  7. Header style: Any outline-style headers? Rewrite conversationally.
  8. AI signposting: “Vem comigo,” “Vamos lá,” “Neste artigo vamos”? Remove.

2e. Translation Phase: Preserve Roughness

Add: “The English version should preserve awkwardness. If Miguel used a long winding sentence in Portuguese, keep it long and winding in English. Do not split rough sentences into cleaner English. Preserve or amplify rough edges.”

Files to Modify

File Action
.claude/skills/write-article/writing-voice.md Add Voice Library, Anti-Pattern Catalog, Variance Requirements, Header Style sections
.claude/skills/write-article/SKILL.md Add brainstorm Q5-Q9, change Structure to story arc, add Phase 4.5 Roughen, add humanizer checklist, update Translate phase

Verification

After implementing changes:

  1. Re-run the write-article skill on the same requestAnimationFrame topic to produce a new draft
  2. Compare the new draft against the original automated draft and a hand-written post
  3. Check that the humanizer checklist passes
  4. Check that the anti-pattern catalog items are absent
  5. Check that variance requirements are met