Razsk/VideoStudio

詢問 Matt

你不記得每個技能，所以儘管問。

在說明某個技能的功能或建議跳過某個步驟之前，請先閱讀該技能的 SKILL.md：這裡的摘要僅供參考。

「流程 (flow)」 是一條貫穿各個技能的路徑。大多數路徑會沿著一個 「主要流程 (main flow)」 運行，並有兩個 「銜接流程 (on-ramps)」 匯入其中。其餘的技能則為獨立技能，或是作為底層的詞彙層。

主要流程：從構想到發佈

這是大部分工作會經歷的路線。你有一個想法，並希望將它建置出來。

1. /grill-with-docs 透過面談來打磨你的想法。只要你在工作目錄 (working directory) 中工作，就從這裡開始：它是有狀態的，會將學到的內容保留在 GLOSSARY.md 和 ADR 中。（沒有工作目錄？請改用 /grill-me，詳見獨立技能區塊。兩者都執行相同的 /grilling 原語；grill-with-docs 是那一個會留下書面記錄的技能，因此只要儲存庫存在，它就是兩者中較好的選擇。）

2. 分支：你能在對話中解決所有問題嗎？ 如果一個問題需要一個可運行的答案（狀態、商業邏輯、你必須看到的 UI），則繞道通過原型，並由 /handoff 在兩個方向進行銜接（原型存在於自己的目錄中，而這正是 /handoff 的用途；請參閱階段邊界）：

   • /handoff 傳出，然後針對該檔案開啟一個新的會話，
   • /prototype 用一次性程式碼來回答問題，
   • /handoff 將你學到的東西傳回，並從原始的想法討論串中引用它。

3. 分支：這是一個需要多個會話的建置工作嗎？

   • 是 → /to-spec （將討論串轉換為規格書），然後 /to-tickets 將其拆分為「導引彈 (tracer-bullet)」任務，每個任務宣告其阻塞邊界 (blocking edges)。然後以兩種方式之一處理任務：
     • /implement 每個任務，並在每個任務之間 /clear 上下文。在本地追蹤器上，這表示在 .scratch/<feature>/issues/ 下每個任務一個檔案，手動以阻塞者優先的方式處理；在真實的追蹤器上，邊界會成為原生的阻塞連結，因此任何阻塞者已完成的任務都可以被選取處理。每個任務都是自包含的，所以前一個任務的上下文可以丟棄。
     • /implement-spec 一次處理整個規格書。它將任務讀取為一個任務圖 (task graph)，跨準備好的前沿 (frontier) 並行運行實作子代理，並將所有內容整合到一個整合分支 (integration branch) 上。當你寧可編排建置工作，也不想自己驅動每個任務時，可以使用它。
   • 否 → /implement 就在這裡，在同一個上下文視窗中進行。

   無論哪種方式，程式碼都是通過驅動 /tdd（一次一個紅-綠切片）來建置，並以 /code-review 結束，這是一個針對差異進行的雙軸（標準 + 規格）審查。/implement 每個任務都執行這兩項；/implement-spec 的實作者各自驅動 /tdd，然後在整合分支上執行一次 /code-review。當你只想在沒有完整規格書的情況下，以測試優先的方式建置一個具體行為時，可以單獨使用 /tdd；當你只想針對一個固定點審查某個分支或 PR 時，可以單獨使用 /code-review。

   當工作以 Pull Request 形式提交時，/pr 會塑造 PR 主體的內容：展示變更的最小視覺呈現、證明其運作的前後對比證據，以及一個單向或雙向的決策門。它是由模型驅動的，因此代理程式在撰寫 PR 時會自動使用它。

4. /retro 閉合循環。在建置完成後，特別是當過程不順利時，它會回顧該會話，並建議對代理程式的環境 (environment) 進行變更，而不是對程式碼：導航指標、自動化檢查、/code-review 強制執行的編碼標準、引導檔案、工具鏈。機械性的錯誤變成確定性檢查；判斷性問題變成編碼標準。下一次建置將從一個更好的環境開始。

上下文衛生

將步驟 1 到 3 保持在一個不中斷的上下文視窗中（在 /to-tickets 之前不要壓縮或清除），這樣打磨、規格書和任務都能建立在相同的思考基礎上。然後，每個 /implement 從任務開始，以全新的狀態啟動。在清除會話之前，在它所回顧的會話中執行 /retro；清除之後，則將其指向該會話的日誌。

對此的限制是 智慧區 (smart zone)：模型仍能清晰推理的視窗（在最先進的模型上約為 150k 個 token）。如果在 /to-tickets 之前會話接近該限制，請不要在效能衰減的情況下繼續；在最近的階段邊界處使用 /compact 繼續進行（請參閱階段邊界）。

銜接流程

這是一種起始情境，會產生工作，然後匯入主要流程。

• Bug 和請求堆積如山 → /triage。它將議題引導通過篩選角色，並產出代理程式就緒的議題，供後續的 /implement 處理。

  篩選僅適用於不是你建立的議題：錯誤報告、傳入的功能請求，任何以原始形式出現的內容。由 /to-tickets 產生的任務已經對代理程式就緒，所以不要對它們進行篩選。

• 有東西壞掉了 → /diagnosing-bugs。針對困難的 bug：一眼看不出來的那種、間歇性的不穩定問題、在兩個已知正常狀態之間潛入的回歸錯誤。它拒絕在擁有緊密回饋迴路（一個已經因這個 bug 而失敗的命令）之前進行理論推導，然後透過回歸測試來修復。一旦修復完成，在同一個會話中執行 /retro，詢問什麼可以預防這個 bug；如果真正的發現是沒有好的接縫可以鎖定它，那麼這就是 /improve-codebase-architecture 的工作。

• 一個龐大且模糊的努力：一個綠地專案或一個巨大的功能建置，太大而無法在一個會話中完成 → /wayfinder，這是這裡認知需求最高的流程。當從這裡到目的地的路徑還不明確時，它會在議題追蹤器上繪製一個由決策任務組成的共享地圖，並逐一解決它們，產出決策，而非可交付成果，直到迷霧被推開且路徑清晰。當 /grill-with-docs 打磨一個你可以在一個會話中掌握的構想時，wayfinder 是為你無法掌握的構想而設計的，它更慢也更密集，所以請僅在這種情況下使用它，切勿用於範圍明確的功能。

  當地圖變得清晰時，它會進行交接，而不是建置：在 /to-spec 處匯入主要流程，它會將地圖中連結的決策收斂成一個可建置的計劃，然後像往常一樣使用 /to-tickets 和 /implement。直接將地圖迴圈導入 /implement 會跳過這個收斂步驟，並丟棄連結的細節，因此只有在該努力結果確實很小時，才直接使用 /implement。

程式碼庫健康

這不是功能開發，只是維護工作。

• /improve-codebase-architecture 在你有多餘時間時運行，以保持程式碼庫適合代理程式運作。它會浮現深化機會 (deepening opportunities)；選擇一個機會會產生一個想法，你可以將其帶入主要流程，從 /grill-with-docs 開始。它是尋找候選項目的調查工具；/codebase-design（下方）則是針對所選項目進行設計的工作檯。

底層詞彙

兩個由模型驅動的參考資料，在其他技能之下運行，各自是其詞彙的單一事實來源。當文字（而非流程）是問題所在時，直接使用它們；或者讓上述技能來調用它們。

• /domain-modeling：打磨專案的領域語言：挑戰模糊的術語，解決過載的詞彙（例如「account」同時擔當三個角色），將難以逆轉的決策記錄為 ADR。這是 /grill-with-docs 驅動的主動紀律，以保持 GLOSSARY.md 成為一個乾淨的詞彙表。
• /codebase-design 是用於設計模組形狀 (shape) 的深層模組詞彙（模組、介面、深度、接縫、轉接器、槓桿、局部性）：在一個乾淨的接縫上，透過一個小介面提供大量行為。/tdd 和 /improve-codebase-architecture 都會使用它。

階段邊界

階段 (phase) 是會話中的一塊工作：打磨、實作、品管。在兩個階段的邊界 (boundary) 處，你有五個選擇，而在這整個地圖中，選擇它們之間是最模糊的決定：

• 繼續 (Continue)：保持現狀。沒有成本，沒有損失。
• /clear：清空視窗，當這裡的內容對下一步不重要時使用。
• /handoff 寫一個可攜帶的 Markdown 檔案。用途狹窄：僅用於新的測試框架 (harness)、新的目錄、同事，或在階段中分叉一個側邊任務。它帶來的好處是可攜帶性。
• 子代理 (Subagent)：將一個範圍緊密的任務發送到其自己的視窗，並取回報告。
• /compact 壓縮這個上下文，並用它來種子一個新的會話。這是預設選項，但位於決策樹的底部，而不是第一個考量。

請閱讀 PHASE-BOUNDARIES.md 以瞭解有序的決策樹：五個問題、每個分支背後的理由，以及為什麼首要的考量成本使得繼續成為第一個要排除的選項。在階段邊界處做出決定；在階段中間，則繼續進行，或將剩餘部分拆分給子代理。

獨立技能

完全脫離主要流程。

• /grill-me：與 /grill-with-docs 相同的深入訪談，但它是無狀態的：不在本地儲存任何內容，也不會建立 GLOSSARY.md。當你不在工作目錄中工作時使用它（打磨一個計畫、設計、一篇文章，或其他任何沒有儲存庫支援的內容）。如果你在工作目錄中，請改用 /grill-with-docs：它執行相同的訪談並留下書面記錄，因此嚴格來說是更好的選擇。
• /grilling 是訪談原語本身：回合、前沿、事實是代理程式的職責，決策是你的。/grill-me 和 /grill-with-docs 是兩個命名的進入方式，而 /triage、/wayfinder 和 /improve-codebase-architecture 都在內部運行它。僅當你想要進行沒有外層包裝的訪談時，才直接使用它。
• /prototype 是一個小的、一次性的程式，用來回答一個設計問題：這個狀態模型感覺對嗎？或者這個 UI 應該長什麼樣子？一次性是對程式碼撰寫方式的約束，而不是銷毀它的承諾：答案會融入真正的程式碼中，而原型本身會作為主要來源 (primary source) 保留在從 main 分支出來的 prototype/<name> 分支上，並從實作議題中指向它。這是主要流程步驟 2 中的繞道，但任何時候當一個設計問題難以在紙上解決時，都可以使用它。
• /research：將閱讀工作委派給一個背景代理程式：它會針對主要來源調查一個問題，然後在儲存庫中留下一個附有引用來源的 Markdown 檔案。在它閱讀的同時，你可以繼續工作。它產生的檔案是你可以帶入主要流程，從 /grill-with-docs 開始的東西，因為研究是為了滋養思考，而非取代它。
• /to-questionnaire 在你遇到的阻礙不在你的腦中或程式碼庫中，而是在別人的腦中時使用，它會為他們撰寫一份問卷來填寫。這是 /grill-me 的反向操作：它不是訪問你關於主題的事，而是訪問你關於發送對象（要發送給誰，你需要什麼回饋）的事，並將問題瞄準資訊缺口。回來的材料可以作為 /grill-with-docs 或 /to-spec 的輸入。
• /wizard 是專門處理只有人類才能採取的步驟：佈建基礎設施、設定憑證或 CI 密碼、點擊陌生的第三方儀表板、執行一次性遷移或切換。它會產生一個互動式 bash 腳本，開啟每個 URL，捕獲每個值，並將其寫入 .env 和 GitHub Secrets，這樣該程序就不再需要你每次向代理程式重新解釋。它是由模型驅動的，因此代理程式在遇到只有你才能通過的障礙時會自動使用它。如果代理程式可以自己完成，它就應該自己做；這是為了那些真正需要人類介入的環節。
• /wait-what 是針對未能傳達清楚的訊息的修正工具。在對話中途，在任何其他技能內部使用它，代理程式會使用 GLOSSARY.md 的詞彙，用簡單的英文，以你當時遺漏的上下文重新說明它剛剛說過的話。它是事後的補救措施；/grill-with-docs 是事前的預防，因為早期達成共識的共同語言可以防止行話的產生。
• /teach：在多次會話中學習一個概念，使用當前目錄作為有狀態的工作空間。
• /writing-for-agents 是撰寫代理程式會消費的文件（技能、AGENTS.md、指向的說明文件）的參考指南。

前置條件

/setup-matt-pocock-skills：在你的第一個工程流程之前運行，以配置其他技能所預期的議題追蹤器、篩選標籤和文件佈局。自訂的議題追蹤器也可使用。