refactor(skills): restore process controls in phase-1-clarify

Keep concise principle-based approach while restoring essential
workflow controls:
- Explicit step numbering (Step 1-6)
- PRD backup mechanism with bash script
- State transition command (ralph-dev state update)
- AskUserQuestion tool constraints (max 4, header ≤12 chars)
- Required PHASE RESULT output format
- Error handling with recovery actions

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: mylukin

skills/phase-1-clarify/SKILL.md

@@ -9,84 +9,83 @@ user-invocable: false
 
 ## Goal
 
-Transform user requirements into a comprehensive PRD (Product Requirements Document) that preserves all context from prior conversations.
+Transform user requirements into a comprehensive PRD that preserves all context from prior conversations.
 
 ## Core Principle
 
-**Context preservation is the primary goal.** If the user discussed UI layouts, data models, or design decisions before invoking `/ralph-dev`, that information MUST be captured in the PRD - not lost.
+**Context preservation is the primary goal.** If the user discussed UI layouts, data models, or design decisions before invoking `/ralph-dev`, that information MUST be captured in the PRD.
+
+---
 
 ## Workflow
 
-### 1. Extract Context First (CRITICAL)
+### Step 1: Extract Context (CRITICAL - Do This First)
 
 Before asking ANY questions, scan the conversation history for:
 
 - **UI/UX**: layouts, wireframes, pages, components, design decisions
 - **Data**: entities, models, schemas, fields, relationships
 - **API**: endpoints, requests, responses, authentication
 - **Flows**: user journeys, processes, interactions
-- **Decisions**: choices made, alternatives considered, trade-offs accepted
+- **Decisions**: choices made, alternatives considered, trade-offs
 
-Convert discussions into structured formats:
-- Layout descriptions → ASCII wireframes
-- Data discussions → TypeScript interfaces
-- API discussions → Endpoint specifications
-- Decisions → Decision log with rationale
+Convert to structured formats as appropriate (ASCII wireframes, TypeScript interfaces, endpoint specs, decision logs).
 
-### 2. Identify Gaps
+### Step 2: Identify Gaps
 
-After extraction, determine what's MISSING:
+Determine what's MISSING after extraction:
 - Tech stack? Scale? Authentication? Deployment?
-- Only ask about information NOT already discussed
+- Only proceed to ask about information NOT already discussed
 
-### 3. Confirm & Ask
+### Step 3: Confirm & Ask Questions
 
-If context was extracted:
-1. Show summary of what was extracted
-2. Ask user to confirm accuracy
-3. Only ask questions for gaps
+**If context was extracted:**
+1. Display summary of extracted context to user
+2. Use `AskUserQuestion` to confirm accuracy
+3. Only ask additional questions for gaps
 
-If no prior context:
+**If no prior context:**
 - Ask standard clarification questions (app type, tech stack, scale, auth)
 
-**Tool**: Use `AskUserQuestion` with max 4 questions per call, each with `header` (≤12 chars), `multiSelect`, and 2-4 `options`.
+### Step 4: Generate PRD
 
-### 4. Generate PRD
-
-Create a comprehensive PRD that includes:
+Create PRD with these sections (include only if relevant):
 
 1. **Project Overview** - Goals, scope, constraints
 2. **Technical Stack** - Language, frameworks, database, deployment
-3. **UI/UX Design** - Wireframes, components, design tokens (if discussed)
-4. **Data Model** - Entities, relationships, schemas (if discussed)
-5. **API Contracts** - Endpoints, auth, errors (if discussed)
-6. **User Flows** - Key journeys, edge cases (if discussed)
-7. **User Stories** - Epics and stories with acceptance criteria
-8. **Design Decisions** - Choices made with rationale (if discussed)
+3. **UI/UX Design** - Wireframes, components, design tokens *(if discussed)*
+4. **Data Model** - Entities, relationships, schemas *(if discussed)*
+5. **API Contracts** - Endpoints, auth, errors *(if discussed)*
+6. **User Flows** - Key journeys, edge cases *(if discussed)*
+7. **User Stories** - Epics with acceptance criteria
+8. **Design Decisions** - Choices with rationale *(if discussed)*
 9. **Non-Functional Requirements** - Performance, security, testing
 10. **Appendix: Context Summary** - Key points from conversation
 
-**Note**: Sections 3-6 and 8 are only needed if relevant context was discussed. Don't pad with generic content.
-
-### 5. Save & Transition
+### Step 5: Save PRD
 
 ```bash
-# Backup existing PRD if present
-# Save to .ralph-dev/prd.md
-# Update state: ralph-dev state update --phase breakdown
-```
+mkdir -p .ralph-dev
 
-## Constraints
+# REQUIRED: Backup existing PRD before overwriting
+if [ -f ".ralph-dev/prd.md" ]; then
+  BACKUP_TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+  cp .ralph-dev/prd.md ".ralph-dev/prd.${BACKUP_TIMESTAMP}.bak"
+  # Keep only last 5 backups
+  ls -t .ralph-dev/prd.*.bak 2>/dev/null | tail -n +6 | xargs -r rm -f
+fi
 
-- **NEVER** lose context from prior discussions
-- **NEVER** ask questions about information already provided
-- **NEVER** generate generic filler content - only include what's relevant
-- **ALWAYS** use `AskUserQuestion` tool, not plain text questions
-- **ALWAYS** confirm extracted context before proceeding
+# Save PRD using Write tool to .ralph-dev/prd.md
+```
+
+### Step 6: Update State & Return Result
 
-## Output
+```bash
+# REQUIRED: Transition to next phase
+ralph-dev state update --phase breakdown
+```
 
-Return structured result:
+**REQUIRED Output Format** (orchestrator parses this):
 ```yaml
 ---PHASE RESULT---
 phase: clarify
@@ -97,10 +96,41 @@ next_phase: breakdown
 ---END PHASE RESULT---
 ```
 
+---
+
+## Tool Constraints
+
+### AskUserQuestion
+
+- **Max 4 questions** per tool call
+- Each question requires:
+  - `question`: The question text
+  - `header`: Short label (≤12 chars), e.g., "App Type", "Tech Stack"
+  - `multiSelect`: true/false
+  - `options`: 2-4 choices, each with `label` and `description`
+- Add "(Recommended)" suffix to suggested default option
+- "Other" option is auto-provided by Claude Code
+- **60-second timeout** - keep questions simple
+
+---
+
+## Constraints
+
+- **NEVER** lose context from prior discussions
+- **NEVER** ask questions about information already provided
+- **NEVER** generate generic filler content - only include relevant sections
+- **NEVER** ask questions in plain text - always use `AskUserQuestion` tool
+- **ALWAYS** backup existing PRD before overwriting
+- **ALWAYS** update state via CLI after completion
+- **ALWAYS** return structured PHASE RESULT block
+
+---
+
 ## Error Handling
 
 | Error | Action |
 |-------|--------|
-| User cancels | Save partial state, return status: cancelled |
-| Context extraction unclear | Ask user to clarify specific points |
-| PRD generation fails | Use minimal viable PRD with available info |
+| User cancels | Save partial state, return `status: cancelled` |
+| Context unclear | Ask user to clarify specific points |
+| PRD generation fails | Use minimal PRD with available info |
+| State update fails | Log error, retry once, then report to orchestrator |