STYLE-GUIDE | Convenções Práticas do Vault

governanca style-guide

Guia de uso prático para quem escreve e lê no vault Colliers × Costal. Complementa o MEMORY-CONTRACT com exemplos concretos do que é bom e do que é ruim. Em conflito, o MEMORY-CONTRACT prevalece.

---

1. Nomenclatura de arquivos

Regra geral

Tipo	Padrão	Exemplo
Documentos datados (atas, briefs trimestrais, eventos)	YYYY-MM-DD_descricao-curta.md	2026-04-17_kickoff-operacional_meeting_summary.md
Documentos perenes (camadas canônicas, missões, briefs vivos)	nome-descritivo.md	decisoes.md, missao-rafael.md, visao-geral.md
Folder notes (índices de pasta)	<nome-da-pasta>.md, ao lado da pasta	02-costal.md ao lado de 02-costal/
Templates	_templates/*.md	_templates/meeting.md

Sempre minúsculas, hífens como separador, sem acentos, sem espaços. Exceção: arquivos top-level em maiúscula (HOME, README, TASKS, MEETINGS, DEFINICOES, STYLE-GUIDE, MEMORY-CONTRACT, AXIOS-HANDOFF).

Quando usar data no nome?

Critério: o documento é pontual (tem data de ocorrência) ou perene (evolui ao longo do tempo)?

Use YYYY-MM-DD_:

• Atas de reunião — data da reunião
• Briefs executivos trimestrais — data da produção
• Snapshots/relatórios pontuais
• Entregáveis versionados de uma fase
• Deliverables com marco temporal claro

NÃO use data:

• Camadas canônicas: decisoes.md, riscos.md, gaps.md, dependencias.md
• Missões de pessoas: missao-gabriel.md
• Documentos de governança: MEMORY-CONTRACT.md, visao-geral.md, stakeholders.md
• Specs vivas, roadmaps vivos, dashboards
• Folder notes

Sufixos semânticos para atas

Atas de reunião seguem YYYY-MM-DD_topico_<sufixo>.md:

Sufixo	Conteúdo	Audiência
_meeting_minutes	Transcrição/notas brutas, exaustivo	Anouk-interno
_meeting_summary	Resumo estruturado (key points, decisions, action items)	Anouk-interno
_summary_brief	Brief executivo (1–2 páginas, narrativo)	Internal + client quando relevante
_brief	Brief curto (variação sem summary_)	Conforme caso

---

2. Folder notes

Padrão adotado (Onda 3 — 2026-04-22)

Cada pasta de conteúdo tem um folder note — um arquivo com o nome da pasta, ao lado dela (no nível pai).

Exemplo correto:

00-projeto.md                  ← folder note da pasta 00-projeto
00-projeto/
├── canonico.md                ← folder note de canonico/
├── canonico/
│   ├── decisoes.md
│   └── ...
└── governanca.md              ← folder note de governanca/

NÃO use: _index.md dentro da pasta. Esse era o padrão antigo; foi migrado na Onda 3.

Quando dois folder notes colidiriam de nome

Se duas pastas-irmãs têm o mesmo nome (ex: 01-colliers/meetings/ e 02-costal/meetings/), os folder notes são prefixados pela pasta-mãe:

• 01-colliers/colliers-meetings.md
• 02-costal/costal-meetings.md

---

3. Frontmatter

Frontmatter mínimo obrigatório

Todo documento deve ter pelo menos:

---
title: "Título curto do documento"
updated: 2026-04-22
owner: quem-mantem@email.com
---

Frontmatter estendido por tipo

Atas de reunião (em */meetings/* ou 00-projeto/reunioes/*):

---
title: "Kickoff operacional Costal"
date: 2026-04-17
participants: [Igor Reginato, Rafael Rossetto, Marcos Eduardo]
empresa: [costal]
tags: [meeting, kickoff]
publish: [internal]
---

Specs técnicas (em */specs/*):

---
title: "Agente Atlas — orçamentação"
type: spec
agente: atlas
area: 02-orcamentacao-propostas
status: draft | review | approved
owner: gabriel@anoukpartners.com
publish: [internal]
---

Agentes (em */agentes/*/):

---
title: "Atlas — Orçamentação"
codinome: atlas
area: 02-orcamentacao-propostas
dono_humano: antonio@anoukpartners.com
status: design | piloto | producao
onda: 1
publish: [internal, client]
---

Camada canônica (em 00-projeto/canonico/*):

---
title: "Riscos do Projeto"
canonical: true
updated: 2026-04-21
owner: pedro.villa@anoukpartners.com
publish: [internal]
---

Folder notes:

---
title: "Pasta X — Função Y"
updated: 2026-04-22
publish: [internal]
---

Campo publish

Controla onde o documento aparece (ver publish-contract):

• [internal] — só wiki interna Anouk
• [internal, client] — interna + wiki cliente (Costal/Colliers)
• [internal, client, board] — todas as 3 wikis
• none — bloqueia publicação mesmo com frontmatter de pasta contrário

---

4. Marcação epistêmica

Regra: todo item relevante deve estar marcado explicitamente como fato, hipótese, premissa ou gap.

Marcador	Significado	Exige
[fato]	Verificado, com fonte rastreável	Fonte linkada
[hipótese]	Plausível, ainda não validado	Dono e critério de validação
[premissa]	Aceito como verdade operacional até prova em contrário	Revisão periódica
[gap]	Informação faltando	Dono e prazo

Exemplo bom:

- [fato] Kickoff ocorreu em 17/04/2026. Fonte: [[02-costal/meetings/2026-04-17_kickoff-operacional_meeting_minutes|minutes]].
- [hipótese] Orçamentação tem ganho esperado de 87%. Precisa validação com base real (owner: Antonio, prazo: 2026-05-10).
- [premissa] Sienge é o ERP transacional definitivo da Costal até 2027.
- [gap] Blueprint da camada de ingestão. Owner: Gabriel. Prazo: 2026-05-01.

Exemplo ruim (inferência implícita):

- O ganho de orçamentação é de 87%.
- A Costal vai usar Sienge até 2027.
- Falta o blueprint da camada de ingestão.

A diferença importa quando um agente de IA ou outra pessoa lê: sem marcação, ele não sabe se isso é decisão tomada, aposta ou buraco.

---

5. Wikilinks

Preferências

Preferir short form quando o filename for único:

• [[decisoes]] em vez de [[00-projeto/canonico/decisoes]] — se decisoes.md for o único arquivo com esse nome no vault.

Usar path completo quando:

• Houver ambiguidade (ex: dois arquivos meetings.md em lugares diferentes)
• For útil explicitar o contexto em uma tabela de referência

Alias com | quando quiser texto diferente:

• [[decisoes|Log de decisões]] → o link mostra “Log de decisões” mas aponta para decisoes.md

Em tabelas markdown — o pipe precisa ser escapado:

• | [[decisoes\|Decisões]] | ... (note o \ antes do |)

Antipadrão

Evitar links quebrados. Se referenciar algo que ainda não existe, marcar claramente:

Ver [[futuro:nome-planejado|planejamento]] — ainda não criado, previsto para 2026-05.

Assim o Axios não trata como erro de referência.

Âncoras internas

Para apontar para uma seção específica: [[arquivo#seção|seção]]

Exemplo: [[canonico/riscos#r-001|Risco R-001]]

---

6. Tags padrão

Mínimo por documento:

• Frente: #colliers e/ou #costal (pode ter ambos)
• Tipo: #meeting, #spec, #agente, #decisao, #risco, #gap, #dependencia, #brief

Tags temáticas úteis:

• #governanca — documentos de governança, operação, auditoria
• #pesquisa — benchmarks, referências externas
• #todo — itens pendentes (alimenta _bases/tasks-abertas)
• #draft — em rascunho, não revisado
• #sensivel — bloqueia publicação em wiki pública
• #board — material executivo para board

---

7. Tamanho e escopo de arquivos

Regra prática

• Atas: sem limite. Conteúdo bruto é bom.
• Specs: mira ≤ 2 páginas por tópico; se crescer, quebrar em subarquivos.
• Camadas canônicas: cada entrada é uma linha da tabela. Se uma decisão precisa de contexto longo, criar arquivo separado e linkar.
• Missões: 1–2 páginas.
• Folder notes: índice + breve descrição do que tem na pasta.

Quando um arquivo está crescendo demais

Sinal: >300 linhas ou múltiplas seções que poderiam viver independentes.

Ação: quebrar em subarquivos e manter o original como hub de navegação.

---

8. Campo publish por caminho — cheat sheet

Resumo do publish-contract:

Pasta típica	Default
00-projeto/canonico/*	[internal]
00-projeto/governanca/visao-geral.md, glossario.md	[internal, client]
00-projeto/assessment/* (maioria)	[internal, client]
00-projeto/board/*	[internal, client, board]
02-costal/plano/*, 02-costal/agentes/*	[internal, client]
*_summary_brief.md em meetings	[internal, client]
02-costal/pesquisa/*, 01-colliers/*	[internal]
agentes-core/axios/* (exceto memory/)	[internal]
Arquivos com tag #sensivel	bloqueado (denylist absoluta)

---

9. Antipadrões comuns (evitar)

Documento sem dono

❌ Arquivo sem campo owner no frontmatter. ✅ Todo arquivo tem dono humano identificado.

Inferência implícita

❌ “A Costal vai crescer 80% no próximo trimestre.” ✅ “[hipótese] Projeção de crescimento 80% Q2/2026. Fonte: brief-board-2026-q2. Precisa validação com dados Sienge após go-live.”

Duplicar camadas canônicas

❌ Criar riscos-abril.md, riscos-maio.md etc. ✅ Continuar em riscos.md (canônico). Para snapshot histórico, usar agentes-core/axios/outputs/weekly-risks.md (derivado).

Link quebrado em tabela

❌ [[pasta/inexistente]] sem indicação. ✅ [[futuro:pasta/inexistente|A criar]] ou criar placeholder.

Ata sem promoção de sinais

❌ Ata registrada mas decisões/riscos/gaps da reunião não subiram para as camadas canônicas. ✅ Rodar o checklist de promover sinais no mesmo dia.

Comunicação materialmente relevante só no Slack

❌ “Acabei de decidir que X. [Slack]” ✅ Registrar em decisoes.md antes de sair do Slack.

---

10. Revisão e atualização deste guia

• Owner: Pedro Villa
• Cadência de revisão: mensal ou quando uma nova convenção for adotada por 3+ pessoas
• Alterações: via commit direto com entrada em decisoes referenciando o que mudou

---

Ver também

• MEMORY-CONTRACT — regras canônicas do vault (peso maior)
• publish-contract — regras de publicação por path
• Runbooks operacionais
• Guia Obsidian para o time
• glossario — terminologia do projeto