| name | refinement-loop |
| description | Iterative refinement through multiple passes. Use when the user asks to 'meditate on', 'distill', 'refine', or 'iterate on' something, or proactively when a problem benefits from multiple passes rather than a single attempt. |
Refinement Loop
STARTER_CHARACTER = 🔄
Iterative refinement through file artifacts. Each pass removes one layer of noise, revealing the next.
Setup
Ensure playground/ exists and is in .gitignore. All iteration files go there.
Process
1. Clarify Goal (if the user hasn't defined it for you already earlier in the conversation)
Ask the user:
- What are you refining and what is the goal of refinement?
- Derive a short tag that we'll use as filename for iterating:
{goal}-{subject} (e.g., gist-nullables, simplify-api, distill-auth-docs)
2. Capture Starting Point
Write original to: playground/{goal}-{subject}-0.md
3. Iterate
Loop:
- Read back the current file (forces fresh perspective)
- Reflect critically: What's missing? What's weak? What could be clearer?
- If improvements found: Write improved version to
playground/{goal}-{subject}-{N+1}.md, then loop again
Before Stopping - Exhaustive Check
When you think you're done, you're probably not. Run through this:
- List everything that could still be improved - even small things (formatting, word choice, structure, clarity)
- Consider what we haven't considered - what angles did we miss? What would someone else notice?
- Try improving in a new direction - not just polishing what's there, but questioning assumptions
- Read as if seeing it for the first time - does it immediately make sense? Is anything unclear?
Only stop when you've gone through this checklist extensively multiple times and genuinely found nothing. There is no "good enough" - someone will use this later and shouldn't waste time on mediocre results.
4. Present Final
Show the user the final version with a brief summary of the refinement journey and number of iterations you used.
If deeper issues or questions surfaced, present them to the user as well.
Principles
- Read back forces fresh eyes: Reading from file breaks the "I just wrote this" blindness
- No "good enough": Every detail matters. Formatting, word choice, structure - all of it
- Consider the unconsidered: What angles haven't we explored? What would someone else see? Is there something that the user hasn't even considered, too? (you can surface it as questions at the end)
- Files force iterative improvement: Writing to files prevents "pretend" iteration in conversation. Real iteration gets to much better results.
- Earn the stop: Run the exhaustive check. If you find nothing, you've earned stopping.
