version: "1.0.1" name: clavix-refine description: Iterate on existing PRDs or improved prompts to enhance quality. Use when you have a draft that needs further refinement. license: Apache-2.0

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