Voiceprint Refine - Iterative Writer Skill Improvement

Voiceprint Refine - Iterative Writer Skill Improvement

Surgically improve an existing writer skill without re-running the full questionnaire. Users discover gaps when using their writer skill in practice - this workflow lets them fix those gaps immediately.

Mode Check

If plan mode is active, exit it now using ExitPlanMode before starting this workflow. All voiceprint commands run in execute mode.

Inputs

• Target directory: The exact path shown after "The target writer skill directory is:" in the command output above. This directory must contain SKILL.md.

Reference Files

All reference file paths are resolved in the /refine command output above. Use those exact paths — do not search or glob.

Workflow Overview

Phase 1: Load & Check        (~30s)  → Read file, VERSION GATE, ask what to refine
Phase 2: Apply                (~1 min) → Surgical edits to SKILL.md
Phase 3: Validate             (~1 min) → Generate test content targeting the change
Phase 4: Cross-Check          (opt)   → Flag inconsistencies within the profile
Phase 5: Summary              (~30s)  → List changes made

---

Phase 1: Load & Check

Step 1: Read the target skill

Do NOT search, glob, or look up the writer skill by name — use the provided path directly.

Read from the provided directory path silently — do NOT display a summary:

• {TARGET_DIR}/SKILL.md - The writer skill

If SKILL.md is missing, tell the user:

I couldn't find a writer skill at that path. I need SKILL.md in the directory. Check the path and try again.

Then stop.

Safety net: The /refine command already verified the version before loading this skill. If you notice voice-profile.md exists in the directory and SKILL.md has no voiceprint-version frontmatter field, stop and tell the user to run /voiceprint update {TARGET_DIR} first.

Step 2: Ask immediately

Do NOT display a profile summary. The user already knows their profile — they're here because something specific needs fixing. Go straight to the question:

Use AskUserQuestion:

• Question: "What would you like to refine about your writer skill?"
• Options:
  • "Add forbidden patterns" (description: "New phrases or structures to avoid")
  • "Remove forbidden patterns" (description: "Something was flagged that I actually use")
  • "Adjust tone/formality" (description: "Change how formal, casual, direct, etc.")
  • "Add active patterns" (description: "Phrases or structures I want used more")
  • "Provide a writing example" (description: "Add a new exemplar to the voice profile")
  • "Update content templates" (description: "Change how specific content types are handled")
  • "Something else" (description: "I'll describe what I need")

Step 3: Get specifics

Based on their selection, ask a follow-up for details.

For "Add forbidden patterns":

Ask (free text, not AskUserQuestion):

What patterns have you noticed that don't sound like you? Give me examples — specific phrases, sentence structures, or general categories. If you've seen them in content generated with your skill, paste an example.

After they respond, read the AI tells catalog listed in Reference Files above to check if the pattern falls into an existing category. If it does, offer to add the full category:

Use AskUserQuestion:

• Question: "That falls under '{CATEGORY_NAME}' in the AI tells catalog. Want me to add the full category or just the specific phrases you mentioned?"
• Options:
  • "Full category" (description: "Block all {COUNT} phrases in this group")
  • "Just what I mentioned" (description: "Only block the specific phrases")

For "Remove forbidden patterns":

List the current items from the Forbidden Patterns section in SKILL.md and ask which ones to remove.

For "Adjust tone/formality":

Ask (free text):

How would you describe the adjustment? For example: "more casual", "less hedging", "more direct", "allow more humor". You can also paste an example of writing that has the tone you want.

For "Add active patterns":

Ask (free text):

What patterns or phrases do you want used more? Paste examples from your own writing if you have them.

For "Provide a writing example":

Ask (free text):

Paste a writing sample that represents your voice well. Tell me what context it's from (tweet, email, blog post, message, etc.) and I'll add it as an exemplar to your profile.

For "Update content templates":

Ask which content template (Social Media, Blog, Email, Documentation) and what to change.

For "Something else":

Ask them to describe what they need in free text.

Step 4: Confirm understanding

Summarize what you're going to change before making edits:

Here's what I'll do:

{numbered list of specific changes}

Sound right?

Use AskUserQuestion:

• Question: "Proceed with these changes?"
• Options:
  • "Yes, go ahead" (description: "Apply the changes")
  • "Let me adjust" (description: "I want to modify the plan")

If they want to adjust, loop back to gather more detail.

---

Phase 2: Apply Refinements

Make surgical edits to SKILL.md. The merged file contains all voice data in one place — no cross-file syncing needed.

Section Reference

The SKILL.md contains these sections that may need editing:

Section	Contains
Quick Reference	10-dimension summary table
Voice Exemplars	6 categorized writing samples
Voice Profile	Core Characteristics, Sentence Metrics, Punctuation, Vocabulary, Voice Detail
Voice Markers	Signature Moves, Natural Expressions, Structural Preferences, Rhythm
Platform Formats	Social, Blog, Email, Docs with synthesized exemplars
Sample Transformations	3 before/after pairs
Forbidden Patterns	Rejected Phrases, Rejected Structures, Additional Rejections
Internal Checks	Silent verification rules
Calibration Notes	Edge cases and context notes

Edit Rules

1. Preserve existing content. Add to sections, don't replace them (unless explicitly removing something).
2. Match the formatting. Follow the existing bullet/list style in each section.
3. Keep sections consistent. If you change the Quick Reference table, also update the corresponding Voice Profile subsection (and vice versa).
4. For new exemplars: Add to the Voice Exemplars section, maintaining the category labels.
5. For new forbidden patterns: Add to the appropriate Forbidden Patterns subsection (Rejected Phrases, Rejected Structures, or Additional Rejections).

Applying Category Expansions

When adding a forbidden pattern category from the AI tells catalog:

1. Read the AI tells catalog listed in Reference Files above
2. Find the matching category
3. Add items to the appropriate Forbidden Patterns subsection in SKILL.md

---

Phase 3: Validate

Step 1: Generate test content

Write a short paragraph (3-5 sentences) that specifically targets the change made. The goal is to test whether the skill correctly applies the refinement.

Examples:

• If patterns were forbidden: Write about a topic that would naturally tempt those patterns, and verify none appear
• If tone was adjusted: Write in the new tone setting
• If active patterns were added: Write content that uses those patterns
• If an exemplar was added: Write in the same register as the new exemplar

Step 2: Present and verify

Here's a test paragraph written with the updated skill. I specifically targeted the area we changed:

{test paragraph}

Does this look right?

Use AskUserQuestion:

• Question: "How does this look?"
• Options:
  • "Good" (description: "The change is working as expected")
  • "Needs more adjustment" (description: "I'll tell you what's still off")

If more adjustment is needed, loop back to Phase 1 Step 3 with the additional feedback.

---

Phase 4: Cross-Check (Optional)

After applying changes, offer to cross-check the updated skill for internal consistency.

Use AskUserQuestion:

• Question: "Want me to cross-check your updated skill for any internal inconsistencies?"
• Options:
  • "Yes, check it" (description: "Flag anything that looks contradictory")
  • "No, we're good" (description: "Skip to summary")

If yes:

1. Read the full SKILL.md
2. Check for contradictions (e.g., a forbidden pattern that also appears in active patterns/exemplars, tone settings that conflict with exemplars, Quick Reference values that don't match Voice Profile details)
3. Present findings and offer to fix any issues found

---

Phase 5: Summary

Step 1: List changes

Present a clear summary:

Changes applied to {PROFILE_NAME}-writer:

{numbered list of changes with before/after where relevant}

Step 2: Wrap up

Your writer skill has been updated. The changes will apply next time you (or any AI tool) uses the {PROFILE_NAME}-writer skill.

---

Error Handling

• Path doesn't exist: Tell the user the path wasn't found and ask them to check it.
• Missing SKILL.md: Explain the file is missing and suggest they may need to run /voiceprint generate first.
• Old two-file format: Caught by the /refine command's pre-flight check before this skill loads. If somehow reached here with an old format, stop and direct user to /voiceprint update first.
• Unrecognized structure: If the file exists but doesn't follow the expected template structure, warn the user and attempt best-effort edits, noting what couldn't be updated automatically.
• User wants multiple changes: Handle them sequentially in a single session — loop through Phase 1-3 for each change, then do a single Phase 5 summary at the end.

References

• AI tells catalog — see resolved path in Reference Files above