← All runbooks
pbakaus / polish

Polish

Perform a meticulous final quality pass on a frontend interface to catch all the small details that separate good work from great work. This runbook guides an agent through systematic UI polish: visual alignment, typography, color/contrast, interaction states, micro-interactions,

agent claude-codemodel claude-sonnet-4-6snapshot python312-uveval programmatic10 stepsv1.0.0

Deploy Polish to your jetty.io

One-click installs this runbook into a collection on your Jetty account. You can run it from the Spot dashboard, schedule it, or pipe inputs in via the API.

Deploy on jetty.io →View source
The shape of the run

10 steps · start to finish.

  1. 1
    Step 1

    Environment Setup

    ▶

    Verify prerequisites before touching any code.

    echo "=== POLISH PRE-FLIGHT ==="

# Verify functional completeness was declared
if [ -z "$TARGET_FEATURE" ]; then
  echo "ERROR: TARGET_FEATURE env var required. Set it to the feature/component path."
  exit 1
fi

# Check for design context files
PRODUCT_MD=$(find . -maxdepth 3 -name "PRODUCT.md" | head -1)
DESIGN_MD=$(find . -maxdepth 3 -name "DESIGN.md" | head -1)

[ -n "$PRODUCT_MD" ] && echo "PASS: PRODUCT.md found at $PRODUCT_MD" || echo "WARN: PRODUCT.md not found — polish will use visible codebase conventions"
[ -n "$DESIGN_MD"  ] && echo "PASS: DESIGN.md found at $DESIGN_MD"   || echo "WARN: DESIGN.md not found — will infer tokens from existing code"

mkdir -p /app/results
echo "PASS: Output directory ready"

    CRITICAL: Do not proceed if the feature is not functionally complete. Polish before functionality is wasteful and often introduces regressions.

  2. 2
    Step 2

    Design System Discovery

    ▶

    Before any edits, map the existing design system. Polish without system alignment is decoration on top of drift.

  3. 3
    Step 3

    Pre-Polish Assessment

    ▶

    Understand the current state before making changes.

  4. 4
    Step 4

    Polish Systematically (max 3 rounds per dimension)

    ▶

    Work through all dimensions methodically. For each dimension: inspect → find issues → fix → verify. Never move on leaving known issues unresolved unless explicitly deferred.

  5. 5
    Step 5

    Complete the Polish Checklist

    ▶

    Mark every item in `/app/results/checklist.md` as `pass`, `fail`, or `n/a`:

  6. 6
    Step 6

    Iterate on Errors (max 3 rounds)

    ▶

    If any checklist item is `fail`:

  7. 7
    Step 7

    Final Verification

    ▶

    Before marking polish complete:

  8. 8
    Step 8

    Clean Up

    ▶

    After polishing, improve code hygiene:

  9. 9
    Step 9

    Write Results and Summary

    ▶

    Write `/app/results/summary.md`:

  10. 10
    Step 10

    Final Checklist (MANDATORY — do not skip)

    ▶

    echo "=== FINAL OUTPUT VERIFICATION ===" RESULTS_DIR="/app/results" for f in \ "$RESULTS_DIR/polish_report.md" \