Skill: document-project

Gera documentação técnica completa de projetos Laravel/Filament no Notion.

Regras Globais

Todo conteúdo gerado deve estar em pt-BR
Referências carregadas sob demanda (não todas de uma vez)
Sempre buscar no Notion antes de criar (evitar duplicatas)
Não criar páginas para seções vazias — se a pasta não existe ou não tem artefatos, pular
Ignorar: tests/, vendor/, node_modules/, storage/, bootstrap/cache/
Campos sem documentação óbvia: inferir pelo nome + contexto, marcar [inferido]
Artefatos complexos (>200 linhas, muitas dependências): adicionar callout ⚠️ sugerindo revisão manual
Nunca auto-corrigir código — apenas documentar
Sempre incluir arquivo:linha nas referências de código
Paralelizar operações Glob/Grep sempre que possível

Fase 1 — Perguntas Iniciais

Determinar caminho do projeto

SE $ARGUMENTS não está vazio:
  PROJECT_PATH = $ARGUMENTS
SENÃO:
  Perguntar ao usuário o caminho do projeto
FIM

Validar projeto Laravel

Verificar existência de: {PROJECT_PATH}/artisan
SE não existe:
  ERRO: "O caminho informado não parece ser um projeto Laravel (arquivo 'artisan' não encontrado)."
  Encerrar skill.
FIM

Coletar informações

Perguntar ao usuário (usar AskUserQuestion):

Nome do projeto — nome para exibir na documentação (sugerir nome da pasta)
Descrição — breve descrição do projeto (1-2 frases)
Pastas adicionais a ignorar — além das padrão (tests, vendor, node_modules, storage)
Nível de detalhe — resumido ou completo
- resumido: apenas métodos públicos, campos, relacionamentos
- completo: inclui regras de negócio inferidas, accessors/mutators, side effects, observers

Armazenar em variáveis:

NOME_PROJETO
DESCRICAO_PROJETO
PASTAS_IGNORAR (array)
NIVEL_DETALHE ("resumido" | "completo")

Fase 2 — Descoberta do Projeto

2.1 Detectar stack

# Ler composer.json para versões
cat {PROJECT_PATH}/composer.json

Extrair:

VERSAO_PHP — do campo require.php
VERSAO_LARAVEL — do campo require.laravel/framework
VERSAO_FILAMENT — do campo require.filament/filament (pode não existir)
PACOTES_NOTAVEIS — pacotes relevantes (spatie/*, livewire, sanctum, horizon, etc.)

2.2 Descoberta de artefatos (Glob paralelo)

Executar todos os Globs em paralelo:

Tipo	Glob Pattern
Models	`{PROJECT_PATH}/app/Models/*/.php`
Services	`{PROJECT_PATH}/app/Services/*/.php`
Actions	`{PROJECT_PATH}/app/Actions/*/.php`
Enums	`{PROJECT_PATH}/app/Enums/*/.php`
Events	`{PROJECT_PATH}/app/Events/*/.php`
Jobs	`{PROJECT_PATH}/app/Jobs/*/.php`
Filament Resources	`{PROJECT_PATH}/app/Filament/Resources/*/.php`
Commands	`{PROJECT_PATH}/app/Console/Commands/*/.php`
Controllers	`{PROJECT_PATH}/app/Http/Controllers/*/.php`
Policies	`{PROJECT_PATH}/app/Policies/*/.php`
Observers	`{PROJECT_PATH}/app/Observers/*/.php`
Form Requests	`{PROJECT_PATH}/app/Http/Requests/*/.php`
Routes	`{PROJECT_PATH}/routes/*.php`

2.3 Reportar ao usuário

Exibir tabela resumo:

📊 Artefatos encontrados:
| Tipo               | Qtd |
|--------------------|-----|
| Models             | X   |
| Services           | X   |
| ...                | ... |
| Total              | XX  |

Informar quais seções serão puladas (pasta vazia ou inexistente).

Pedir confirmação para prosseguir.

Fase 3 — Escaneamento

Carregar referência: references/scan-patterns.md

Grupo 1 — Grep rápido (paralelo)

Executar em paralelo os padrões de Grep definidos em scan-patterns.md para:

Models: $fillable, $casts, $guarded, relacionamentos (hasMany, belongsTo, etc.)
Enums: case , BackedEnum
Events: class.*Event, ShouldBroadcast
Jobs: $tries, $timeout, handle(, ShouldQueue
Commands: $signature, $description, handle(
Routes: Route::get|post|put|patch|delete|resource|apiResource

Grupo 2 — Leitura completa (paralelo, após Grupo 1)

Para cada artefato detectado, ler o arquivo completo usando Read.

Ordem de prioridade:

Models (base para entender o domínio)
Services e Actions (lógica de negócio)
Filament Resources (interface admin) — ler Resource + suas Pages juntas
Controllers, Policies, Observers, Form Requests (suporte)

Otimização: Processar em lotes de 5-10 arquivos por vez para não sobrecarregar o contexto.

Fase 4 — Extração e Estruturação

Carregar referências sob demanda:

references/extraction-models.md — ao processar Models

references/extraction-filament.md — ao processar Filament Resources

references/extraction-services-enums.md — ao processar Services, Enums, Events, Jobs, Commands

4.1 Aplicar templates de extração

Para cada artefato, aplicar o template de extração correspondente ao seu tipo.

4.2 Nível de detalhe

SE NIVEL_DETALHE == "completo":
  - Incluir regras de negócio inferidas dos métodos
  - Documentar accessors, mutators, scopes com exemplos
  - Listar side effects (eventos disparados, jobs despachados, notificações)
  - Documentar observers e policies relacionados
  - Incluir Form Request rules por endpoint

SE NIVEL_DETALHE == "resumido":
  - Apenas métodos públicos com assinatura
  - Campos fillable/casts
  - Relacionamentos (nome + tipo + modelo relacionado)
  - Sem regras de negócio inferidas
FIM

4.3 Detectar integrações externas

Grep paralelo:
  - "Http::" em app/**/*.php
  - "Guzzle" em app/**/*.php
  - "curl_" em app/**/*.php
  - SDKs no composer.json (aws, stripe, twilio, sendgrid, etc.)

4.4 Consolidar regras de negócio (apenas modo completo)

Cruzar informações de:

Policies → permissões por entidade
Form Requests → validações por endpoint
Services/Actions → fluxos de negócio
Observers → side effects automáticos
Events/Listeners → reações a mudanças de estado

Agrupar por entidade (Model) para a seção "Regras de Negócio".

Fase 5 — Criação das Páginas Notion

Carregar referências:

references/notion-structure.md — hierarquia e ordem de criação

references/notion-page-templates.md — templates de conteúdo por tipo de página

5.1 Verificar duplicatas

notion-search: query = "{NOME_PROJETO} — Documentação Técnica"
SE resultado encontrado:
  Perguntar ao usuário:
    - "Já existe documentação para este projeto no Notion. Deseja atualizar ou criar nova?"
    - Opções: "Atualizar existente" | "Criar nova" | "Cancelar"
FIM

5.2 Criar página raiz

notion-create-pages:
  title: "{NOME_PROJETO} — Documentação Técnica"
  content: (usar template de notion-page-templates.md para página raiz)

Capturar: ROOT_PAGE_ID

5.3 Criar sub-páginas de seção (paralelo)

Criar apenas as seções que têm artefatos. Usar parent = ROOT_PAGE_ID.

Seções possíveis (em ordem):

📋 Visão Geral
🗃️ Models
⚖️ Regras de Negócio (apenas se NIVEL_DETALHE == "completo")
⚙️ Services & Use Cases
🏷️ Enums
📡 Eventos & Jobs
🖥️ Filament Resources
🔧 Comandos Artisan
🔌 Integrações Externas

Capturar o ID de cada sub-página criada.

5.4 Criar páginas de artefatos (paralelo por seção)

Para cada seção, criar sub-páginas individuais:

Models: 1 página por Model
Services & Use Cases: 1 página por Service/Action
Enums: consolidado se ≤5 enums, ou 1 página por enum se >5
Eventos & Jobs: tabelas consolidadas em página única
Filament Resources: 1 página por Resource
Comandos Artisan: tabela consolidada em página única
Integrações Externas: tabela consolidada em página única

5.5 Atualizar Visão Geral

Após criar todas as páginas, atualizar a página "Visão Geral" com:

Stack tecnológica (PHP, Laravel, Filament, pacotes notáveis)
Estatísticas finais (quantidade de artefatos por tipo)
Módulos/domínios identificados
Data de geração

Fase 6 — Resumo Terminal

Exibir ao usuário:

✅ Documentação gerada com sucesso!

📊 Resumo:
| Tipo                  | Documentados |
|-----------------------|-------------|
| Models                | X           |
| Services/Actions      | X           |
| Enums                 | X           |
| Eventos               | X           |
| Jobs                  | X           |
| Filament Resources    | X           |
| Comandos Artisan      | X           |
| Integrações Externas  | X           |
| **Total de páginas**  | **XX**      |

🔗 Página raiz: {URL_NOTION_RAIZ}
📝 Nível de detalhe: {NIVEL_DETALHE}
📅 Gerado em: {DATA_HORA}

Gerado por: Claude Code / Skill: document-project