@polymorphism-tech/morph-spec 4.9.0 → 4.10.0

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

@@ -0,0 +1,238 @@
+---
+name: morph:phase-clarify
+description: MORPH-SPEC Phase 3 (Clarify). Iterative clarification loop driven by a satisfaction score (0-100). Generates targeted questions per round, always presents "Encerrar Clarify" as exit option, and stops when score ≥ 85 or user exits. 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.10.0"
+---
+
+# MORPH Clarify - FASE 3
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Elimine ambiguidades da especificação através de um loop iterativo de perguntas até que o spec tenha qualidade suficiente para gerar tasks.
+
+## Pré-requisitos
+
+- [ ] FASE 2 (Design) concluída
+- [ ] `spec.md` aprovado pelo usuário
+- [ ] `contracts.cs` definidos
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
+> **Example:** `references/clarifications-example.md` — filled-in clarifications.md showing expected Q&A format.
+
+| Ação | Ferramenta |
+|------|------------|
+| Ler spec.md + contracts.cs | **Read** |
+| Verificar viabilidade técnica | **Context7 MCP** `query_docs()` |
+| Verificar issues/limitações externas | **GitHub MCP** `search_issues()` |
+| Atualizar spec com clarificações | **Edit** spec.md |
+| Criar clarifications.md | **Write** |
+| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS clarifications` |
+
+---
+
+## Sistema de Pontuação de Satisfação
+
+Antes de cada round, calcule o **Satisfaction Score (0–100)** avaliando o spec atual:
+
+| Dimensão | Pts | Critério de máxima pontuação |
+|----------|-----|------------------------------|
+| **Completude funcional** | 25 | Todos os requisitos têm critérios de aceitação mensuráveis (sem "deve", "pode", "em geral") |
+| **Cobertura de falhas** | 20 | Todos os caminhos de erro têm comportamento definido (invalid input, not found, timeout, unauthorized) |
+| **Edge cases** | 20 | Limites, estados concorrentes, inputs vazios/extremos documentados |
+| **Clareza definitória** | 20 | Nenhum termo crítico sem definição, nenhum "TBD", nenhum "a definir" |
+| **Contratos de integração** | 15 | Dependências externas têm formato de payload, erros e retry policy definidos |
+
+**Thresholds:**
+
+| Score | Ação |
+|-------|------|
+| ≥ 85 | Claude está satisfeito. Apresentar resultado e oferecer "Encerrar" como opção principal |
+| 70–84 | Continuar. Focar perguntas nas dimensões com menor pontuação |
+| < 70 | Continuar. Perguntas amplas cobrindo as maiores lacunas |
+
+> O score sobe conforme as respostas são incorporadas. Não há número máximo fixo de rounds — o loop para quando o score ≥ 85 **ou** quando o usuário escolhe encerrar.
+
+---
+
+## Workflow
+
+### Inicialização
+
+**PASSO 0 (ANTES de qualquer escrita) — Garantir fase clarify:**
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Verifique o campo `"phase"` no output:
+
+**Se `"phase": "clarify"`** → ✅ fase correta, prossiga.
+
+**Se `"phase": "design"`** → execute em sequência:
+1. `npx morph-spec approve $ARGUMENTS design`
+2. `npx morph-spec phase advance $ARGUMENTS` (→ clarify)
+
+**Qualquer outro valor** → ⛔ não prossiga — estado inconsistente, reporte ao usuário.
+
+> **Regra:** Nunca escreva `clarifications.md` ou atualize `spec.md` enquanto a fase não for `clarify`.
+
+---
+
+Leia os arquivos base:
+- `.morph/features/$ARGUMENTS/1-design/spec.md`
+- `.morph/features/$ARGUMENTS/1-design/contracts.cs`
+- `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` (se existir)
+
+Calcule o score inicial. Registre mentalmente as respostas acumuladas de rounds anteriores para não repetir perguntas já respondidas.
+
+---
+
+### Loop Principal
+
+**Repita até: score ≥ 85 OU usuário escolhe encerrar.**
+
+#### A. Calcular Score do Round Atual
+
+Pontue cada dimensão com base no spec + respostas acumuladas. Anote quais dimensões estão mais fracas — elas guiam as perguntas deste round.
+
+#### B. Identificar Questões Novas
+
+Analise apenas o que **ainda não foi respondido**. Categorize por dimensão:
+
+| Categoria | Exemplos de questões |
+|-----------|----------------------|
+| **Validação** | Limites de campo, formatos aceitos, regras de negócio |
+| **Comportamento** | O que acontece quando X falha? Estado vazio? Loading? |
+| **Prioridade** | Must-have vs nice-to-have? MVP vs v2? |
+| **Integração** | Webhook vs polling? Retry policy? Timeout? |
+| **Performance** | Volume esperado? SLA de resposta? |
+| **UX** | Mensagem de erro exibida ao usuário? Feedback visual? |
+
+#### C. Apresentar Perguntas via `AskUserQuestion`
+
+**Regras obrigatórias:**
+
+1. Use `AskUserQuestion` — **NUNCA liste perguntas como texto simples**
+2. Máximo **4 perguntas por chamada** (incluindo a opção de encerrar)
+3. Se houver mais de 3 questões novas, faça chamadas sequenciais — mas a **opção de encerrar aparece SEMPRE na última chamada de cada round**
+4. **SEMPRE inclua a seguinte pergunta como última do último batch de cada round:**
+
+```json
+{
+  "header": "Encerrar?",
+  "question": "Deseja encerrar a fase Clarify agora ou continuar refinando o spec?",
+  "multiSelect": false,
+  "options": [
+    {
+      "label": "Continuar refinando",
+      "description": "Claude identificou mais questões abertas neste round"
+    },
+    {
+      "label": "Encerrar Clarify",
+      "description": "Prosseguir para fase Tasks com o spec no estado atual"
+    }
+  ]
+}
+```
+
+> Se score ≥ 85, ajuste o label da primeira opção para: `"Continuar (opcional)"` com description: `"Score ${score}/100 — spec está satisfatório, mas você pode refinar mais"`
+
+#### D. Aguardar e Incorporar Respostas
+
+**Não avance antes de receber todas as respostas.**
+
+Após receber:
+1. Verifique se a resposta é consistente com `contracts.cs` e `schema-analysis.md`
+2. Se alguma resposta for ambígua ou contraditória → peça esclarecimento antes de atualizar
+3. Atualize `spec.md` com:
+   - Seção `## Clarifications (FASE 3)` com Q&A estruturado
+   - Atualização das seções funcionais afetadas
+   - Novos edge cases em `## Edge Cases`
+
+#### E. Verificar Condição de Saída
+
+- Usuário escolheu **"Encerrar Clarify"** → sair do loop
+- Score ≥ 85 E nenhuma questão nova identificada → sair do loop
+- Caso contrário → voltar para A
+
+---
+
+### Pós-Loop: Gerar Outputs
+
+**Passo 1: Criar `clarifications.md`**
+
+Escreva em `.morph/features/$ARGUMENTS/1-design/clarifications.md`:
+
+```markdown
+# Clarifications — {Feature Name}
+
+**Fase:** CLARIFY (Fase 3)
+**Rounds realizados:** {N}
+**Score final:** {score}/100
+**Status:** Resolvido — incorporado em spec.md
+
+---
+
+## Questions & Answers
+
+### Q{N}: {Título}
+**Question:** {pergunta}
+**Answer:** {resposta do usuário}
+**Spec Updates:** {quais seções foram atualizadas}
+**Priority:** High/Medium/Low
+**Resolved:** ✅ Yes
+
+---
+
+## Edge Cases
+
+### EC{N}: {Nome}
+**Scenario:** {quando acontece}
+**Expected Behavior:** {como o sistema reage}
+**Implementation Notes:** {dicas}
+
+---
+
+## Summary
+
+| | Count |
+|---|---|
+| Questions Answered | {N} |
+| Edge Cases Documented | {N} |
+| Spec Sections Updated | {N} |
+| Score Final | {score}/100 |
+```
+
+**Passo 2: Atualizar State**
+
+```bash
+npx morph-spec state mark-output $ARGUMENTS clarifications
+```
+
+---
+
+## Outputs Gerados/Atualizados
+
+- `.morph/features/$ARGUMENTS/1-design/spec.md` — Seção "Clarifications", edge cases, requisitos refinados
+- `.morph/features/$ARGUMENTS/1-design/clarifications.md` — Q&A estruturado com score final
+
+## Critérios de Avanço
+
+- [x] Score de satisfação ≥ 85 OU usuário optou por encerrar
+- [x] Todas as respostas são consistentes com `contracts.cs`
+- [x] `spec.md` atualizado com clarificações e edge cases
+- [x] `clarifications.md` criado com Q&A e score final
+- [x] State atualizado (`mark-output clarifications`)
+
+---
+
+```bash
+npx morph-spec phase advance $ARGUMENTS
+```
+
+Continuar automaticamente para FASE 4 (Plan) após clarifications.md gerado.