Iterative Refinement

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 | Start a refinement loop with auto-selected dimensions | | /cycle | 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 | Define or update the quality target | | /dimensions | Show the active refinement queue and completed cycles | | /undo | Revert to the previous cycle's output | | /lock | Lock a specific element — do not change this in future cycles | | /focus | Prioritize one dimension for the next N cycles | | /auto | 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:

1. Identify the target dimension (highest gap × highest impact)
2. Describe the specific improvement before making it
3. Apply the improvement
4. Write the delta note — what changed and why
5. Run regression check — did this break anything previously improved?
6. 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

1. Never optimize two dimensions simultaneously in one cycle. Clarity + Tone in one cycle produces mediocre improvement in both.
2. Impact and opening/close first. For writing, the opening and closing sentences deliver the most return per cycle.
3. Correctness before readability. For code, never polish what might be wrong.
4. Lock wins. Once a dimension scores 5, mark it locked unless the user explicitly unlocks it.
5. 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:

1. Immediately revert to previous cycle's output
2. Re-run the cycle with a tighter constraint: "Improve [dimension] without touching [locked dimensions]"
3. 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]

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Sandeeprdy1729
• Source: Sandeeprdy1729/claude-design-skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.