@polymorphism-tech/morph-spec 4.10.7 → 4.10.9

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

@@ -1,247 +1,247 @@
----
-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 "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, AskUserQuestion
-cliVersion: "4.10.7"
----
-
-# MORPH Clarify — Phase 3
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Eliminate spec ambiguities through an iterative question loop until the spec has sufficient quality to generate tasks.
-
-## Prerequisites
-
-- [ ] Phase 2 (Design) completed
-- [ ] `spec.md` approved by user
-- [ ] `contracts.cs` (or `contracts.ts`) defined
-
-## Recommended Tools
-
-> **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.
-
-| 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` | — |
-
----
-
-## Satisfaction Scoring System
-
-Before each round, calculate the **Satisfaction Score (0-100)** by evaluating the current spec:
-
-| 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 | 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 |
-
-> 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
-
-### Initialization
-
-**Step 0 (BEFORE any writing) — Ensure clarify phase:**
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field in the output:
-
-**If `"phase": "clarify"`** → correct phase, proceed.
-
-**If `"phase": "design"`** → run in sequence:
-1. `npx morph-spec approve $ARGUMENTS design`
-2. `npx morph-spec phase advance $ARGUMENTS` (→ clarify)
-
-**Any other value** → STOP — inconsistent state, report to user.
-
-> **Rule:** Never write `clarifications.md` or update `spec.md` until the phase is `clarify`.
-
----
-
-Read the base files in PARALLEL:
-
-```
-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.
-
----
-
-### Main Loop
-
-**Repeat until: score >= 85 OR user chooses to end.**
-
-#### A. Calculate Current Round Score
-
-Score each dimension based on the spec + accumulated answers. Note which dimensions are weakest — they guide this round's questions.
-
-#### B. Identify New Questions
-
-Analyze only what **hasn't been answered yet**. Categorize by dimension:
-
-| 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? |
-
-#### C. Present Questions 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.
-
-**Rules:**
-
-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": "End Clarify?",
-  "question": "End the Clarify phase now or continue refining the spec?",
-  "multiSelect": false,
-  "options": [
-    {
-      "label": "Continue refining",
-      "description": "There are still open questions identified in this round"
-    },
-    {
-      "label": "End Clarify",
-      "description": "Proceed to Plan phase with the spec in its current state"
-    }
-  ]
-}
-```
-
-> 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. Wait and Incorporate Answers
-
-**Do not proceed before receiving all responses.**
-
-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. Check Exit Condition
-
-- User chose **"End Clarify"** → exit loop
-- Score >= 85 AND no new questions identified → exit loop
-- Otherwise → return to A
-
----
-
-### Post-Loop: Generate Outputs
-
-**Step 1: Create `clarifications.md`**
-
-Write to `.morph/features/$ARGUMENTS/1-design/clarifications.md`:
-
-```markdown
-# Clarifications — {Feature Name}
-
-**Phase:** Clarify (Phase 3)
-**Rounds completed:** {N}
-**Final score:** {score}/100
-**Status:** Resolved — incorporated into spec.md
-
----
-
-## Questions & Answers
-
-### Q{N}: {Title}
-**Question:** {question}
-**Answer:** {user's answer}
-**Spec Updates:** {which sections were updated}
-**Priority:** High/Medium/Low
-**Resolved:** Yes
-
----
-
-## Edge Cases
-
-### EC{N}: {Name}
-**Scenario:** {when it happens}
-**Expected Behavior:** {how the system reacts}
-**Implementation Notes:** {tips}
-
----
-
-## Summary
-
-| | Count |
-|---|---|
-| Questions Answered | {N} |
-| Edge Cases Documented | {N} |
-| Spec Sections Updated | {N} |
-| Final Score | {score}/100 |
-```
-
-**Step 2: Update State**
-
-```bash
-npx morph-spec state mark-output $ARGUMENTS clarifications
-```
-
----
-
-## Phase Outputs
-
-<!-- morph-outputs:clarify -->
-| Output | Path |
-|--------|------|
-| `clarifications` | `.morph/features/{feature}/1-design/clarifications.md` |
-<!-- /morph-outputs -->
-
-## Advancement Criteria
-
-- [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`)
-
----
-
-```bash
-npx morph-spec phase advance $ARGUMENTS
-```
-
-Continue automatically to Phase 4 (Plan) after clarifications.md is generated.
+---
+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 "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, AskUserQuestion
+cliVersion: "4.10.9"
+---
+
+# MORPH Clarify — Phase 3
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Eliminate spec ambiguities through an iterative question loop until the spec has sufficient quality to generate tasks.
+
+## Prerequisites
+
+- [ ] Phase 2 (Design) completed
+- [ ] `spec.md` approved by user
+- [ ] `contracts.cs` (or `contracts.ts`) defined
+
+## Recommended Tools
+
+> **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.
+
+| 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` | — |
+
+---
+
+## Satisfaction Scoring System
+
+Before each round, calculate the **Satisfaction Score (0-100)** by evaluating the current spec:
+
+| 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 | 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 |
+
+> 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
+
+### Initialization
+
+**Step 0 (BEFORE any writing) — Ensure clarify phase:**
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Check the `"phase"` field in the output:
+
+**If `"phase": "clarify"`** → correct phase, proceed.
+
+**If `"phase": "design"`** → run in sequence:
+1. `npx morph-spec approve $ARGUMENTS design`
+2. `npx morph-spec phase advance $ARGUMENTS` (→ clarify)
+
+**Any other value** → STOP — inconsistent state, report to user.
+
+> **Rule:** Never write `clarifications.md` or update `spec.md` until the phase is `clarify`.
+
+---
+
+Read the base files in PARALLEL:
+
+```
+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.
+
+---
+
+### Main Loop
+
+**Repeat until: score >= 85 OR user chooses to end.**
+
+#### A. Calculate Current Round Score
+
+Score each dimension based on the spec + accumulated answers. Note which dimensions are weakest — they guide this round's questions.
+
+#### B. Identify New Questions
+
+Analyze only what **hasn't been answered yet**. Categorize by dimension:
+
+| 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? |
+
+#### C. Present Questions 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.
+
+**Rules:**
+
+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": "End Clarify?",
+  "question": "End the Clarify phase now or continue refining the spec?",
+  "multiSelect": false,
+  "options": [
+    {
+      "label": "Continue refining",
+      "description": "There are still open questions identified in this round"
+    },
+    {
+      "label": "End Clarify",
+      "description": "Proceed to Plan phase with the spec in its current state"
+    }
+  ]
+}
+```
+
+> 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. Wait and Incorporate Answers
+
+**Do not proceed before receiving all responses.**
+
+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. Check Exit Condition
+
+- User chose **"End Clarify"** → exit loop
+- Score >= 85 AND no new questions identified → exit loop
+- Otherwise → return to A
+
+---
+
+### Post-Loop: Generate Outputs
+
+**Step 1: Create `clarifications.md`**
+
+Write to `.morph/features/$ARGUMENTS/1-design/clarifications.md`:
+
+```markdown
+# Clarifications — {Feature Name}
+
+**Phase:** Clarify (Phase 3)
+**Rounds completed:** {N}
+**Final score:** {score}/100
+**Status:** Resolved — incorporated into spec.md
+
+---
+
+## Questions & Answers
+
+### Q{N}: {Title}
+**Question:** {question}
+**Answer:** {user's answer}
+**Spec Updates:** {which sections were updated}
+**Priority:** High/Medium/Low
+**Resolved:** Yes
+
+---
+
+## Edge Cases
+
+### EC{N}: {Name}
+**Scenario:** {when it happens}
+**Expected Behavior:** {how the system reacts}
+**Implementation Notes:** {tips}
+
+---
+
+## Summary
+
+| | Count |
+|---|---|
+| Questions Answered | {N} |
+| Edge Cases Documented | {N} |
+| Spec Sections Updated | {N} |
+| Final Score | {score}/100 |
+```
+
+**Step 2: Update State**
+
+```bash
+npx morph-spec state mark-output $ARGUMENTS clarifications
+```
+
+---
+
+## Phase Outputs
+
+<!-- morph-outputs:clarify -->
+| Output | Path |
+|--------|------|
+| `clarifications` | `.morph/features/{feature}/1-design/clarifications.md` |
+<!-- /morph-outputs -->
+
+## Advancement Criteria
+
+- [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`)
+
+---
+
+```bash
+npx morph-spec phase advance $ARGUMENTS
+```
+
+Continue automatically to Phase 4 (Plan) after clarifications.md is generated.