/design-iteration

A one-fix-at-a-time, approval-gated design fix recovery skill. Given a checklist of
fixes (a handover doc, CHECKLIST.md, or inline list), applies each fix individually,
presents a diff, and waits for an explicit APPROVE / REJECT / NO CHANGES decision
before committing or moving on. Never batches. Never self-merges.

When to invoke

• /design-iteration — start or resume a fix pass on the current branch
• "go through the checklist one by one"
• "fix these one at a time, show me each before committing"
• "bucket recovery" / "design fix pass" with a list of items

Invocation

/design-iteration [path/to/checklist-or-handover.md]

If no path is given, look for the active handover in:

1. An explicit path in the conversation context
2. founder/reports/design-review-<today>/HANDOVER*.md
3. Ask the user to specify

Operating contract

The one rule that governs everything

One fix at a time. After each fix, STOP and present it for a decision.

• APPROVE → commit that fix (one commit, one fix), push, move to next
• REJECT → git restore touched files, move to next
• NO CHANGES → fix was already present or unnecessary; touch nothing, note it, move to next

Never batch. Never "do them all and summarize." The checkpoint exists because these fixes
touch files that may have been rewritten by a migration, and a wrong port can silently
regress a shipped fix.

Loop for each fix

1. Verify it is still missing. Re-run the check from the handover (grep, line read).
   If already present → NO CHANGES; report and skip.
2. git show <ref-sha> (if provided) to see original intent. Do not blind-apply.
3. Port the intent onto the current file(s) by hand. Do NOT paste stale patches wholesale
   when target files were rewritten since the source SHA.
4. Read the edited file(s) back. Confirm:
   • No duplicated or merged lines
   • No new hardcoded hex (use design tokens; fallback to var(--token, fallback) only)
   • No banned patterns (gradient text, dead enum reads, client-side branch derivation if
     the project has an emitted-branch architecture)
5. STOP. Present to the user:
   • Fix ID + description
   • Files changed
   • git diff output (or key hunks if very large)
   • One-line rationale: why this matches the intent without introducing regressions
   • Ask explicitly: APPROVE / REJECT / NO CHANGES?
6. On decision:
   • APPROVE → git add <only those files> → commit with message
     fix(design): <fix-id> — <one-line summary> → git push origin <branch> →
     report SHA → next fix
   • REJECT → git restore <those files> → next fix
   • NO CHANGES → touch nothing → next fix
7. Never proceed to the next fix before a decision on the current one.

After all fixes

Open one PR from the current branch to the target base branch. PR body must list:

• Each fix + its outcome (approved / rejected / no-change)
• Any Bucket-2 / "do not re-apply" items that were deliberately skipped, and why

Then stop — the human merges.

Branch + scope rules

• Always work on the branch specified in the handover or by the user. Never create a
  new branch mid-pass without asking.
• Respect CI branch-scope (e.g. design/ branches may only touch docs/ + *.md).
  When a fix crosses scope, surface the conflict and ask: split across branches, or add
  [skip-scope-check] to the commit message per the user's call.
• Never push to main directly.

Presenting the diff

For each fix, show:

--- Fix N: <title> ---
Files: <list>
---
<git diff or key hunks>
---
Why this is safe: <one sentence>

APPROVE / REJECT / NO CHANGES?

If the diff is very large (e.g. 48-file sweep), show the full file list + one
representative sample diff, then ask for approval before running the bulk operation.

Token discipline

• Verify before editing (one read + grep). Edit. Verify after (read-back). That's the
  full cycle — do not re-read files already confirmed.
• For bulk deletions (e.g. removing a dev tag from N files), use a single shell command
  rather than N individual edits, then confirm count = 0 with a follow-up grep.

Reference implementation

This skill was extracted from the 2026-07-20 Bucket-1 recovery session
(design/ygg2-bucket1-recovery → dev/yggdrasil-ii-staging, PR #1241).
Handover doc: founder/reports/design-review-2026-07-20/HANDOVER-bucket1-recovery.md.
INSIGHTS source-of-truth: founder/reports/design-review-2026-07-20/INSIGHTS.md.