📋 Governança de Documentação — finops-docs-portal

Toda a interação do usuário de negócio com o ciclo de vida da documentação é realizada 100% via Slack. Não é necessário abrir o repositório, editar YAML ou criar Pull Requests manualmente.

1. Fluxo do Ciclo de Vida (Visão de Negócio)

graph LR
    %% Início e Criação
    A((Início)) --> B[Slack: /doc-new]
    B --> C[Publicação Automática]

    %% Monitoramento e Notificação
    C --> D{Monitor de Saúde}
    D -- Documento Vencendo --> E[Slack: Alerta de Revisão]
    D -- Documento Vencido --> F[Slack: Alerta Público]

    %% Ações de Manutenção
    E --> G{Decisão do Dono}
    F --> G

    G -- Revisar: /doc-renew --> C
    G -- Deletar: /doc-archive --> H[Arquivamento Seguro]

    %% Gestão de Órfãos
    D -- Sem Responsável --> I[Slack: Alerta Admin]
    I --> J[Atribuição de Novo Dono]
    J --> C

2. Comandos Slack

A interface de operação é 100% via Slack. Os comandos abaixo conectam o usuário ao repositório de forma transparente.

Comando	Quem usa	O que acontece
`/doc-new <tipo> "<título>"`	Qualquer membro do time	Cria e publica um novo documento a partir do template escolhido
`/doc-renew <nome-do-doc>`	Dono do documento	Renova a data de revisão e reinicia o ciclo de monitoramento
`/doc-archive <nome-do-doc>`	Dono / Admin	Move o documento para área de arquivo morto com segurança

Tipos disponíveis para `/doc-new`

Tipo	Descrição
`adr`	Decisão de Arquitetura
`rfc`	RFC Técnica
`tech`	Guia Técnico / Golden Rules
`onboarding`	Guia de Onboarding FinOps
`workflow`	Fluxo de Processo
`serverless`	Otimização / Incidente Serverless
`proposal`	Proposta
`cost`	Gestão de Custos de Cloud
`policy`	Política de Custos
`onprem`	Gestão OnPrem (Compras e Contratos)

3. Matriz de Canais Slack

Todas as notificações são enviadas via @grupoboticario/slack-notification (finopping-core-services), garantindo padronização com os demais sistemas da plataforma.

Evento	Canal / Destino	Quando dispara
Nova documentação criada via `/doc-new`	`#gerencia-finops`	Imediatamente após publicação
Documento vencendo (15 dias antes)	🔔 DM direta para o Dono	D-15
Documento vencido	`#gerencia-finops`	No dia do vencimento (D-0)
Documento arquivado via `/doc-archive`	`#gerencia-finops`	No momento do arquivamento
Documento sem dono válido	`#gerencia-finops`	Na próxima execução do monitor

4. Contrato de Metadados

Todo documento possui um cabeçalho de metadados que alimenta o Monitor de Saúde. O usuário não precisa preencher este cabeçalho manualmente — ele é gerado automaticamente pelo comando /doc-new a partir do template escolhido.

Campo	O que representa	Quem define
`owner`	ID Slack do responsável pela documentação	Usuário que executou `/doc-new`
`last_review`	Data da última revisão	Atualizado pelo `/doc-renew`
`review_period`	Prazo de revisão em dias (90 ou 365)	Definido pelo tipo do template
`criticality`	Importância: `high` ou `low`	Definido pelo tipo do template

5. Regra de Arquivamento Seguro

O comando /doc-archive nunca apaga um documento. Ele move o arquivo para uma área de arquivo morto (/archive), preservando todo o histórico no Git, mas removendo o documento da visualização principal do portal.

/doc-archive → status: deprecated → Movido para /archive → Notificação no canal

O histórico completo permanece rastreável e auditável a qualquer momento.

6. Catálogo de Templates Disponíveis

Estes modelos são a base para qualquer documento criado via /doc-new. Cada template já vem com os metadados pré-preenchidos conforme o tipo escolhido. Clique em cada item para ver a estrutura e o cabeçalho de metadados.

📡 RFC Técnica — /doc-new rfc

Proposta formal de mudança técnica significativa para revisão e aprovação antes da implementação.

Pasta de destino: docs/proposals/ | Prazo de revisão: 90 dias | Criticidade: high

Seções: Motivação · Proposta Técnica · Alternativas · Impacto e Riscos · Plano de Implementação · Critérios de Aceite

---
owner: "@slack-user-id"
last_review: "YYYY-MM-DD"
review_period: 90
criticality: high
---

🎓 Guia de Onboarding FinOps — /doc-new onboarding

Orienta novos membros: ferramentas, acessos, rituais, processos e primeiras responsabilidades.

Pasta de destino: docs/tech/ | Prazo de revisão: 90 dias | Criticidade: high

Seções: Bem-vindo · Ferramentas e Acessos · Canais Slack e Rituais · Processos do Dia a Dia · Checklist dos Primeiros 30 Dias · Contatos

---
owner: "@slack-user-id"
last_review: "YYYY-MM-DD"
review_period: 90
criticality: high
---

📜 Política de Custos — /doc-new policy

Define regras de tagging, alocação, thresholds de alerta e processo de reclassificação de custos.

Pasta de destino: docs/cost-management/ | Prazo de revisão: 90 dias | Criticidade: high

Seções: Objetivo e Escopo · Regras de Tagging · Critérios de Alocação · Thresholds e Alertas · Processo de Reclassificação · Penalidades · Vigência

---
owner: "@slack-user-id"
last_review: "YYYY-MM-DD"
review_period: 90
criticality: high
---

📋 ADR — Decisão de Arquitetura — /doc-new adr

Registra decisões técnicas formais com contexto, opções avaliadas e implicações.

Pasta de destino: docs/adrs/ | Prazo de revisão: 90 dias | Criticidade: high

---
owner: "@slack-user-id"
last_review: "YYYY-MM-DD"
review_period: 90
criticality: high
---

🔧 Guia Técnico / Golden Rules — /doc-new tech

Padrões obrigatórios, boas práticas e configurações de repositório.

Pasta de destino: docs/tech/ | Prazo de revisão: 365 dias | Criticidade: low

---
owner: "@slack-user-id"
last_review: "YYYY-MM-DD"
review_period: 365
criticality: low
---

⚙️ Workflow / Fluxo de Processo — /doc-new workflow

Fluxos de dados, pipelines e processos automatizados com Lambdas e integrações.

Pasta de destino: docs/workflows/ | Prazo de revisão: 90 dias | Criticidade: high

---
owner: "@slack-user-id"
last_review: "YYYY-MM-DD"
review_period: 90
criticality: high
---

☁️ Serverless — Otimização / Incidente — /doc-new serverless

Otimizações, troubleshootings e aprendizados em infraestrutura Lambda/Serverless.

Pasta de destino: docs/serverless/ | Prazo de revisão: 90 dias | Criticidade: high

---
owner: "@slack-user-id"
last_review: "YYYY-MM-DD"
review_period: 90
criticality: high
---

☁️ Gestão de Custos de Cloud — /doc-new cost

Tendência, fechamento mensal, reclassificação e apuração de resultados.

Pasta de destino: docs/cost-management/ | Prazo de revisão: 90 dias | Criticidade: high

---
owner: "@slack-user-id"
last_review: "YYYY-MM-DD"
review_period: 90
criticality: high
---

🏢 OnPrem — Compras e Contratos — /doc-new onprem

Orçamento, solicitação de compra, negociação, PO, entradas de NF e gestão de contratos.

Pasta de destino: docs/onprem/ | Prazo de revisão: 90 dias | Criticidade: high

---
owner: "@slack-user-id"
last_review: "YYYY-MM-DD"
review_period: 90
criticality: high
---

7. Referências

Template de entrada: template-docs.md
Package de notificações: @grupoboticario/slack-notification (finopping-core-services)
Script de interface Slack: scripts/slack_interface.py
Motor de monitoramento: scripts/governance_engine.py
Script de validação CI: scripts/validate_metadata.py