Clavix Refine Skill

Clavix Refine Skill

Update your PRD or improve a saved prompt. We're refining what exists, not starting over.

What This Skill Does

1. Find what you've got - Look for your PRDs and saved prompts
2. Ask what to update - Which one do you want to refine?
3. Load it up - Read what's there now
4. Talk through changes - What do you want to add, change, or remove?
5. Save the update - Keep track of what changed

---

State Assertion (REQUIRED)

Before starting refinement, output:

**CLAVIX MODE: Refinement**
Mode: planning
Purpose: Updating existing PRD or prompt
Implementation: BLOCKED - I'll update requirements, not build them

---

Self-Correction Protocol

DETECT: If you find yourself doing any of these 6 mistake types:

STOP: Immediately halt the incorrect action

CORRECT: Output: "I apologize - I was [describe mistake]. Let me get back to refining your existing work."

RESUME: Return to refinement mode - load content and discuss changes.

---

Step 1: Source Discovery

Check what's available to refine:

Looking for PRDs:

• .clavix/​outputs/​*/​mini-prd.md
• .clavix/​outputs/​*/​quick-prd.md
• .clavix/​outputs/​*/​full-prd.md

Looking for saved prompts:

• .clavix/​outputs/​prompts/​*.md

What you'll see:

Found 2 PRD projects and 3 saved prompts.
Which would you like to refine?

List what's found with project names and file types.

---

Step 2: Interactive Selection

If you have both PRDs and prompts:

"I found some things you can refine:

PRD Projects:

• user-auth (has PRD and tasks)
• dashboard (has PRD)

Saved Prompts:

• api-integration.md
• payment-flow.md

Which one do you want to update?"

If you only have PRDs:

"Found your user-auth PRD. Want to update it?

I can help you:

• Add new features
• Change existing requirements
• Adjust scope or constraints
• Update tech requirements"

If you only have prompts:

"Found 2 saved prompts:

• api-integration.md (Dec 1)
• payment-flow.md (Nov 28)

Which one should we improve?"

If nothing exists:

"I don't see any PRDs or saved prompts to refine yet.

To create something first:

• /​clavix-prd - Create a new PRD
• /​clavix-improve [prompt] - Save an optimized prompt
• /​clavix-start then /​clavix-summarize - Extract from chat

Once you've got something, come back and we can refine it!"

---

PRD Refinement Flow

Step 3: Show Current Content

Read and summarize the current PRD:

"Here's your user-auth PRD:

Goal: Build secure user authentication system

Features:

• User registration
• Login/​logout
• Session management

Tech: Node.js, JWT tokens, PostgreSQL

Out of Scope: Social login, 2FA

---

What do you want to change?"

Step 4: Ask What to Change

Options to present:

• Add new features?
• Change existing requirements?
• Update tech requirements?
• Adjust scope?

Step 5: Track All Changes

Use change markers for everything:

• [ADDED] - New stuff
• [MODIFIED] - Changed stuff
• [REMOVED] - Removed stuff
• [UNCHANGED] - Kept as-is

Step 6: Save with Refinement History

Add a history section to the document:

## Refinement History

### {Date}
**Changes:**
- [ADDED] Password reset via email
- [MODIFIED] Now using bcrypt instead of plain JWT
- [REMOVED] Session management (moved to separate feature)

**Why:** User feedback needed password reset, security upgrade

---

Tasks Impact Warning (CRITICAL)

If tasks.md exists AND PRD changed significantly:

"⚠️ Your tasks.md was made from the old PRD.

After these changes, you might want to:

• Run /​clavix-plan to regenerate tasks
• Or manually update tasks.md

Biggest changes that affect tasks:

• New password reset feature
• Different auth approach
• Removed session management"

Always list the changes that would affect existing tasks.

---

Prompt Refinement Flow

Step 3: Pick Which Prompt

If multiple saved prompts exist:

"Which prompt do you want to refine?

1. api-integration.md (Dec 1)
2. payment-flow.md (Nov 28)

Pick a number or say 'latest' for the most recent."

Step 4: Show Current Quality

Display prompt with quality scores:

"Here's your current prompt:

'Build an API integration for our system.'

Quality scores:

• Clarity: 40/​100 (too vague)
• Specificity: 30/​100 (no details)
• Completeness: 20/​100 (missing info)

What do you want to improve?

• Make it more specific?
• Add context or constraints?
• Clarify the goal?
• Something else?"

Step 5: Apply Quality Patterns & Show Comparison

Enhance using quality patterns, then show before/​after:

---

Save + Verify Protocol

1. Write file to save location
2. Read file to verify exists
3. Show user actual saved path

Save Locations:

• PRDs: .clavix/​outputs/​{project}/​full-prd.md
• Prompts: .clavix/​outputs/​prompts/<id>.md

---

Mode Boundaries

Do: Find existing docs, ask which to update, show current state, track changes, add history, warn about task impact

Don't: Write code, create new PRDs/​prompts, remove requirements without approval

---

Workflow Navigation

Common flows:

• Update PRD → /​clavix-refine → /​clavix-plan
• Improve prompt → /​clavix-refine → /​clavix-implement --latest

Related: /​clavix-prd, /​clavix-improve, /​clavix-plan, /​clavix-implement