| name | iterative-refinement |
| description | Rapid iterative refinement skill. Runs 4–6 structured improvement cycles on any output — writing, code, strategy, design — without losing coherence, regressing previous improvements, or drifting from the original intent. Each cycle targets a specific refinement dimension, tracks deltas explicitly, and terminates when the output reaches a defined quality threshold. Prevents the common failure where "make it better" produces sidewise movement instead of genuine improvement. Use when user says: refine this, iterate, make it better, run refinement cycles, improve this over multiple passes, keep improving, cycle through this, refine until good, multiple passes, polish this, iterate until done, run the loop, keep going until it's great, another pass, refine again. Do NOT activate for: first-draft generation, simple one-shot edits, structural rewrites that require rethinking from scratch. First response: "Iterative Refinement active. Paste the output to refine and describe what 'done' looks like — quality bar, intended use, audience. I'll run targeted cycles and track deltas."
|
| license | Apache 2.0 |
Iterative Refinement Loops
"Make it better" produces one of two failure modes: circular iteration (the output
changes but doesn't improve, just moves sideways) or regression (fixing one dimension
breaks another).
The solution is structured refinement: each cycle has a specific target dimension,
an explicit delta from the previous version, and a quality gate. The model knows what
it's optimizing for, knows what it changed, and knows when to stop.
SLASH COMMANDS
| Command | Action |
|---|
/refine <output> | Start a refinement loop with auto-selected dimensions |
/cycle <dimension> | Run one targeted refinement cycle on a specific dimension |
/delta | Show exactly what changed in the last cycle and why |
/score | Score the current output against the quality target |
/target <description> | Define or update the quality target |
/dimensions | Show the active refinement queue and completed cycles |
/undo | Revert to the previous cycle's output |
/lock <element> | Lock a specific element — do not change this in future cycles |
/focus <dimension> | Prioritize one dimension for the next N cycles |
/auto <n> | Run n cycles automatically, picking the highest-value dimension each time |
/history | Show all cycle deltas in sequence — full refinement log |
/done | Declare the output final and output the refinement summary |
HIGH-LEVEL WORKFLOW
User provides output and quality target
│
├─ Phase 1: Baseline Assessment
│ Score the input across all refinement dimensions
│
├─ Phase 2: Dimension Prioritization
│ Rank dimensions by gap from target and impact
│
├─ Phase 3: Targeted Cycles
│ Apply one cycle per dimension; track every delta
│
├─ Phase 4: Regression Check
│ Confirm each cycle didn't regress a previously-improved dimension
│
├─ Phase 5: Quality Gate
│ Score after each cycle; stop when target is met
│
└─ Phase 6: Refinement Summary
Report what changed, what improved, and what was locked
PHASE 1 — REFINEMENT DIMENSIONS
Every output type has a set of refinement dimensions. Score each 1–5 before starting.
Writing dimensions
| Dimension | Score 1 | Score 5 |
|---|
| Clarity | Reader must re-read to understand | First read is enough; meaning is immediate |
| Concision | Words don't earn their place | Every word is necessary |
| Impact | Opening and close are weak | First and last sentences are strongest |
| Specificity | Vague; could apply to anything | Concrete, specific, tied to this context |
| Flow | Sentence-to-sentence movement is rough | Transitions are invisible; reading is effortless |
| Tone | Doesn't match the target audience | Exactly right for the audience and purpose |
| Structure | Organization is unclear or wrong | Structure serves the reader's needs |
Code dimensions
| Dimension | Score 1 | Score 5 |
|---|
| Correctness | Has bugs | Handles all cases correctly |
| Readability | Hard to follow | Intent is obvious on first read |
| Robustness | Crashes on edge cases | Handles unexpected inputs gracefully |
| Performance | Obvious inefficiencies | Appropriate for the use case |
| Testability | Hard to test in isolation | Clean interfaces; easy to mock |
| Security | Obvious vulnerabilities | Input validated; no injection points |
Strategy / plan dimensions
| Dimension | Score 1 | Score 5 |
|---|
| Clarity of goal | Ambiguous success criteria | Concrete, measurable outcomes |
| Completeness | Missing key steps | Every necessary step is present |
| Risk coverage | Major risks unaddressed | Key risks named with mitigations |
| Feasibility | Resources or timeline unrealistic | Grounded in real constraints |
| Prioritization | All steps treated equally | Critical path is clear |
PHASE 2 — CYCLE EXECUTION
Cycle structure
Each refinement cycle:
- Identify the target dimension (highest gap × highest impact)
- Describe the specific improvement before making it
- Apply the improvement
- Write the delta note — what changed and why
- Run regression check — did this break anything previously improved?
- Score the dimension — did it improve?
Cycle output format
CYCLE [N]: [dimension]
Target: [what this cycle is improving]
Gap before: [score]/5 → Target: [target score]/5
Changes made:
· [specific change 1] — [why]
· [specific change 2] — [why]
Delta:
BEFORE: "[exact quote of changed section]"
AFTER: "[exact quote of new version]"
Regression check:
[dimension previously improved]: [still holds / regressed — describe]
[Dimension] score: [before] → [after]
Cycle targeting rules
- Never optimize two dimensions simultaneously in one cycle. Clarity + Tone in one cycle produces mediocre improvement in both.
- Impact and opening/close first. For writing, the opening and closing sentences deliver the most return per cycle.
- Correctness before readability. For code, never polish what might be wrong.
- Lock wins. Once a dimension scores 5, mark it locked unless the user explicitly unlocks it.
- Diminishing returns threshold. If two consecutive cycles on the same dimension produce less than 0.5 score improvement, move to the next dimension.
PHASE 3 — QUALITY GATE
After each cycle, calculate the overall quality score:
QUALITY GATE — CYCLE [N]
Scores:
[Dimension 1]: [N]/5 [LOCKED / ACTIVE / REGRESSED]
[Dimension 2]: [N]/5 [LOCKED / ACTIVE / REGRESSED]
...
Overall: [avg]/5
Target: [user-defined threshold]/5
Status: CONTINUE | DONE | REGRESSION DETECTED
Stop conditions
- Done: Overall score ≥ target threshold (default: 4.2/5)
- Done: All active dimensions locked (all scored ≥ 4.5)
- Stop and review: Any dimension regressed after being locked
- Stop and reframe: 3+ consecutive cycles with < 0.3 total improvement
Regression handling
If a cycle causes a regression:
- Immediately revert to previous cycle's output
- Re-run the cycle with a tighter constraint: "Improve [dimension] without touching [locked dimensions]"
- If regression persists after 2 attempts, surface the tension explicitly: "Improving [A] conflicts with [B] because [reason]. Which takes priority?"
PHASE 4 — DIMENSION-SPECIFIC TECHNIQUES
Clarity cycles
- Replace abstract nouns with concrete verbs: "the implementation" → "the function that..."
- Split sentences that contain more than one idea
- Move the main clause first; subordinate clauses after
- Replace "this," "it," "they" with the actual noun when the referent is more than 2 sentences back
Concision cycles
- Remove every word that does not change meaning if deleted
- Remove softeners: "somewhat," "quite," "rather," "a bit"
- Remove throat-clearing openers: "It is important to note that," "As we can see,"
- Replace prepositional phrases with a single word: "in the event that" → "if"
- Merge two sentences that make the same point
Impact cycles
- Move the most important sentence first in every paragraph
- End the piece with the highest-stakes sentence, not a summary
- Find the most generic sentence and make it the most specific
- Find the most passive sentence and make it active
Specificity cycles
- Replace every adjective that could apply to anything with one that couldn't
- Add a number where an amount is described: "many users" → "72% of users"
- Name the specific mechanism: "it improves performance" → "it reduces round trips by eliminating..."
- Ground the abstract: "a better experience" → "opens in under 200ms"
PHASE 5 — REFINEMENT SUMMARY
When the loop completes:
REFINEMENT COMPLETE
Cycles run: [N]
Total iterations: [N]
Quality progression:
Cycle 0 (baseline): [N]/5
Cycle 1: [N]/5 (+[delta]) — [dimension improved]
Cycle 2: [N]/5 (+[delta]) — [dimension improved]
...
Final: [N]/5
Dimensions locked: [list with final scores]
Dimensions not reached: [list with current scores — why not improved]
Most impactful change: [which cycle, which dimension, what changed]
What held back further improvement: [honest assessment of ceiling]
