gtarpenning/ui-critic

ui-critic 是做什麼的？

以特定人物的方式來評斷螢幕，並以其過往決策作為證據。單純的 Claude 在預測此人真實設計選擇時的正確率為 44-50%，而此程序的正確率約為 60%，且這些決策皆無相同主題的證據（結果）。這是一個強而有力的第二意見，而非預言神諭。

詢問	動作
哪個設計比較好？	比較
這個螢幕或流程應該改變什麼？	評論
教導它、調整它，它判斷錯了	調整
此人在設計之間做出了選擇	記錄

腳本位於此檔案旁。使用 python3 執行；prepare.py 和 annotate.py 需要 Pillow（pip install pillow）。

務必遵守

• 先了解任務。 如果你不知道該螢幕的用途和目標對象，請先詢問一次。否則，請陳述你的假設。
• 過往決策勝過這些規則和一般設計觀點。 較新的決策優先於較舊的。
• 不要僅從「最佳實踐」推論。 針對此人的決策，謹慎的一般性推論正確率低於隨機水準，因為它傾向支持更多資訊、標籤和計數。應從他們實際選擇的內容來論證。
• 不要將偏好推廣到證據範圍之外。 列表中的「較少」不代表到處都「較少」。他們曾選擇地圖圖片而非較短的文字標籤，並在比較步驟中增加了照片和筆記，因為這些能讓人更快地辨識事物。
• 先講結論。 先給 verdict，再給細節。你的報告應遵循你正在評判的相同漸進式揭露原則。

比較

1. 準備。 python3 scripts/prepare.py --out <tmp> <images...>，然後使用準備好的副本。對於流程，每個設計都是一個有序的螢幕列表。

2. 取得證據。 閱讀 taste/taste.md。執行 python3 scripts/cases.py --context "<此螢幕的用途>" --k 4。

3. 盲審兩次。 產生兩個子代理，彼此沒有共享上下文，使用 references/judge.md 中的提示。第一個代理看到的設計順序是 X, Y，標記為 A, B；第二個代理看到的順序是 Y, X。使用 Sonnet：Opus 成本高出數倍但分數並未更好。提供每個案例的圖片路徑，並指示其閱讀每張圖片。不要告訴它們你偏好哪個設計、誰設計的、或哪個比較新。

   多於兩個設計時：先兩兩比較最強的兩個，然後將勝出者與下一個進行比較。不要一次要求進行排名。

4. 決定。

   • 兩者選擇相同的設計：這就是 verdict。
   • 它們意見分歧：請說難分軒輊，用一行文字說明雙方的最佳論點，並指出需要由該人物做決定的關鍵問題。不要自行打破平手。

5. 超越選項思考。 如果兩個設計都有相同的缺點，或者落敗者有一個值得保留的想法，請用一兩句話提出合併後的版本。過去的勝者經常正是來自於此。

6. 報告。

   **B.** <一句話：決定性的差異。>
   信心：兩者順序一致（非絕對保證：不同的模型或證據仍可能翻轉）/ 難分軒輊
   - 原因：<決定性的差異，並引用它們所呼應的過往決策>
   - 值得從 A 保留的部分：<如果有的話>
   - 比兩者都好的方案：<如果有的話>
   

   僅在被要求時，才添加一個帶有方框覆蓋圖的勝出者剩餘問題圖層。

評論

1. 準備螢幕如上所述，並記錄每個螢幕的像素尺寸。座標僅在準備好的副本上有效。
2. 取得證據。 閱讀 taste/taste.md 並執行 cases.py --k 4，然後在查看新螢幕之前，閱讀每個案例的兩張圖片。以下分數假設你已看過它們。
3. 審查，依此順序：
   • 某人來到此螢幕是為了做哪一件事？他們必須一眼就能掌握什麼？
   • 逐個元素檢查：這個元素值得佔據此處，還是可以移到下一層？是否有任何資訊被重複說明？在該螢幕或應用程式其他位置，同一種事物是否以兩種不同方式繪製？次要動作是否與主要動作競爭？圖片是否比文字更容易被理解？
   • 對於流程，還要問：開啟的內容看起來像你點擊的東西嗎？是否有任何步驟是死胡同？
4. 精簡。 最多 3 個發現，最重要的先列出。刪除無障礙功能的樣板內容、一般性的潤飾，以及任何你無法具體指出的項目。如果設計良好，請直接說明並回報無發現。用次要問題填充內容視為失敗。在完成之前，檢查每個發現是否與過往決策衝突。
5. 繪製。 在準備好的螢幕旁邊寫入 findings.json，方框使用緊貼的絕對像素座標 [x1, y1, x2, y2]（基於準備好的副本）：

   {"verdict": "一句話。",
    "screens": [{"path": "/abs/prepared.png", "label": "首頁"}],
    "findings": [{"screen": 0, "box": [40, 120, 300, 180], "severity": "high", "title": "...", "why": "...", "fix": "..."}]}
   

   執行 python3 scripts/annotate.py findings.json --out <tmp>。閱讀每個 .annotated.png 檔案，檢查每個方框是否確實對應到其發現所描述的內容。如果位置不對，修正數字並重新執行。如果發現是關於整個卡片，那麼在卡片周圍畫一個方框是可以接受的。
6. 報告 verdict、發現，以及 report.html 和註釋圖片的路徑。

記錄決策

當此人在設計之間做出選擇或在觀看螢幕時陳述偏好時，請提供記錄選項：python3 scripts/record.py --context "..." --winner a.png --loser b.png --reason "他們的原話" --topic <short-slug>。使用他們的原話作為理由。這是技能改進的方式，一句「為什麼」比好幾個未經解釋的選擇更有價值。

調整

啟動 python3 scripts/tune.py，在背景執行，並提供該 URL 給使用者。它有四個分頁：

• 挑選：使用方向鍵在設計之間選擇。大約需要 5 分鐘。
• 失誤：顯示判斷器與使用者意見不一致的地方及其論點。使用者可以維持自己的判斷或承認判斷器是對的。
• 規則：編輯 taste/taste.md。
• 分數：重新評分，包括使用者自身選擇的一致性。

在進行挑選或編輯後，執行 python3 scripts/distill.py 以根據所有決策重建 taste/taste.md。關於數據以及與他人品味搭配使用的資訊，請參閱 references/tuning.md。