@polymorphism-tech/morph-spec 4.8.18 → 4.9.0

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

@@ -1,190 +1,216 @@
----
-name: phase-clarify
-description: MORPH-SPEC Phase 3 (Clarify). Reviews spec.md for ambiguities, generates 3-7 targeted clarification questions, waits for user answers, then updates spec with edge cases and clarification sections. Use after design approval to eliminate spec ambiguities before task breakdown begins.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.18"
----
-
-# MORPH Clarify - FASE 3
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Identifique ambiguidades na especificação e faça perguntas de clarificação para garantir que todos os edge cases estão cobertos.
-
-## Pré-requisitos
-
-- [ ] FASE 2 (Design) concluída
-- [ ] `spec.md` aprovado pelo usuário
-- [ ] `contracts.cs` definidos
-
-## 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.
-> **Example:** `references/clarifications-example.md` — filled-in clarifications.md showing expected Q&A format.
-
-| Ação | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Ler spec.md completo | **Read** spec.md | — |
-| Ler contracts.cs | **Read** contracts.cs | — |
-| Ler schema-analysis.md | **Read** schema-analysis.md | — |
-| Verificar viabilidade de requisito | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
-| Verificar issues/limitações conhecidas | **GitHub MCP** `search_issues()` | **Bash** `gh issue list --search "..."` |
-| Pesquisar edge cases externos | **WebSearch** | — |
-| Verificar comportamento UI existente | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | **WebFetch** URL |
-| Atualizar spec com clarificações | **Edit** spec.md | — |
-| Criar clarifications.md | **Bash** `npx morph-spec template render docs/clarifications .morph/features/$ARGUMENTS/2-clarify/clarifications.md` | — |
-| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS clarifications` | — |
-
-**MCPs desta fase:** Context7 (validar viabilidade), GitHub (issues conhecidas), Playwright (verificar UI existente).
-
-**Anti-padrões:**
-- ❌ Task agent para ler spec (use Read direto)
-- ❌ Reescrever spec do zero (use Edit para atualizar seções)
-- ❌ Pular cross-reference com schema-analysis.md (crítico para precisão)
-
----
-
-## Workflow
-
-### Passo 1: Analisar Spec
-
-Leia `.morph/features/$ARGUMENTS/1-design/spec.md` em detalhes e identifique:
-
-#### 1.1. Ambiguidades
-- Requisitos vagos ou genéricos
-- Termos sem definição clara
-- Comportamentos não especificados
-
-#### 1.2. Edge Cases Não Documentados
-- O que acontece se...?
-- Como lidar com entradas inválidas?
-- Comportamento em caso de erro?
-- Estados intermediários (loading, empty)
-
-#### 1.3. Requisitos Conflitantes
-- Duas funcionalidades que parecem incompatíveis
-- Prioridades não claras (o que vem primeiro?)
-
-#### 1.4. Dados Faltantes
-- Validações de negócio não especificadas
-- Limites e constraints (tamanhos, quantidades)
-- Formatos de dados (datas, moedas, etc.)
-
-### Passo 2: Gerar Perguntas de Clarificação
-
-Com base na análise, gere **3-7 perguntas** focadas e específicas:
-
-**Formato de pergunta:**
-```markdown
-### Q{N}: {Categoria} - {Título}
-
-**Context:** {Por que esta pergunta é importante}
-
-**Question:** {Pergunta clara e objetiva}
-
-**Options (if applicable):**
-- A) {Opção 1}
-- B) {Opção 2}
-- C) {Deixar em aberto/usuário decidir}
-
-**Impact:** {Como a resposta afeta a implementação}
-```
-
-### Passo 3: Categorizar Perguntas
-
-Organize perguntas por categoria:
-
-| Categoria | Descrição | Exemplos |
-|-----------|-----------|----------|
-| **Validação** | Regras de negócio, constraints | Limites de tamanho, formatos aceitos |
-| **Comportamento** | O que acontece quando... | Error handling, estados vazios |
-| **Prioridade** | O que é must-have vs nice-to-have | MVP vs futuras iterações |
-| **Integração** | Como interage com sistemas externos | APIs, webhooks, formato de dados |
-| **Performance** | Requisitos de velocidade/volume | Quantos registros? Tempo de resposta? |
-| **UX** | Experiência do usuário | Feedback visual, mensagens de erro |
-
-### Passo 4: Apresentar Perguntas ao Usuário
-
-Liste todas as perguntas de forma clara e estruturada.
-
-**IMPORTANTE:** Não prossiga para próxima fase até ter respostas!
-
-### Passo 5: Atualizar `spec.md` com Respostas
-
-Após receber respostas do usuário, atualize o spec com:
-
-1. **Seção de Clarificações** no início do spec:
-```markdown
-## Clarifications (FASE 3)
-
-### Q1: {Título}
-**Answer:** {Resposta do usuário}
-**Date:** {YYYY-MM-DD}
-```
-
-2. **Atualizar seções relevantes** com detalhes adicionados
-
-### CHECKPOINT: Validar Respostas Completas
-
-**⏸️ PAUSE - Antes de atualizar spec:**
-
-- [ ] Todas as perguntas foram respondidas pelo usuário?
-- [ ] Nenhuma resposta é ambígua ou contraditória?
-- [ ] Respostas são consistentes com `contracts.cs` existente?
-- [ ] Respostas são consistentes com `schema-analysis.md`?
-
-**❌ Se alguma checkbox NÃO estiver marcada:**
-→ Voltar e pedir esclarecimento adicional ao usuário
-
-**✅ Se TODAS as checkboxes estiverem marcadas:**
-→ Prosseguir para atualizar spec.md
-
-### Passo 6: Validar Edge Cases
-
-Documente no spec como lidar com cada edge case identificado:
-
-```markdown
-## Edge Cases
-
-### EC001: {Nome do Edge Case}
-**Scenario:** {Quando acontece}
-**Expected Behavior:** {Como o sistema deve reagir}
-**Implementation Notes:** {Dicas para implementação}
-```
-
-### Passo 7: Atualizar State
-
-## Outputs Gerados/Atualizados
-
-- `.morph/features/$ARGUMENTS/1-design/spec.md` - Atualizado com:
-  - Seção "Clarifications" com perguntas e respostas
-  - Edge cases documentados
-  - Requisitos mais específicos
-- `.morph/features/$ARGUMENTS/2-clarify/clarifications.md` - Novo arquivo com Q&A estruturado
-
-## Critérios de Avanço
-
-- [x] Perguntas de clarificação identificadas (3-7)
-- [x] Perguntas apresentadas ao usuário
-- [x] Respostas do usuário recebidas
-- [x] `spec.md` atualizado com clarificações
-- [x] Edge cases documentados
-- [x] State atualizado
-- [x] Nenhuma ambiguidade crítica remanescente
-
----
-
-## Integração com Superpowers
-
-> Disponível quando o plugin `superpowers` está instalado.
-
-| Skill | Quando Usar | Invocação |
-|-------|-------------|-----------|
-| `systematic-debugging` | Para investigar ambiguidades técnicas complexas | `Skill(superpowers:systematic-debugging)` |
-
----
-
+---
+name: morph:phase-clarify
+description: MORPH-SPEC Phase 3 (Clarify). Reviews spec.md for ambiguities, generates 3-7 targeted clarification questions, waits for user answers, then updates spec with edge cases and clarification sections. Use after design approval to eliminate spec ambiguities before task breakdown begins.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+cliVersion: "4.9.0"
+---
+
+# MORPH Clarify - FASE 3
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Identifique ambiguidades na especificação e faça perguntas de clarificação para garantir que todos os edge cases estão cobertos.
+
+## Pré-requisitos
+
+- [ ] FASE 2 (Design) concluída
+- [ ] `spec.md` aprovado pelo usuário
+- [ ] `contracts.cs` definidos
+
+## 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.
+> **Example:** `references/clarifications-example.md` — filled-in clarifications.md showing expected Q&A format.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Ler spec.md completo | **Read** spec.md | — |
+| Ler contracts.cs | **Read** contracts.cs | — |
+| Ler schema-analysis.md | **Read** schema-analysis.md | — |
+| Verificar viabilidade de requisito | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Verificar issues/limitações conhecidas | **GitHub MCP** `search_issues()` | **Bash** `gh issue list --search "..."` |
+| Pesquisar edge cases externos | **WebSearch** | — |
+| Verificar comportamento UI existente | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | **WebFetch** URL |
+| Atualizar spec com clarificações | **Edit** spec.md | — |
+| Criar clarifications.md | **Bash** `npx morph-spec template render docs/clarifications .morph/features/$ARGUMENTS/2-clarify/clarifications.md` | — |
+| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS clarifications` | — |
+
+**MCPs desta fase:** Context7 (validar viabilidade), GitHub (issues conhecidas), Playwright (verificar UI existente).
+
+**Anti-padrões:**
+- ❌ Task agent para ler spec (use Read direto)
+- ❌ Reescrever spec do zero (use Edit para atualizar seções)
+- ❌ Pular cross-reference com schema-analysis.md (crítico para precisão)
+
+---
+
+## Workflow
+
+### Passo 1: Analisar Spec
+
+Leia `.morph/features/$ARGUMENTS/1-design/spec.md` em detalhes e identifique:
+
+#### 1.1. Ambiguidades
+- Requisitos vagos ou genéricos
+- Termos sem definição clara
+- Comportamentos não especificados
+
+#### 1.2. Edge Cases Não Documentados
+- O que acontece se...?
+- Como lidar com entradas inválidas?
+- Comportamento em caso de erro?
+- Estados intermediários (loading, empty)
+
+#### 1.3. Requisitos Conflitantes
+- Duas funcionalidades que parecem incompatíveis
+- Prioridades não claras (o que vem primeiro?)
+
+#### 1.4. Dados Faltantes
+- Validações de negócio não especificadas
+- Limites e constraints (tamanhos, quantidades)
+- Formatos de dados (datas, moedas, etc.)
+
+### Passo 2: Gerar Perguntas de Clarificação
+
+Com base na análise, gere **3-7 perguntas** focadas e específicas:
+
+**Formato de pergunta:**
+```markdown
+### Q{N}: {Categoria} - {Título}
+
+**Context:** {Por que esta pergunta é importante}
+
+**Question:** {Pergunta clara e objetiva}
+
+**Options (if applicable):**
+- A) {Opção 1}
+- B) {Opção 2}
+- C) {Deixar em aberto/usuário decidir}
+
+**Impact:** {Como a resposta afeta a implementação}
+```
+
+### Passo 3: Categorizar Perguntas
+
+Organize perguntas por categoria:
+
+| Categoria | Descrição | Exemplos |
+|-----------|-----------|----------|
+| **Validação** | Regras de negócio, constraints | Limites de tamanho, formatos aceitos |
+| **Comportamento** | O que acontece quando... | Error handling, estados vazios |
+| **Prioridade** | O que é must-have vs nice-to-have | MVP vs futuras iterações |
+| **Integração** | Como interage com sistemas externos | APIs, webhooks, formato de dados |
+| **Performance** | Requisitos de velocidade/volume | Quantos registros? Tempo de resposta? |
+| **UX** | Experiência do usuário | Feedback visual, mensagens de erro |
+
+### Passo 4: Apresentar Perguntas ao Usuário via AskUserQuestion
+
+Use o tool `AskUserQuestion` para coletar as respostas — **NUNCA liste perguntas como texto simples**.
+
+**Regras:**
+- `AskUserQuestion` aceita **1-4 perguntas por chamada**
+- Se houver 5-7 perguntas, faça **2 chamadas sequenciais** (ex: Q1-Q4 → Q5-Q7)
+- Cada pergunta deve ter `header` (≤12 chars), `question` clara e 2-4 `options`
+- Se a pergunta for aberta sem opções fixas, defina 2-3 opções representativas (o usuário pode usar "Other" para resposta livre)
+- Use `multiSelect: true` quando múltiplas respostas forem igualmente válidas
+- Aguarde o retorno do tool antes de prosseguir para qualquer próximo passo
+
+**Exemplo de estrutura:**
+```json
+{
+  "questions": [
+    {
+      "header": "Validação",
+      "question": "Qual o limite de tamanho para o campo Nome?",
+      "multiSelect": false,
+      "options": [
+        { "label": "100 chars", "description": "Padrão comum para nomes curtos" },
+        { "label": "255 chars", "description": "Máximo típico de banco de dados" },
+        { "label": "Sem limite fixo", "description": "Apenas validação no frontend" }
+      ]
+    }
+  ]
+}
+```
+
+**IMPORTANTE:** Não prossiga para o Passo 5 até receber respostas de TODAS as perguntas!
+
+### Passo 5: Atualizar `spec.md` com Respostas
+
+Após receber respostas do usuário, atualize o spec com:
+
+1. **Seção de Clarificações** no início do spec:
+```markdown
+## Clarifications (FASE 3)
+
+### Q1: {Título}
+**Answer:** {Resposta do usuário}
+**Date:** {YYYY-MM-DD}
+```
+
+2. **Atualizar seções relevantes** com detalhes adicionados
+
+### CHECKPOINT: Validar Respostas Completas
+
+**⏸️ PAUSE - Antes de atualizar spec:**
+
+- [ ] Todas as perguntas foram respondidas pelo usuário?
+- [ ] Nenhuma resposta é ambígua ou contraditória?
+- [ ] Respostas são consistentes com `contracts.cs` existente?
+- [ ] Respostas são consistentes com `schema-analysis.md`?
+
+**❌ Se alguma checkbox NÃO estiver marcada:**
+→ Voltar e pedir esclarecimento adicional ao usuário
+
+**✅ Se TODAS as checkboxes estiverem marcadas:**
+→ Prosseguir para atualizar spec.md
+
+### Passo 6: Validar Edge Cases
+
+Documente no spec como lidar com cada edge case identificado:
+
+```markdown
+## Edge Cases
+
+### EC001: {Nome do Edge Case}
+**Scenario:** {Quando acontece}
+**Expected Behavior:** {Como o sistema deve reagir}
+**Implementation Notes:** {Dicas para implementação}
+```
+
+### Passo 7: Atualizar State
+
+## Outputs Gerados/Atualizados
+
+- `.morph/features/$ARGUMENTS/1-design/spec.md` - Atualizado com:
+  - Seção "Clarifications" com perguntas e respostas
+  - Edge cases documentados
+  - Requisitos mais específicos
+- `.morph/features/$ARGUMENTS/2-clarify/clarifications.md` - Novo arquivo com Q&A estruturado
+
+## Critérios de Avanço
+
+- [x] Perguntas de clarificação identificadas (3-7)
+- [x] Perguntas apresentadas ao usuário
+- [x] Respostas do usuário recebidas
+- [x] `spec.md` atualizado com clarificações
+- [x] Edge cases documentados
+- [x] State atualizado
+- [x] Nenhuma ambiguidade crítica remanescente
+
+---
+
+## Integração com Superpowers
+
+> Disponível quando o plugin `superpowers` está instalado.
+
+| Skill | Quando Usar | Invocação |
+|-------|-------------|-----------|
+| `systematic-debugging` | Para investigar ambiguidades técnicas complexas | `Skill(superpowers:systematic-debugging)` |
+
+---
+
 Continuar automaticamente para FASE 4 (Tasks) após clarificações resolvidas.