@polymorphism-tech/morph-spec 4.10.0 → 4.10.2

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

@@ -2,90 +2,90 @@
 name: morph: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.10.0"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+cliVersion: "4.10.2"
 ---
 
-# MORPH Codebase Analysis - Sub-fase de DESIGN
+# MORPH Codebase Analysis - Design Sub-phase
 
 > INTERNAL: Automation skill for schema analysis step within Phase 2 (Design).
-> Called by `phase-design.md` Passo 2. Not a standalone user command.
+> Called by `phase-design.md` Step 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.
+Automates existing code analysis to generate `schema-analysis.md` with real database/code data.
 
-## Pré-requisitos
+## Prerequisites
 
-- [ ] FASE 1 (Setup) concluída
-- [ ] Feature tem `proposal.md` aprovado
-- [ ] Contexto do projeto carregado (stack, agentes)
+- [ ] Phase 1 (Setup) completed
+- [ ] Feature has approved `proposal.md`
+- [ ] Project context loaded (stack, agents)
 
-## Ferramentas Recomendadas
+## Recommended Tools
 
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for MCP reference.
 
-| Ação | Ferramenta | Alternativa |
+| Action | Tool | Alternative |
 |------|------------|-------------|
-| 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.
+| List database tables | **Supabase MCP** `list_tables()` | **Grep** `.from(` in code |
+| Get table schema | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
+| Get FK relationships | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
+| Get RLS policies | **Supabase MCP** `query()` | **Read** policy files |
+| Find queries in code | **Grep** `\.from\(` in `*.ts,*.tsx,*.js,*.cs` | — |
+| Find type definitions | **Glob** `src/**/types/**/*.ts` or `**/Entities/**/*.cs` | — |
+| Read found files | **Read** each file | — |
+| Complex multi-file analysis | **Task** (subagent Explore) | Read individual |
+| Generate schema-analysis.md | **Write** using template | **Bash** template render |
+
+**MCPs for this phase:** Supabase (schema — **PRIORITY**), Generic database MCPs.
 
 ---
 
-## Workflow Automatizado
+## Automated Workflow
 
-### Passo 1: Detectar Método de Análise
+### Step 1: Detect Analysis Method
 
-**IMPORTANTE (Problem 8 fix):** Não assuma que o MCP está disponível e acessível.
-Verifique primeiro com uma chamada de teste antes de tentar usá-lo.
+**IMPORTANT:** Do not assume the MCP is available and accessible.
+Verify first with a test call before attempting to use it.
 
 ```
-1. SE MCP Supabase configurado no settings.json:
-   → Tentar mcp__supabase__list_tables() com timeout implícito
-   → SE retornar dados válidos (array de tabelas com conteúdo):
-      → Usar Método A (MCP direto)
-   → SE retornar erro, timeout, array vazio, ou dados inacessíveis:
-      → Logar: "MCP Supabase configurado mas inacessível (CloudSQL? Auth? Permissões?)"
-      → Usar Método B (análise estática de código)
-
-2. SE MCP Database (outro) configurado:
-   → Testar conectividade com query trivial antes de usar
-   → SE OK: Usar Método A adaptado
-   → SE falhar: Usar Método B
-
-3. SE nenhum MCP disponível:
-   → Usar Método B (análise estática de código)
+1. IF Supabase MCP configured in settings.json:
+   → Try mcp__supabase__list_tables() with implicit timeout
+   → IF returns valid data (array of tables with content):
+      → Use Method A (direct MCP)
+   → IF returns error, timeout, empty array, or inaccessible data:
+      → Log: "Supabase MCP configured but inaccessible (CloudSQL? Auth? Permissions?)"
+      → Use Method B (static code analysis)
+
+2. IF Database MCP (other) configured:
+   → Test connectivity with trivial query before using
+   → IF OK: Use adapted Method A
+   → IF fails: Use Method B
+
+3. IF no MCP available:
+   → Use Method B (static code analysis)
 ```
 
-**Sinais de MCP inacessível:**
-- Resposta vazia ou `[]` em `list_tables()`
-- Erro de autenticação / permissão negada
-- Schema retornado não bate com o código (ex: tabelas existem no código mas não no MCP)
-- Projeto usa banco diferente do Supabase (CloudSQL, RDS, Azure SQL, etc.)
+**Signs of inaccessible MCP:**
+- Empty response or `[]` from `list_tables()`
+- Authentication error / permission denied
+- Returned schema doesn't match code (e.g., tables exist in code but not in MCP)
+- Project uses database other than Supabase (CloudSQL, RDS, Azure SQL, etc.)
 
-### Passo 2A: Método MCP (Preferencial)
+### Step 2A: MCP Method (Preferred)
 
-**Ferramentas:** Supabase MCP
+**Tools:** Supabase MCP
 
 ```javascript
-// 1. Listar todas as tabelas
+// 1. List all tables
 const tables = await mcp__supabase__list_tables();
 
-// 2. Para cada tabela relevante à feature:
+// 2. For each feature-relevant table:
 for (const table of relevantTables) {
-  // 2a. Schema completo
+  // 2a. Complete schema
   const schema = await mcp__supabase__get_table_schema({ table: table.name });
   // → column_name, data_type, is_nullable, column_default
 
-  // 2b. Relacionamentos
+  // 2b. Relationships
   const rels = await mcp__supabase__get_relationships({ table: table.name });
   // → foreign_table, foreign_column, constraint_type
 
@@ -94,18 +94,18 @@ for (const table of relevantTables) {
     query: `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '${table.name}'`
   });
 
-  // 2d. RLS policies (segurança)
+  // 2d. RLS policies (security)
   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)
+### Step 2B: Static Analysis Method (Fallback)
 
-**Ferramentas:** Grep, Glob, Read, Task (subagent para projetos grandes)
+**Tools:** Grep, Glob, Read, Task (subagent for large projects)
 
-**Fase B1: Encontrar Queries**
+**Phase B1: Find Queries**
 
 ```
 Grep: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|DbSet<"
@@ -113,15 +113,15 @@ Type: ts,tsx,js,jsx,cs
 Output: files_with_matches
 ```
 
-**Fase B2: Ler Arquivos de Query**
+**Phase B2: Read Query Files**
 
-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
+For each found file, use **Read** to extract:
+- Table names: `from('leads')`, `DbSet<Lead>`, `FROM leads`
+- Column names: `.select('fullname, phonenumber')`, `l.FullName`
+- Data types: TypeScript interfaces, C# DTOs
+- Relationships: JOIN clauses, navigation properties
 
-**Fase B3: Encontrar Type Definitions**
+**Phase B3: Find Type Definitions**
 
 ```
 # TypeScript/JavaScript:
@@ -135,23 +135,23 @@ Glob: "**/Entities/**/*.cs"
 Glob: "**/Models/**/*.cs"
 ```
 
-**Fase B4: Quando usar Task (subagent)**
+**Phase B4: When to use 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
+Use Task subagent **ONLY** when:
+- Project has 20+ query files
+- Multiple data access patterns (Supabase + EF Core + raw SQL)
+- Precise cross-context analysis across many files
 
-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)
+Do not use Task subagent when:
+- Project has < 10 query files (direct Read is faster)
+- Data access pattern is uniform (only Supabase OR only EF Core)
 
-### Passo 2B-Formato: Formato Padronizado para Análise Estática
+### Step 2B-Format: Standardized Format for Static Analysis
 
-**IMPORTANTE (Problem 10 fix):** Quando usar Método B (análise estática), **sempre use o template oficial**.
-Isso garante que `contracts.cs` pode ser gerado mecanicamente, sem interpretação manual.
+**IMPORTANT:** When using Method B (static analysis), **always use the official template**.
+This ensures `contracts.cs` can be generated mechanically, without manual interpretation.
 
-O template está em `framework/templates/docs/schema-analysis.md`. Use-o via:
+The template is at `framework/templates/docs/schema-analysis.md`. Use it via:
 
 ```bash
 npx morph-spec template render docs/schema-analysis \
@@ -194,23 +194,23 @@ npx morph-spec template render docs/schema-analysis \
   }'
 ```
 
-**Se o template render não estiver disponível**, use **Write** tool para criar o arquivo diretamente
-seguindo a estrutura acima. O formato das tabelas e mismatches é OBRIGATÓRIO — sem formato padrão
-não é possível gerar contracts.cs mecanicamente.
+**If template render is not available**, use **Write** tool to create the file directly
+following the structure above. The table and mismatch format is MANDATORY — without standard format
+it's not possible to generate contracts.cs mechanically.
 
-### Passo 3: Mapear Inconsistências
+### Step 3: Map Inconsistencies
 
-Crie um mapa de:
+Create a map of:
 
-| Frontend/Código | Banco de Dados | Tipo | Problema |
+| Frontend/Code | Database | Type | Problem |
 |----------------|----------------|------|----------|
-| user.name | users.fullname | string | ❌ MISMATCH |
-| lead.phone | leads.phonenumber | string | ❌ MISMATCH |
-| order.metadata | orders.metadata | JSONB | ⚠️ Type complex |
+| 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`
+### Step 4: Generate `schema-analysis.md`
 
-Use o template em `framework/templates/docs/schema-analysis.md`:
+Use the template at `framework/templates/docs/schema-analysis.md`:
 
 ```bash
 npx morph-spec template render docs/schema-analysis \
@@ -218,9 +218,9 @@ npx morph-spec template render docs/schema-analysis \
   '{ "FEATURE_NAME": "{feature-name}", "DATE": "..." }'
 ```
 
-OU use **Write** tool para criar diretamente com os dados coletados.
+OR use **Write** tool to create directly with collected data.
 
-### Passo 5: Atualizar State
+### Step 5: Update State
 
 ```bash
 npx morph-spec state mark-output {feature-name} schema-analysis
@@ -231,22 +231,40 @@ npx morph-spec state mark-output {feature-name} schema-analysis
 ## Outputs
 
 - `.morph/features/{feature}/1-design/schema-analysis.md`
-- State atualizado com output `schemaAnalysis`
+- State updated with `schemaAnalysis` output
 
 ## 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
+Before proceeding to contracts.cs, present results and ask for confirmation using `AskUserQuestion`:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Schema Review",
+      "question": "Schema analysis complete: {N} tables, {N} field mismatches, {N} type mismatches, {N} relationships. Is the analysis correct?",
+      "multiSelect": false,
+      "options": [
+        { "label": "Correct", "description": "Schema analysis matches the real database" },
+        { "label": "Has issues", "description": "I see problems — let me explain" }
+      ]
+    },
+    {
+      "header": "Contracts",
+      "question": "May I generate contracts.cs based on this real schema?",
+      "multiSelect": false,
+      "options": [
+        { "label": "Generate contracts", "description": "Proceed to contracts.cs using the analyzed schema" },
+        { "label": "Wait", "description": "I want to review schema-analysis.md first" }
+      ]
+    }
+  ]
+}
+```
 
-**Perguntas obrigatórias:**
-1. "O schema analysis está correto?"
-2. "Posso gerar contracts.cs com base nesse schema real?"
+**If "Has issues"** → ask what's wrong, fix schema-analysis.md, re-present checkpoint.
+**If "Correct" + "Generate contracts"** → proceed to contracts generation.
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech*
+*MORPH-SPEC by Polymorphism Tech*