refining-a-spell

name	refining-a-spell
description	Use when an existing spell needs improvement based on usage. Captures what changed, re-runs the tester (mandatory), bumps the version, and saves.
kind	workflow
audience	anyone
ai-tools	any
complexity	guided
time	5-15 min
version	1.0.0
source	bundled

Refining a Spell

What this does

Updates an existing spell in the user's library. Walks through the diff, re-runs the tester (this is non-skippable), bumps the version field, and saves.

When to use

• User invoked /refine-spell <name>
• User says "this skill needs to also handle X"
• A spell's tester verdict changes (e.g., a new edge case found in production use)

What you bring (Inputs)

• The name of the spell to refine
• What needs to change (and ideally why — what failed in real use)

What you get (Output)

The updated SKILL.md, validated, re-tested, and saved with bumped version.

How it works (Steps)

This is a workflow.

Stages

Stage 1: Load the current version

Find the spell in $WIZARD_HOME (preferred) or bundled spells/. If it's bundled and not yet overridden, copy it to $WIZARD_HOME/personal/<name>/ first — never modify the bundled file.

Stage 2: Capture the diff

Ask: "What needs to change?" and "What real situation showed you this was needed?"

The "what real situation" question is required. A refinement without a real-world trigger is speculative — push back: "Want to wait until you hit a real case?"

Stage 3: Apply the change

Edit the SKILL.md. Common changes:

• New step → add to How it works (Steps) and to Quality bar
• New variation → add to Variations
• Better example → swap the Example block
• New rationalization (discipline) → add to Excuses and counters
• New input → update What you bring (Inputs) and add a step to capture it

Stage 4: Re-run the tester (NON-SKIPPABLE)

Any change requires re-test. The kind of test depends on the kind:

Kind	Test
content, workflow, subagent	Standard mode tester on 2-3 scenarios
discipline	pressure-testing-a-spell with at least one scenario that exercises the change

Forbidden excuses (re-test is non-skippable)

If you think...	Reality
"It's a tiny wording change"	Tiny changes shift behavior. Re-test.
"I already manually verified"	Re-test.
"The previous version passed"	The previous version is no longer the current version. Re-test.
"I'll re-test next time"	Re-test now.

All forbidden excuses get the same response: Re-test. No exceptions.

Before saving any refined spell, the tester must have returned PASS for the new version. If you are about to save without a fresh PASS, STOP. Re-test.

Stage 5: Bump the version

Apply semver:

• Wording-only change → PATCH (1.0.0 → 1.0.1)
• New optional capability → MINOR (1.0.0 → 1.1.0)
• Removed step or changed required input → MAJOR (1.0.0 → 2.0.0)

If the current version is 0.x.y and the user has used this spell 3+ times successfully, prompt: "Bump to 1.0.0?"

Stage 6: Save and confirm

Write to $WIZARD_HOME/<category>/<name>/SKILL.md. Show the user the diff summary and the new version.

Checkpoints

• After Stage 1: file loaded; if from bundled, copy to personal first
• After Stage 2: diff captured; real situation named
• After Stage 3: edits applied
• After Stage 4: tester returned PASS for the new version
• After Stage 5: version bumped per semver rules
• After Stage 6: file saved; diff summary shown

Loop-back conditions

Return to Stage 3 when:

• Tester returns NEEDS-REFINEMENT — apply the suggested fix
• Tester returns SCOPE-CHANGED — pivot via intuitive-interviewing

Quality bar

The refinement is good enough when:

• The change is documented in the user's words (so future-them remembers why)
• A fresh PASS verdict exists for the new version (not assumed from old version)
• Version bump matches the change type (no MAJOR for typo fixes; no PATCH for new steps)

Variations

• Bug-fix refinement (something was wrong): name the bug in a comment in the SKILL.md
• Generalization refinement (works for more cases now): add the new variations explicitly
• Sharpening refinement (was too vague): tighten Quality bar criteria

Example

User: "My writing-a-status-update skill keeps including too much detail when I'm in a hurry. Make it shorter."

• Stage 1: Load ~/.wizard/work/writing-a-status-update/SKILL.md.
• Stage 2: Real situation: "Today's update was 7 bullets when manager wanted 3."
• Stage 3: Add "rush mode" variation: "Trim to 3 bullets max; only wins + asks."
• Stage 4: Tester runs 2 scenarios in rush mode. PASS.
• Stage 5: MINOR bump (new optional variation). 1.0.0 → 1.1.0.
• Stage 6: Saved. Showed diff summary.