視覺修復
將一個可見的 UI 問題，轉化為一個局部、經批准、並經驗證的程式碼變更。
支援的證據
接受以下任何有用的組合：
- 目前 UI 的螢幕截圖
- 螢幕截圖中經過註解或描述過的區域
- 目前與目標螢幕截圖，並標明各自的作用
- 路由、視窗大小、元件名稱、可見字串、選擇器或測試 ID
- 使用日常語言描述的症狀，例如「這張卡片被裁剪了」或「這些控制項沒有對齊」
只要求提供那些會阻礙可靠定位的證據。如果一個路由加上一個獨特的可見字串就足夠了，可能不需要螢幕截圖。如果螢幕截圖中包含重複的元件，仍然可能需要路由、標籤或狀態。
一次只處理一個視覺問題。將不相關的症狀分開處理。
工作流程
1. 建立目標
用具體的詞彙重新陳述有邊界的結果：
- 現在看起來哪裡不對勁
- 使用者期望看到什麼
- 如果知道，相關的路由、元件、狀態和視窗大小是什麼
- 哪個可見的錨點可以識別目標
如果要求的結果是主觀的，或者可能影響不同的元素，提出一個最小的問題來區分它們。
2. 建立唯讀基準線
在編輯之前：
- 尋找儲存庫的說明文件和事實來源。
- 檢查工作目錄狀態，並保留使用者現有的變更。
- 識別框架、路由條目、元件樹、樣式系統以及可用的執行或測試指令。
- 在環境允許的情況下，重現目標路由和視窗大小。
- 在變更前，擷取或記錄當前狀態。
當已維護的原始檔存在時，不要編輯產生的輸出。不要清理或覆蓋工作目錄中不相關的變更。
簡要報告基準線：
Context
- Route/state: /catalog, filters open
- Viewport: 390 x 844
- Source of truth: src/routes/catalog.tsx + src/styles/catalog.css
- Existing user changes: none
- Reproduction: available
3. 定位渲染的原始碼
將證據從渲染的元素追溯到維護中的程式碼。使用路由、可存取名稱、可見文字、DOM 選擇器、元件名稱、測試 ID、類別、樣式令牌或螢幕截圖的幾何位置。當涉及多個檔案或樣式層時，請閱讀 references/locating.md。
識別一個主要的原始碼位置，以及最多兩個必要的相關位置。檔案和行號的證據必須來自當前的 worktree。
Located
- Primary: src/components/ProductGrid.tsx:42, ProductGrid
- Related: src/styles/products.css:18
- Evidence: `.grid` controls the repeated horizontal spacing visible between the cards
- Confidence: high
如果兩個相似的元件仍然難以區分，解釋區分它們的證據，並停下來尋求釐清。
4. 從證據進行診斷
將可見的症狀與實際的程式碼連結起來。優先選擇一個有支援的原因。只有在證據仍然模糊時，才提供兩到三個假設。
對於每個假設，請包含：
- 相關的屬性、選擇器、令牌或元件
- 支援它的程式碼或渲染證據
- 預期的修復方向
- 一個可以推翻它的觀察
不要從螢幕截圖中憑空發明 CSS 值。先檢查當前值和周圍的設計系統。
5. 提出確切的變更計劃
在編輯之前展示建議的修補程式：
Change plan
- Files: src/components/ProductGrid.tsx:42
- Current: gap: 8px
- Proposed: use the existing space-4 token (16px)
- Scope: ProductGrid on /catalog and /search
- Preserving: card padding, mobile column count, unrelated routes
- Verification: targeted test, lint, screenshots at 390 x 844 and 1280 x 800
- Risk: medium; the component is shared by two routes
等待此計劃的明確批准。選擇診斷結果並不代表批准程式碼變更。如果計劃後來擴展到另一個檔案、依賴項、鎖定檔、產生的成品或路由，請提出修改後的計劃並再次獲得批准。
6. 套用已批准的修補程式
進行能實現該計劃的最小變更。將編輯保持在已批准的檔案和範圍內。然後立即檢查 diff：
- 當專案使用 Git 時，執行
git diff --check。 - 確認 diff 僅包含計劃中的變更。
- 保留預先存在的變更，避免不相關的格式化改動。
- 除非另行授權，否則不要提交、推送、安裝依賴項或修改外部服務。
7. 驗證結果
在聲稱成功之前，請閱讀 references/verification.md。
使用最強的可用證據：
- 執行與變更程式碼相關的目標測試、格式檢查、型別檢查或建置。
- 渲染與基準線相同的路由、狀態和視窗大小。
- 視覺上比較前後差異。
- 當變更的原始碼有更廣的影響範圍時，檢查一個附近的視窗大小或共享路由。
確切報告一個驗證狀態：
Verified visually當存在可比較的視覺證據時Verified statically當程式碼檢查通過，但 UI 無法渲染時Unable to verify visually當環境缺少路由、瀏覽器、測試用資料或啟動路徑時Verification failed並附上失敗的指令或觀察到的回歸
如果驗證失敗，返回診斷步驟。不要在第一次修復的基礎上疊加未經批准的第二個修復。
完成報告
保持交接簡潔且基於證據：
Fixed
- Target: catalog card spacing at mobile width
- Source: src/components/ProductGrid.tsx:42
- Change: gap now uses space-4
- Verification: Verified visually at 390 x 844; unit test and lint passed
- Wider checks: /search at 390 x 844 and /catalog at 1280 x 800
提及任何殘留的視覺不確定性。永遠不要將程式碼 diff 描述為視覺證據。