Redação orientada por spec: por que supera o ChatGPT puro

Redigir documentos complexos e regulados — políticas, narrativas de controle, relatórios CAPA, pacotes de autorização — com uma interface de chat genérica é tentador: você cola um prompt e recebe um rascunho. O problema é consistência, estrutura e conformidade. Prompts pontuais não impõem fluxos de trabalho, não rodam verificações e não dão ao modelo uma forma de se corrigir. A redação orientada por spec no Rakenne inverte isso: os skills definem fluxos de trabalho, carregam referências e usam ferramentas de extensão para o agente validar, corrigir e manter a qualidade. Este artigo explica por que essa abordagem é muito melhor do que “prompting comum no ChatGPT” e mostra exemplos concretos e comparações de saída.

Por que orientado por spec vence prompting ad hoc

Em resumo: a redação orientada por spec dá ao LLM uma spec (workflow + referências + estrutura) e ferramentas (extensões) para checar e se corrigir. Prompting puro não.

Como os skills Rakenne implementam redação orientada por spec

No Rakenne, cada skill é um pacote pequeno que o agente pi pode acionar. Em geral inclui:

1. SKILL.md — Nome, descrição (quando usar) e um workflow: passos ordenados (ex.: definir escopo → carregar referência → redigir → validar).
2. Referências — Arquivos Markdown (normas, listas de critérios, schemas) que o agente carrega quando o skill está ativo, para o rascunho ficar alinhado à autoridade.
3. Ferramentas de extensão (opcional) — Ferramentas TypeScript registradas no agente (extension.ts) que rodam checagens determinísticas no documento (cobertura, gates lógicos, completude). O agente as chama, lê o resultado e revisa até as checagens passarem.

O contexto do projeto (tipo de documento, domínio, glossário) fica em AGENTS.md no workspace, então toda conversa naquele projeto tem o mesmo escopo.

Abaixo usamos skills reais do Rakenne para ilustrar workflows, verificações e auto-correção, e depois comparamos as saídas.

Exemplo 1: Política de medicamentos HIQA (workflow + referência)

Skill: HIQA Designated Centre Medication . Redige uma política de medicamentos para centros designados na Irlanda alinhada aos padrões HIQA.

Workflow no skill:

1. Definir escopo — Tipo de centro, autoadministração vs. medicamentos administrados, procedimentos existentes.
2. Carregar referência — Ler references/hiqa-nssbh.md para o NSSBH Theme 3 (cuidado seguro, segurança de medicamentos).
3. Redigir — Produzir uma política cobrindo: pedido, armazenamento, prescrição, administração, autoadministração, fichas MAR, erros/incidentes, descarte, treinamento, revisão.
4. Referência cruzada — Alinhar com notificação de incidentes e planejamento de cuidado/apoio.

O arquivo de referência detalha os oito temas HIQA e expectativas de governança para o agente não chutar.

Rakenne (com o skill): O agente segue o workflow, puxa o NSSBH Theme 3 e textos de governança relacionados da referência e produz uma política com seções nomeadas (pedido, armazenamento, administração, erros, treinamento etc.) e alinhamento explícito a “NSSBH Theme 3” e contexto “designated centre”.

ChatGPT puro: Você pode pedir: “Escreva uma política de medicamentos para uma casa de repouso na Irlanda.” O modelo costuma devolver uma “política de medicamentos” genérica aplicável em qualquer lugar: “revisão periódica”, “equipe apropriada” vagos, sem vínculo com HIQA ou NSSBH. Não há garantia de que o Theme 3 (ou armazenamento, MAR, erros, descarte) seja coberto de forma sistemática nem passo integrado de “carregar referência e depois redigir”.

Exemplo 2: Narrativas de controle SOC 2 (workflow + ferramentas de validação)

Skill: SOC 2 Control Narrative Author . Monta documentação SOC 2 com narrativas de controle, mapeamento TSC e placeholders de evidência.

Workflow:

1. Escopo — Quais categorias TSC (Security sempre; opcionalmente Availability, PI, Confidentiality, Privacy).
2. Narrativas de controle — Para cada critério no escopo (CC1–CC9, A1, PI1, C1, P1–P8): narrativa + referência de evidência.
3. Evidência — Adicionar placeholders de evidência por narrativa.
4. Validar — Rodar as extensões e corrigir até passarem.

Ferramentas de extensão:

• check_trust_services_criteria_coverage — Garante que cada critério TSC no escopo tenha narrativa e referência de evidência; sinaliza critérios não mapeados.
• soc2_narrative_reliability_check — Aplica o Rubric SOC 2 Reliability: sinaliza frases vagas (“revisado periodicamente”, “a gestão mantém a segurança”) e exige especificidade (quem, como, quando, onde, tecnologia nomeada).

Rakenne (com o skill): O agente redige as narrativas e roda as duas ferramentas. Se CC4 não tem referência de evidência ou a narrativa diz “o acesso é revisado periodicamente”, as ferramentas retornam FAIL com achados concretos. O agente revisa (adiciona evidência, especifica “trimestralmente pela equipe de segurança via relatório de acesso IdP”) e reexecuta até PASS.

ChatGPT puro: Você pede “narrativas de controle SOC 2 para Security”. Muitas vezes recebe texto que fala em “controles” e “políticas” mas não cobre sistematicamente CC1–CC9, não mapeia cada critério a narrativa + evidência e usa exatamente o tipo de linguagem vaga que o rubric rejeita (“revisado periodicamente”, “controles apropriados”). Não há checagem automatizada; lacunas e vagueza só aparecem na preparação para auditoria.

Exemplo 3: Relatório CAPA (workflow + gates lógicos)

Skill: CAPA Report . Relatórios de ação corretiva e preventiva para não conformidades (ISO 9001 / ISO 13485).

Workflow:

1. Não conformidade — Achado, escopo, contenção.
2. Causa raiz — Completar uma seção 5 Whys (Why 1 … Why 5). Não propor ações até isso estar feito.
3. Gate — Rodar root_cause_logic_gate no documento. Só prosseguir quando passar.
4. Ações corretivas / preventivas — Ações, responsáveis, prazos.
5. Implementação — Registrar conclusão.
6. Verificação de eficácia — Definir uma data futura para verificação. Rodar verification_of_effectiveness_timer antes de fechar; não fechar até passar.

Ferramentas de extensão:

• root_cause_logic_gate — Verifica se existe seção Causa raiz / 5 Whys e pelo menos cinco níveis why distintos. Falha se o documento pula para “soluções” antes de um 5 Whys adequado.
• verification_of_effectiveness_timer — Garante que exista data de verificação de eficácia e que seja no futuro. Evita fechar a CAPA antes da verificação estar agendada.

Rakenne (com o skill): O agente redige a não conformidade e a causa raiz. Se tiver só três níveis why ou pular para “vamos treinar a equipe”, o gate retorna FAIL com “Níveis why detectados: 3/5. Complete uma análise 5 Whys antes de propor soluções.” O agente adiciona Why 4 e Why 5, reexecuta o gate e segue para as ações. Antes de fechar precisa definir uma data de eficácia futura; se colocar “2025-01-15” e hoje for depois, o timer falha e o agente precisa definir uma data futura.

ChatGPT puro: Você pede “uma CAPA para um achado de auditoria sobre controle documental”. Muitas vezes recebe um parágrafo de causa e uma lista de ações de uma vez — sem 5 Whys obrigatório, sem gate e sem checagem de que a verificação de eficácia está agendada no futuro. O resultado parece plausível mas não passaria em uma revisão ISO 9001/13485 rigorosa.

Exemplo 4: Pacote de autorização FedRAMP (workflow + checagem de completude)

Skill: FedRAMP Authorization Package . SSP, anexos, SAP, SAR, POA&M.

Workflow (resumido): Categorizar sistema → descrição do sistema → limite de autorização → fluxos de dados → implementações de controles (com referência de baseline) → anexos SSP → Validar com fedramp_package_completeness_check. Corrigir e reexecutar até PASS. Sub-workflows separados para SAP/SAR e POA&M, com a mesma ferramenta usada para sinalizar controles faltando, seções de anexo faltando ou itens POA&M sem plano de remediação ou vencidos sem justificativa.

Rakenne (com o skill): O agente segue o workflow, carrega as referências de baseline e anexos, redige as seções e roda a checagem de completude. Lacunas (ex.: controles não implementados sem justificativa, seção PIA faltando) são reportadas; o agente preenche e revalida.

ChatGPT puro: Você pede “um SSP FedRAMP para um produto SaaS”. Recebe um texto longo que pode parecer um SSP mas não segue a estrutura FedRAMP real, a implementação controle a controle nem a checklist de anexos. Não há como verificar cobertura da baseline ou completude dos anexos; você descobre as lacunas depois manualmente.

Resumo: mesmo modelo, resultados diferentes

O LLM subjacente pode ser o mesmo. A diferença está em como ele é usado:

• Prompting puro: Uma vez ou ida e volta sem fluxo fixo, sem referências carregadas pelo skill, sem ferramentas de validação. A saída é genérica, a estrutura desvia e o modelo não consegue se “checar e corrigir” de forma confiável.
• Orientado por spec no Rakenne: Os skills definem workflow, referências e extensões. O agente segue o workflow, carrega as referências certas, redige e então roda ferramentas que retornam PASS/FAIL e achados concretos. Corrige até as checagens passarem e mantém a estrutura e qualidade desejadas.

Para documentos complexos e regulados — políticas, narrativas de controle, CAPAs, pacotes de autorização — redação orientada por spec com workflows e ferramentas de validação não é um pequeno upgrade; é a diferença entre “talvez bom o suficiente” e “pronto para auditoria e repetível”.

Para experimentar: escolha um skill Rakenne para o seu domínio, crie um projeto com esse workflow e compare a saída estruturada e validada com o que você obtém de um único prompt no ChatGPT.