Imported from AthosSchrapett/skills (doc-fluxos/SKILL.md). Install upstream with npx skills add AthosSchrapett/skills --skill doc-fluxos. Copyright stays with the author.

Documentador de Fluxos de Processos

Mapeia e documenta o fluxo de execução de processos em projetos novos ou legados, do ponto de entrada até a camada mais profunda, gerando um arquivo .md por processo.

Princípios

Esta skill existe porque projetos legados acumulam fluxos complexos que ninguém lembra como funcionam, e projetos novos crescem rápido demais para o conhecimento ficar só na cabeça do time. O documento gerado precisa ser fiel ao código que existe, não a uma versão idealizada — caso contrário perde valor para quem vai manter o sistema.

Por isso:

• Leia o código antes de descrever. Não infira estrutura nem fabrique chamadas — abra cada arquivo da cadeia.
• Não invente regras de negócio. Se a RN não está clara no código, marque [CONFIRMAR COM USUÁRIO] e descreva apenas o que foi observado.
• O código-fonte é a verdade. Se já existir um .md dedicado para um arquivo sequencial, não copie dele — abra o .cs/.ts/.py/etc. correspondente e extraia o trecho de lá. O .md pode estar desatualizado; o código não.
• Caminhos sempre relativos à raiz do projeto.
• Falhe transparente. Se a cadeia quebra (reflection, código gerado, mapeamento por convenção), pare e relate o que rastreou e onde parou — não invente continuação.
• Sem conclusões nem resumos finais. O template já é o entregável.

Pasta de destino e índice

Antes de gerar o primeiro documento da sessão:

1. Leia o CLAUDE.md na raiz procurando chaves como docs_flow_path, documentacao, vault ou similar.
2. Se houver → use esse caminho.
3. Se não houver → sugira uma das opções (recomende a primeira):
   • docs/fluxos-de-processos/
   • docs/process-flows/
   • vault/fluxos/
   • documentacao/fluxos/
4. Crie a pasta se ela não existir.
5. Pergunte se o usuário quer registrar a escolha no CLAUDE.md para próximas execuções. Se CLAUDE.md não existir, ofereça criá-lo com apenas essa chave.

Toda pasta de fluxos tem um README.md na raiz funcionando como índice (formato na seção Índice de fluxos mais abaixo). Crie-o se não existir; atualize-o sempre que gerar/atualizar qualquer fluxo.

Fluxo de execução

1. Descoberta

Pergunte:

• Qual processo documentar? Exemplos: tela de cadastro, rotina de fechamento de caixa, endpoint POST /pedidos, job de envio de e-mail, handler de fila, scheduler diário, integração com gateway, evento de domínio.
• Qual é o arquivo de entrada? (HTML, .cshtml, .razor, .tsx, controller, job, listener, scheduler, página, função CLI, handler de evento…)

Se o usuário não souber o arquivo de entrada, busque por palavra-chave do processo antes de pedir mais detalhes.

Detecte fluxo já documentado. Liste a pasta de destino e veja se já existe .md cobrindo esse processo (por slug ou por título). Se houver:

• Pergunte: "Encontrei {arquivo.md} cobrindo esse fluxo. Quer atualizar o existente ou criar um novo?"
• Atualizar → releia o código, regenere o conteúdo no mesmo arquivo, atualize last-reviewed e commit no frontmatter.
• Criar novo → siga numeração normal.

2. Rastreamento

A partir do entry point, percorra a cadeia. As camadas variam conforme o tipo de fluxo:

Frontend → backend View (HTML/Razor/JSX/Vue/…) → componente/page → chamada HTTP → controller/endpoint → serviço/handler → repositório/DAO → banco ou integração externa

Backend-only (job, scheduler, message handler, evento) Entry point (Worker.cs, BackgroundService, handler de fila, scheduler) → serviço → repositório/integração

Frontend-only View → componentes filhos → store/estado local → serviço local

Para cada arquivo identifique: caminho relativo, dependências relevantes (ignore imports decorativos), e para qual(is) arquivo(s) ele se comunica.

Onde parar. Sem critério de parada, o rastreamento desce indefinidamente em frameworks ou para cedo demais.

• Pare em boundaries de I/O. Query SQL final, chamada HTTP externa (HttpClient.SendAsync, fetch, requests.get), publicação em fila/event bus, gRPC, leitura/escrita de arquivo. Registre o que vai e o que volta, mas não tente abrir o destino.
• Não desça em código de framework nem terceiros. Classes-base do framework (Controller, BackgroundService, DbContext, Component), bibliotecas via NuGet/npm/PyPI. Mencione como dependência, não como sequencial.
• Desça em código do projeto. Inclusive herança, quando o override for relevante.
• Interfaces injetadas (DI). Ao ver IServicoX injetada, busque a implementação concreta no registro de DI (AddScoped, AddTransient, módulo providers, etc.) e documente o concreto.

Eventos e assíncrono. Quando vir Publish/Send/Dispatch/emit:

1. Registre a publicação como sequencial (com tipo do evento e payload resumido).
2. Busque consumidores pelo tipo do evento.
3. Consumidor único e crítico → continuação do fluxo. Múltiplos → ramificação, ou fluxos separados linkados via "Fluxos relacionados".

Fan-out (chamadas paralelas). Se um arquivo dispara várias chamadas independentes, liste cada caminho curto. Se algum caminho for substancial (>5 arquivos), prefira fluxo separado linkado — um doc só fica ilegível.

Middleware, auth e pipeline. Inclua apenas o que afeta a compreensão do fluxo: [Authorize] com role/policy específica, validators ativos, middleware customizado. Ignore logging, CORS, tracing genéricos.

Resiliência. Se houver retry / circuit breaker / Polly policy específico do fluxo (não infra genérica), mencione na descrição do arquivo que aplica.

Cadeia quebrada. Se não conseguir encontrar o entry point ou a cadeia se perder (reflection, código gerado, mapeamento por convenção), pare e relate:

• O que rastreou até onde
• Onde a cadeia se perdeu e por quê
• Pergunte se o usuário pode apontar o próximo passo

3. Confirmação intermediária

Antes de gerar o documento, em fluxos com mais de 3 arquivos, liste a cadeia rastreada:

Cadeia rastreada (N arquivos):
1. {arquivo-primario}
2. {sequencial-1}
3. {sequencial-2}  ← já documentado em _componentes/
...

Pergunte: "Posso gerar com essa cadeia? Falta algum arquivo?" Em fluxos pequenos (≤3 arquivos) pule esta etapa.

4. Decisão sobre arquivos .md

Antes de descrever cada sequencial, verifique se ele já tem .md em _componentes/ (ls _componentes/). Isso evita redocumentar e gerar divergência.

Fluxo principal → .md em {numero}-{slug}.md. Use max(números na pasta) + 1 — não preencha lacunas.

5. Revisão de componente já documentado

Quando um componente reutilizado já tem .md mas o novo fluxo o invoca de forma não-coberta (novo parâmetro, novo caminho condicional, efeito colateral novo), não reescreva o doc do componente. No fluxo principal, abaixo do link, adicione:

> [REVISAR DOC DO COMPONENTE] Este fluxo usa `{nome}` com {situação nova} que não está descrito em `_componentes/{nome}.md`.

A decisão de atualizar fica com o usuário — automatizar arrisca apagar contexto de fluxos anteriores.

6. Geração

Use o template da próxima seção. Não adicione campos extras, conclusões ou resumos.

Convenções de nome e idioma

• Slug: kebab-case, ASCII apenas (remova acentos: ã→a, ç→c), substantivo no singular quando possível. Ex.: 01-cadastro-cliente.md, não 01-cadastros-de-clientes.md.
• Numeração: max(números existentes) + 1. Se 03 foi deletado, o próximo continua sendo o próximo número, não 03.
• Idioma: detecte de CLAUDE.md (chave docs_language) ou de fluxos já documentados na pasta. Sem indicação, default PT-BR. Confirme se houver dúvida.
• Commit/data: capture o commit atual via git rev-parse --short HEAD (se for repo git) e a data ISO de hoje para o frontmatter.

Template do documento

---
name: {slug-do-fluxo}
status: draft
related: []
last-reviewed: {YYYY-MM-DD}
commit: {hash-curto-ou-null}
---

# {Título do Processo}

## 1. Descrição do Processo

**Regra de Negócio (RN):**
{O que o processo faz do ponto de vista do negócio. Se não for derivável do código com certeza, marque [CONFIRMAR COM USUÁRIO] e descreva o que foi inferido.}

**Entrada:**
{Payload/parâmetros que disparam o fluxo: DTO, query params, evento consumido, conteúdo de mensagem.}

**Saída:**
{O que o fluxo devolve ao chamador: response body, status code, evento publicado, registro retornado.}

**Efeitos colaterais:**
{Mudanças fora do retorno: registro no banco, e-mail enviado, arquivo gerado, evento publicado, cache invalidado. "Nenhum" se realmente não houver.}

---

## 2. Fluxo

### 2.1 Arquivo primário

**Descrição:** {O que este arquivo faz e qual seu papel no fluxo}
**Componentes/Bibliotecas:** {Imports/libs relevantes}
**Caminho:** `{caminho/relativo/do/arquivo}`

---

### 2.2 Arquivos sequenciais

#### 2.2.{n} {Nome do arquivo}

**Descrição:** {O que faz e como se relaciona com o anterior}
**Componentes/Bibliotecas:** {Imports/libs relevantes}
**Caminho:** `{caminho/relativo/do/arquivo}`
**Trecho do código original:** `{caminho}:{linha_inicial}-{linha_final}`

```{linguagem}
{Trecho extraído do código-fonte ORIGINAL — não do .md derivado. Mantenha curto (idealmente < 40 linhas); recorte o miolo com "// ... [N linhas omitidas] ..." se necessário.}
```

**Banco** *(só se o arquivo acessa banco)*:
- Tabelas: `{tabela_a}`, `{tabela_b}`
- Colunas afetadas: `{tabela_a.coluna_x}`, `{tabela_b.coluna_y}`
- Sprocs/funções: `{sp_x}` *(ou "nenhuma")*

**Documento dedicado:** [{nome}](./_componentes/{nome}.md) *(só se houver doc separado)*

> [REVISAR DOC DO COMPONENTE] *(só se aplicável, conforme seção 5)*

{Repita para cada sequencial}

---

## 3. Diagrama

```mermaid
flowchart TD
    A[arquivo-primario] --> B[seq-1]
    B --> C{decisor}
    C -->|caso A| D[seq-a-1]
    C -->|caso B| E[seq-b-1]
    B --> F[(banco)]
    B -.->|publica evento X| G[[consumer-handler]]
```

Para fluxos puramente lineares e curtos (≤5 nós), texto simples é aceitável:
```
{arquivo-primario} → {seq-1} → {seq-2}
```

---

## 4. Fluxos relacionados

- [{nome-do-fluxo}](./{slug}.md) — {relação curta}

*(remova esta seção se não houver relações)*

Convenções do Mermaid: retângulo [ ] para arquivos, losango { } para decisão, cilindro [( )] para banco, retângulo duplo [[ ]] para handler/consumer, seta tracejada -.-> para publicação de evento.

Índice de fluxos (README.md)

Mantenha um README.md na raiz da pasta de fluxos. Atualize a cada geração/atualização.

# Fluxos documentados

| Nº | Fluxo | Status | Última revisão |
|---|---|---|---|
| 01 | [Cadastro de cliente](./01-cadastro-cliente.md) | active | 2026-05-18 |
| 02 | [Fechamento de caixa](./02-fechamento-caixa.md) | draft | 2026-05-15 |

## Componentes reutilizáveis

- [`PessoaService`](./_componentes/pessoa-service.md)
- [`PedidoRepository`](./_componentes/pedido-repository.md)

Após gerar

1. Atualize o README.md (índice) com a nova linha ou status atualizado.
2. Emita confirmação:

✅ Documento gerado: {caminho/do/arquivo.md}
📎 Componentes extraídos para arquivos separados: {lista ou "nenhum"}
📇 Índice atualizado: {caminho/do/README.md}

3. Se houver [CONFIRMAR COM USUÁRIO] no documento, pergunte os pontos incertos de RN.
4. Se houver [REVISAR DOC DO COMPONENTE], lembre o usuário de revisar quando puder.