@polymorphism-tech/morph-spec 4.10.0 → 4.10.1

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

@@ -1,200 +1,206 @@
 ---
 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.
+description: MORPH-SPEC Phase 3 (Clarify). Iterative clarification loop driven by a satisfaction score (0-100). Generates targeted questions per round, always presents "End 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"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+cliVersion: "4.10.1"
 ---
 
-# MORPH Clarify - FASE 3
+# MORPH Clarify — Phase 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.
+Eliminate spec ambiguities through an iterative question loop until the spec has sufficient quality to generate tasks.
 
-## Pré-requisitos
+## Prerequisites
 
-- [ ] FASE 2 (Design) concluída
-- [ ] `spec.md` aprovado pelo usuário
-- [ ] `contracts.cs` definidos
+- [ ] Phase 2 (Design) completed
+- [ ] `spec.md` approved by user
+- [ ] `contracts.cs` (or `contracts.ts`) defined
 
-## Ferramentas Recomendadas
+## Recommended Tools
 
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
 > **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` |
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Read spec + contracts | **Read** all design outputs | — |
+| Verify technical feasibility | **Context7 MCP** `query_docs()` | **WebSearch** |
+| Check external issues/limitations | **GitHub MCP** `search_issues()` | — |
+| Ask clarifying questions | **AskUserQuestion** (never plain text) | — |
+| Update spec with clarifications | **Edit** spec.md | — |
+| Create clarifications.md | **Write** | — |
+| Update state | **Bash** `npx morph-spec state mark-output $ARGUMENTS clarifications` | — |
 
 ---
 
-## Sistema de Pontuação de Satisfação
+## Satisfaction Scoring System
 
-Antes de cada round, calcule o **Satisfaction Score (0–100)** avaliando o spec atual:
+Before each round, calculate the **Satisfaction Score (0-100)** by evaluating the current spec:
 
-| 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 |
+| Dimension | Pts | Maximum Score Criteria |
+|-----------|-----|----------------------|
+| **Functional completeness** | 25 | All requirements have measurable acceptance criteria (no vague "should", "may", "generally") |
+| **Failure coverage** | 20 | All error paths have defined behavior (invalid input, not found, timeout, unauthorized) |
+| **Edge cases** | 20 | Boundaries, concurrent states, empty/extreme inputs documented |
+| **Definitional clarity** | 20 | No critical term undefined, no "TBD", no "to be defined" |
+| **Integration contracts** | 15 | External dependencies have payload format, errors, and retry policy defined |
 
 **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 |
+| Score | Action |
+|-------|--------|
+| >= 85 | Satisfied. Present results and offer "End Clarify" as the primary option |
+| 70-84 | Continue. Focus questions on the lowest-scoring dimensions |
+| < 70 | Continue. Broad questions covering the largest gaps |
 
-> 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.
+> The score rises as answers are incorporated. There's no fixed maximum rounds — the loop ends when score >= 85 **or** the user chooses to end.
 
 ---
 
 ## Workflow
 
-### Inicialização
+### Initialization
 
-**PASSO 0 (ANTES de qualquer escrita) — Garantir fase clarify:**
+**Step 0 (BEFORE any writing) — Ensure clarify phase:**
 
 ```bash
 npx morph-spec state get $ARGUMENTS
 ```
 
-Verifique o campo `"phase"` no output:
+Check the `"phase"` field in the output:
 
-**Se `"phase": "clarify"`** → ✅ fase correta, prossiga.
+**If `"phase": "clarify"`** → correct phase, proceed.
 
-**Se `"phase": "design"`** → execute em sequência:
+**If `"phase": "design"`** → run in sequence:
 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.
+**Any other value** → STOP — inconsistent state, report to user.
 
-> **Regra:** Nunca escreva `clarifications.md` ou atualize `spec.md` enquanto a fase não for `clarify`.
+> **Rule:** Never write `clarifications.md` or update `spec.md` until the phase is `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)
+Read the base files in PARALLEL:
 
-Calcule o score inicial. Registre mentalmente as respostas acumuladas de rounds anteriores para não repetir perguntas já respondidas.
+```
+Read: .morph/features/$ARGUMENTS/1-design/spec.md
+    + Read: .morph/features/$ARGUMENTS/1-design/contracts.cs  (or contracts.ts for TypeScript)
+    + Read: .morph/features/$ARGUMENTS/1-design/schema-analysis.md  (if exists)
+```
+
+Calculate the initial score. Track accumulated answers from prior rounds to avoid repeating already-answered questions.
 
 ---
 
-### Loop Principal
+### Main Loop
+
+**Repeat until: score >= 85 OR user chooses to end.**
 
-**Repita até: score ≥ 85 OU usuário escolhe encerrar.**
+#### A. Calculate Current Round Score
 
-#### A. Calcular Score do Round Atual
+Score each dimension based on the spec + accumulated answers. Note which dimensions are weakest — they guide this round's questions.
 
-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. Identify New Questions
 
-#### B. Identificar Questões Novas
+Analyze only what **hasn't been answered yet**. Categorize by dimension:
 
-Analise apenas o que **ainda não foi respondido**. Categorize por dimensão:
+| Category | Example Questions |
+|----------|-------------------|
+| **Validation** | Field limits, accepted formats, business rules |
+| **Behavior** | What happens when X fails? Empty state? Loading state? |
+| **Priority** | Must-have vs nice-to-have? MVP vs v2? |
+| **Integration** | Webhook vs polling? Retry policy? Timeout? |
+| **Performance** | Expected volume? Response SLA? |
+| **UX** | Error message shown to user? Visual feedback? |
 
-| 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. Present Questions via `AskUserQuestion`
 
-#### C. Apresentar Perguntas via `AskUserQuestion`
+**Why this matters:** AskUserQuestion gives structured options the user can click — far better UX than walls of text. It also captures answers programmatically for the clarifications.md output.
 
-**Regras obrigatórias:**
+**Rules:**
 
-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:**
+1. Use `AskUserQuestion` — **NEVER list questions as plain text**
+2. Maximum **4 questions per call** (tool limit)
+3. If there are more than 3 new questions, make sequential calls — the **exit option always appears in the last call of each round**
+4. **Always include the following question as the last in the final batch of each round:**
 
 ```json
 {
-  "header": "Encerrar?",
-  "question": "Deseja encerrar a fase Clarify agora ou continuar refinando o spec?",
+  "header": "End Clarify?",
+  "question": "End the Clarify phase now or continue refining the spec?",
   "multiSelect": false,
   "options": [
     {
-      "label": "Continuar refinando",
-      "description": "Claude identificou mais questões abertas neste round"
+      "label": "Continue refining",
+      "description": "There are still open questions identified in this round"
     },
     {
-      "label": "Encerrar Clarify",
-      "description": "Prosseguir para fase Tasks com o spec no estado atual"
+      "label": "End Clarify",
+      "description": "Proceed to Plan phase with the spec in its current state"
     }
   ]
 }
 ```
 
-> 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"`
+> If score >= 85, adjust the first option label to: `"Continue (optional)"` with description: `"Score ${score}/100 — spec is satisfactory, but you can refine further"`
 
-#### D. Aguardar e Incorporar Respostas
+#### D. Wait and Incorporate Answers
 
-**Não avance antes de receber todas as respostas.**
+**Do not proceed before receiving all responses.**
 
-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`
+After receiving answers:
+1. Check if the answer is consistent with `contracts.cs` and `schema-analysis.md`
+2. If any answer is ambiguous or contradictory → ask for clarification before updating
+3. Update `spec.md` with:
+   - Section `## Clarifications (Phase 3)` with structured Q&A
+   - Updates to affected functional sections
+   - New edge cases in `## Edge Cases`
 
-#### E. Verificar Condição de Saída
+#### E. Check Exit Condition
 
-- 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
+- User chose **"End Clarify"** → exit loop
+- Score >= 85 AND no new questions identified → exit loop
+- Otherwise → return to A
 
 ---
 
-### Pós-Loop: Gerar Outputs
+### Post-Loop: Generate Outputs
 
-**Passo 1: Criar `clarifications.md`**
+**Step 1: Create `clarifications.md`**
 
-Escreva em `.morph/features/$ARGUMENTS/1-design/clarifications.md`:
+Write to `.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
+**Phase:** Clarify (Phase 3)
+**Rounds completed:** {N}
+**Final score:** {score}/100
+**Status:** Resolved — incorporated into spec.md
 
 ---
 
 ## Questions & Answers
 
-### Q{N}: {Título}
-**Question:** {pergunta}
-**Answer:** {resposta do usuário}
-**Spec Updates:** {quais seções foram atualizadas}
+### Q{N}: {Title}
+**Question:** {question}
+**Answer:** {user's answer}
+**Spec Updates:** {which sections were updated}
 **Priority:** High/Medium/Low
-**Resolved:** ✅ Yes
+**Resolved:** Yes
 
 ---
 
 ## Edge Cases
 
-### EC{N}: {Nome}
-**Scenario:** {quando acontece}
-**Expected Behavior:** {como o sistema reage}
-**Implementation Notes:** {dicas}
+### EC{N}: {Name}
+**Scenario:** {when it happens}
+**Expected Behavior:** {how the system reacts}
+**Implementation Notes:** {tips}
 
 ---
 
@@ -205,10 +211,10 @@ Escreva em `.morph/features/$ARGUMENTS/1-design/clarifications.md`:
 | Questions Answered | {N} |
 | Edge Cases Documented | {N} |
 | Spec Sections Updated | {N} |
-| Score Final | {score}/100 |
+| Final Score | {score}/100 |
 ```
 
-**Passo 2: Atualizar State**
+**Step 2: Update State**
 
 ```bash
 npx morph-spec state mark-output $ARGUMENTS clarifications
@@ -216,18 +222,21 @@ npx morph-spec state mark-output $ARGUMENTS clarifications
 
 ---
 
-## Outputs Gerados/Atualizados
+## Phase Outputs
 
-- `.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
+<!-- morph:outputs:clarify -->
+| Output | Path |
+|--------|------|
+| `clarifications` | `.morph/features/{feature}/1-design/clarifications.md` |
+<!-- /morph:outputs -->
 
-## Critérios de Avanço
+## Advancement Criteria
 
-- [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`)
+- [x] Satisfaction score >= 85 OR user opted to end
+- [x] All answers are consistent with `contracts.cs`
+- [x] `spec.md` updated with clarifications and edge cases
+- [x] `clarifications.md` created with Q&A and final score
+- [x] State updated (`mark-output clarifications`)
 
 ---
 
@@ -235,4 +244,4 @@ npx morph-spec state mark-output $ARGUMENTS clarifications
 npx morph-spec phase advance $ARGUMENTS
 ```
 
-Continuar automaticamente para FASE 4 (Plan) após clarifications.md gerado.
+Continue automatically to Phase 4 (Plan) after clarifications.md is generated.