Clavix Refine

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