@polymorphism-tech/morph-spec 4.7.1 → 4.8.1

package/framework/skills/level-1-workflows/phase-codebase-analysis/SKILL.md

@@ -1,181 +1,182 @@
----
-name: phase-codebase-analysis
-description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# MORPH Codebase Analysis - Sub-fase de DESIGN
-
-> INTERNAL: Automation skill for schema analysis step within Phase 2 (Design).
-> Called by `phase-design.md` Passo 2. Not a standalone user command.
-
-Automatiza a análise de código existente para gerar `schema-analysis.md` com dados reais do banco/código.
-
-## Pré-requisitos
-
-- [ ] FASE 1 (Setup) concluída
-- [ ] Feature tem `proposal.md` aprovado
-- [ ] Contexto do projeto carregado (stack, agentes)
-
-## Ferramentas Recomendadas
-
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
-
-| Ação | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Listar tabelas do banco | **Supabase MCP** `list_tables()` | **Grep** `.from(` no código |
-| Obter schema de tabela | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
-| Obter relacionamentos FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
-| Obter políticas RLS | **Supabase MCP** `query()` | **Read** policy files |
-| Encontrar queries no código | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
-| Encontrar type definitions | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
-| Ler arquivos encontrados | **Read** cada arquivo | — |
-| Análise multi-arquivo complexa | **Task** (subagent Explore) | Read individual |
-| Gerar schema-analysis.md | **Write** usando template | **Bash** template render |
-
-**MCPs desta fase:** Supabase (schema — **PRIORITÁRIO**), Database MCPs genéricos.
-
----
-
-## Workflow Automatizado
-
-### Passo 1: Detectar Método de Análise
-
-```
-SE MCP Supabase disponível:
-  → Usar Método A (MCP direto)
-SE MCP Database disponível:
-  → Usar Método A adaptado
-SENÃO:
-  → Usar Método B (análise estática de código)
-```
-
-### Passo 2A: Método MCP (Preferencial)
-
-**Ferramentas:** Supabase MCP
-
-```javascript
-// 1. Listar todas as tabelas
-const tables = await mcp__supabase__list_tables();
-
-// 2. Para cada tabela relevante à feature:
-for (const table of relevantTables) {
-  // 2a. Schema completo
-  const schema = await mcp__supabase__get_table_schema({ table: table.name });
-  // → column_name, data_type, is_nullable, column_default
-
-  // 2b. Relacionamentos
-  const rels = await mcp__supabase__get_relationships({ table: table.name });
-  // → foreign_table, foreign_column, constraint_type
-
-  // 2c. Indexes
-  const indexes = await mcp__supabase__query({
-    query: `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '${table.name}'`
-  });
-
-  // 2d. RLS policies (segurança)
-  const policies = await mcp__supabase__query({
-    query: `SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = '${table.name}'`
-  });
-}
-```
-
-### Passo 2B: Método Análise Estática (Fallback)
-
-**Ferramentas:** Grep, Glob, Read, Task (subagent para projetos grandes)
-
-**Fase B1: Encontrar Queries**
-
-```
-Grep: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|DbSet<"
-Type: ts,tsx,js,jsx,cs
-Output: files_with_matches
-```
-
-**Fase B2: Ler Arquivos de Query**
-
-Para cada arquivo encontrado, use **Read** para extrair:
-- Nomes de tabelas: `from('leads')`, `DbSet<Lead>`, `FROM leads`
-- Nomes de colunas: `.select('fullname, phonenumber')`, `l.FullName`
-- Tipos de dados: TypeScript interfaces, C# DTOs
-- Relacionamentos: JOIN clauses, navigation properties
-
-**Fase B3: Encontrar Type Definitions**
-
-```
-# TypeScript/JavaScript:
-Glob: "src/**/types/**/*.ts"
-Glob: "src/**/*.d.ts"
-Glob: "src/**/interfaces/*.ts"
-
-# .NET:
-Glob: "**/*Dto.cs"
-Glob: "**/Entities/**/*.cs"
-Glob: "**/Models/**/*.cs"
-```
-
-**Fase B4: Quando usar Task (subagent)**
-
-Use Task subagent **APENAS** quando:
-- Projeto tem 20+ arquivos de query
-- Múltiplos padrões de acesso a dados (Supabase + EF Core + raw SQL)
-- Análise precisa de contexto cruzado entre muitos arquivos
-
-Não use Task subagent quando:
-- Projeto tem < 10 arquivos de query (Read direto é mais rápido)
-- Padrão de acesso a dados é uniforme (só Supabase OU só EF Core)
-
-### Passo 3: Mapear Inconsistências
-
-Crie um mapa de:
-
-| Frontend/Código | Banco de Dados | Tipo | Problema |
-|----------------|----------------|------|----------|
-| user.name | users.fullname | string | ❌ MISMATCH |
-| lead.phone | leads.phonenumber | string | ❌ MISMATCH |
-| order.metadata | orders.metadata | JSONB | ⚠️ Type complex |
-
-### Passo 4: Gerar `schema-analysis.md`
-
-Use o template em `framework/templates/docs/schema-analysis.md`:
-
-```bash
-npx morph-spec template render docs/schema-analysis \
-  .morph/features/{feature-name}/1-design/schema-analysis.md \
-  '{ "FEATURE_NAME": "{feature-name}", "DATE": "..." }'
-```
-
-OU use **Write** tool para criar diretamente com os dados coletados.
-
-### Passo 5: Atualizar State
-
-```bash
-npx morph-spec state mark-output {feature-name} schema-analysis
-```
-
----
-
-## Outputs
-
-- `.morph/features/{feature}/1-design/schema-analysis.md`
-- State atualizado com output `schemaAnalysis`
-
-## CHECKPOINT
-
-Antes de prosseguir para contracts.cs, apresente ao usuário:
-
-- [ ] Analisei {N} tabelas
-- [ ] Encontrei {N} field name mismatches
-- [ ] Encontrei {N} type mismatches
-- [ ] Mapeei {N} relacionamentos
-- [ ] `schema-analysis.md` criado
-
-**Perguntas obrigatórias:**
-1. "O schema analysis está correto?"
-2. "Posso gerar contracts.cs com base nesse schema real?"
-
----
-
+---
+name: phase-codebase-analysis
+description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+cliVersion: "4.8.1"
+---
+
+# MORPH Codebase Analysis - Sub-fase de DESIGN
+
+> INTERNAL: Automation skill for schema analysis step within Phase 2 (Design).
+> Called by `phase-design.md` Passo 2. Not a standalone user command.
+
+Automatiza a análise de código existente para gerar `schema-analysis.md` com dados reais do banco/código.
+
+## Pré-requisitos
+
+- [ ] FASE 1 (Setup) concluída
+- [ ] Feature tem `proposal.md` aprovado
+- [ ] Contexto do projeto carregado (stack, agentes)
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Listar tabelas do banco | **Supabase MCP** `list_tables()` | **Grep** `.from(` no código |
+| Obter schema de tabela | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
+| Obter relacionamentos FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
+| Obter políticas RLS | **Supabase MCP** `query()` | **Read** policy files |
+| Encontrar queries no código | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
+| Encontrar type definitions | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
+| Ler arquivos encontrados | **Read** cada arquivo | — |
+| Análise multi-arquivo complexa | **Task** (subagent Explore) | Read individual |
+| Gerar schema-analysis.md | **Write** usando template | **Bash** template render |
+
+**MCPs desta fase:** Supabase (schema — **PRIORITÁRIO**), Database MCPs genéricos.
+
+---
+
+## Workflow Automatizado
+
+### Passo 1: Detectar Método de Análise
+
+```
+SE MCP Supabase disponível:
+  → Usar Método A (MCP direto)
+SE MCP Database disponível:
+  → Usar Método A adaptado
+SENÃO:
+  → Usar Método B (análise estática de código)
+```
+
+### Passo 2A: Método MCP (Preferencial)
+
+**Ferramentas:** Supabase MCP
+
+```javascript
+// 1. Listar todas as tabelas
+const tables = await mcp__supabase__list_tables();
+
+// 2. Para cada tabela relevante à feature:
+for (const table of relevantTables) {
+  // 2a. Schema completo
+  const schema = await mcp__supabase__get_table_schema({ table: table.name });
+  // → column_name, data_type, is_nullable, column_default
+
+  // 2b. Relacionamentos
+  const rels = await mcp__supabase__get_relationships({ table: table.name });
+  // → foreign_table, foreign_column, constraint_type
+
+  // 2c. Indexes
+  const indexes = await mcp__supabase__query({
+    query: `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '${table.name}'`
+  });
+
+  // 2d. RLS policies (segurança)
+  const policies = await mcp__supabase__query({
+    query: `SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = '${table.name}'`
+  });
+}
+```
+
+### Passo 2B: Método Análise Estática (Fallback)
+
+**Ferramentas:** Grep, Glob, Read, Task (subagent para projetos grandes)
+
+**Fase B1: Encontrar Queries**
+
+```
+Grep: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|DbSet<"
+Type: ts,tsx,js,jsx,cs
+Output: files_with_matches
+```
+
+**Fase B2: Ler Arquivos de Query**
+
+Para cada arquivo encontrado, use **Read** para extrair:
+- Nomes de tabelas: `from('leads')`, `DbSet<Lead>`, `FROM leads`
+- Nomes de colunas: `.select('fullname, phonenumber')`, `l.FullName`
+- Tipos de dados: TypeScript interfaces, C# DTOs
+- Relacionamentos: JOIN clauses, navigation properties
+
+**Fase B3: Encontrar Type Definitions**
+
+```
+# TypeScript/JavaScript:
+Glob: "src/**/types/**/*.ts"
+Glob: "src/**/*.d.ts"
+Glob: "src/**/interfaces/*.ts"
+
+# .NET:
+Glob: "**/*Dto.cs"
+Glob: "**/Entities/**/*.cs"
+Glob: "**/Models/**/*.cs"
+```
+
+**Fase B4: Quando usar Task (subagent)**
+
+Use Task subagent **APENAS** quando:
+- Projeto tem 20+ arquivos de query
+- Múltiplos padrões de acesso a dados (Supabase + EF Core + raw SQL)
+- Análise precisa de contexto cruzado entre muitos arquivos
+
+Não use Task subagent quando:
+- Projeto tem < 10 arquivos de query (Read direto é mais rápido)
+- Padrão de acesso a dados é uniforme (só Supabase OU só EF Core)
+
+### Passo 3: Mapear Inconsistências
+
+Crie um mapa de:
+
+| Frontend/Código | Banco de Dados | Tipo | Problema |
+|----------------|----------------|------|----------|
+| user.name | users.fullname | string | ❌ MISMATCH |
+| lead.phone | leads.phonenumber | string | ❌ MISMATCH |
+| order.metadata | orders.metadata | JSONB | ⚠️ Type complex |
+
+### Passo 4: Gerar `schema-analysis.md`
+
+Use o template em `framework/templates/docs/schema-analysis.md`:
+
+```bash
+npx morph-spec template render docs/schema-analysis \
+  .morph/features/{feature-name}/1-design/schema-analysis.md \
+  '{ "FEATURE_NAME": "{feature-name}", "DATE": "..." }'
+```
+
+OU use **Write** tool para criar diretamente com os dados coletados.
+
+### Passo 5: Atualizar State
+
+```bash
+npx morph-spec state mark-output {feature-name} schema-analysis
+```
+
+---
+
+## Outputs
+
+- `.morph/features/{feature}/1-design/schema-analysis.md`
+- State atualizado com output `schemaAnalysis`
+
+## CHECKPOINT
+
+Antes de prosseguir para contracts.cs, apresente ao usuário:
+
+- [ ] Analisei {N} tabelas
+- [ ] Encontrei {N} field name mismatches
+- [ ] Encontrei {N} type mismatches
+- [ ] Mapeei {N} relacionamentos
+- [ ] `schema-analysis.md` criado
+
+**Perguntas obrigatórias:**
+1. "O schema analysis está correto?"
+2. "Posso gerar contracts.cs com base nesse schema real?"
+
+---
+
 *MORPH-SPEC by Polymorphism Tech*