Ask Matt

詢問 Matt

你不可能記得每個技能，所以開口問。

flow（流程） 是穿越技能的一條路徑。多數路徑沿著一條主流程行進，兩條進入匝道（on-ramp）匯入其中。其餘都是獨立技能，或是運行於其下的詞彙層。

主流程：點子 → 交付

多數工作走的路徑。你有個點子，想要把它做出來。

1. /grill-with-docs — 透過訪談磨利點子。每當你在工作目錄中作業時就從這裡開始：它是有狀態的，會把學到的內容留在 CONTEXT.md 與 ADR 中。（沒有工作目錄？改用 /grill-me——見「獨立技能」。兩者都運行同一個 /grilling 原語；grill-with-docs 是會留下紙本痕跡的那個，因此只要有 repo 可以留存，它就是兩者中較好的一個。）

2. 分支——你能否在對話中解決所有問題？ 如果某個問題需要可執行的答案（狀態、商業邏輯、你必須親眼看到的 UI），繞道原型，由 /handoff 在兩個方向上搭橋（原型住在自己的目錄裡，這正是 /handoff 的用途——見「階段邊界」）：

   • /handoff 出去，然後針對那個檔案開啟新的 session，
   • 用 /prototype 以一次性程式碼回答問題，
   • 把學到的內容 /handoff 回來，並在原始點子討論串中引用它。

3. 分支——這是跨越多個 session 的建置嗎？

   • 是 → /to-spec（把討論串轉成規格說明），然後用 /to-tickets 把它拆成曳光彈 ticket，每個 ticket 都宣告自己的阻塞邊。在本機追蹤器上，這表示每個 ticket 一個檔案，放在 .scratch/<feature>/issues/ 下，以人工方式優先處理阻塞者已完成的 ticket；在真正的追蹤器上，這些邊會變成原生的阻塞連結，因此任何阻塞項已完成的 ticket 都可以被認領——逐個 ticket 啟動 /implement，並在每個 ticket 之間 /clear 上下文。每個 ticket 都是自足的，所以最後一個的上下文可以直接丟棄。
   • 否 → 直接在同一個上下文視窗中執行 /implement。

   不管哪條路，/implement 透過在內部驅動 /tdd 來建置每個 issue——一次一個紅-綠切片——然後在 commit 之前，以 /code-review 收尾，這是針對 diff 的雙軸審查（規範 + 規格）。當你只想在沒有完整規格說明的情況下以測試先行的方式建置某個具體行為時，就單獨使用 /tdd；每當你想針對固定基點審查某個分支或 PR 時，就單獨使用 /code-review。

上下文衛生

把步驟 1–3 保持在一個不間斷的上下文視窗中——在 /to-tickets 完成之前不要 compact 或 clear——讓 grilling、規格說明與 ticket 都建立在同一份思考上。之後每次 /implement 才從 ticket 出發、重新開始。

這個做法的上限是**智慧區**：模型仍能清晰推理的視窗（在最新的模型上約 150k tokens）。如果 session 在 /to-tickets 之前就逼近這個上限，不要硬撐到品質劣化——在最接近的階段邊界 /compact，然後繼續（見「階段邊界」）。

進入匝道

一種會產生工作的起始情境，接著匯入主流程。

• Bug 與請求不斷堆積 → /triage。它讓 issues 在分診角色之間流動，產出可供代理（agent-ready）使用的 issues，之後由 /implement 接手。

  分診只用於不是你建立的 issues——Bug 回報、進來的功能請求、任何以原始樣貌抵達的內容。/to-tickets 產出的 ticket 已經可供代理使用，所以不要再分診它們。

• 有東西壞了 → /diagnosing-bugs。用於那些棘手的：一眼看不穿的 bug、間歇性的 flake、在兩個已知良好狀態之間悄悄冒出的回歸。在取得緊密的回饋迴圈——一個對這個 bug 已經顯示紅色的指令——之前，它拒絕空談理論，然後以回歸測試修復。當真正的發現是沒有好的接縫可以把 bug 鎖住時，它的事後檢討會交接給 /improve-codebase-architecture。

• 一個巨大、迷霧籠罩的努力——綠地專案或巨大的功能建置，大得單一 session 裝不下 → /wayfinder，這裡認知負擔最重的流程。當從這裡到目的地的路徑還看不見時，它會在 Issue 追蹤器上繪製一張決策 ticket 的共享地圖，並逐一解決它們——產出的是決策，而非交付物——直到迷霧被推開、路徑清晰為止。/grill-with-docs 磨利的是你可以在單一 session 中掌握的點子，wayfinder 則是給你掌握不了的那種——它比較慢也比較密集，所以只把它留給這種情況，絕不用在範圍明確的功能上。

  當地圖清晰後，它交接，而不是建置：在 /to-spec 匯入主流程，它會把地圖上彼此關聯的決策收斂成可建置的計畫，然後照常 /to-tickets 與 /implement。把地圖直接繞進 /implement 會跳過那次收斂，把關聯的細節丟掉——只有當這次努力實際上真的很小時，才直接前往 /implement。

程式碼庫健康

不是功能開發——是維護。

• /improve-codebase-architecture ——只要有空閒時間就執行，讓程式碼庫對代理而言保持良好作業狀態。它會浮現深化機會；挑選其中一個就會產生一個點子，你可以帶著它從 /grill-with-docs 進入主流程。它是找出候選者的普查；/codebase-design（見下方）則是你用來設計所選項目的工作台。

底層詞彙

兩個由模型自動叫用的參考，運行在其他技能之下——各自是其詞彙的單一事實來源。當問題出在用詞而非流程時，直接使用它們；或讓上面的技能把它們帶進來。

• /domain-modeling ——磨利專案的領域語言：質疑模糊的術語、解決一個詞過度負載的問題（"account" 同時做三件事）、把難以反轉的決策記錄成 ADR。這是 /grill-with-docs 驅動的主動紀律，讓 CONTEXT.md 保持為乾淨的詞彙表。
• /codebase-design ——用於設計模組形狀的深模組詞彙（模組、介面、深度、接縫、轉接器、槓桿收益、局部性）：在乾淨的接縫處，用小介面涵蓋大量行為。/tdd 和 /improve-codebase-architecture 都用這套詞彙。

階段邊界

phase（階段） 是 session 內的一塊工作——grilling、實作、QA。在兩者之間的邊界，你有五個選項，而如何在其中選擇，是整張地圖中最模糊的決策：

• Continue（繼續） ——待在原地。不花任何成本，也不失去任何東西。
• /clear ——清空視窗，當這裡的內容對接下來要做的事都不重要時。
• /handoff ——寫一個可攜帶的 markdown 檔案。範圍很窄：只用於新的執行環境、新的目錄、同事，或在階段中途岔出一個旁支任務。它買到的是可攜帶性。
• Subagent（子代理） ——把範圍緊密限定的任務送到它自己的視窗，並拿回一份報告。
• /compact ——壓縮這個上下文，並用它孕育出一個新的 session。這是預設選項，位於樹的底部，而不是最先伸手去拿的。

閱讀 PHASE-BOUNDARIES.md 以了解有序的決策樹——五個問題、每個分支背後的推理，以及為什麼主要來源的成本讓 Continue（繼續） 成為最先排除的選項。在邊界上做決定；在階段中途，就繼續，或把剩餘的部分拆給子代理。

獨立技能

完全脫離主流程。

• /grill-me ——與 /grill-with-docs 相同的鍥而不捨的訪談，但無狀態：它不會在本機儲存任何東西，也不會建立 CONTEXT.md。當你不在工作目錄中作業時使用它——磨利一個計畫、一個設計、一篇寫作、任何下面沒有 repo 的內容。如果你在工作目錄中，改用 /grill-with-docs：它運行相同的訪談並留下紙本痕跡，所以嚴格來說是較好的選擇。
• /grilling ——訪談原語本身：回合、前沿，事實是代理的工作，決策是你的。/grill-me 和 /grill-with-docs 是兩個有名稱的入口，而 /triage、/wayfinder 與 /improve-codebase-architecture 都在內部運行它。只有當你想要沒有任何外殼包裹的訪談時，才直接使用它。
• /resolving-merge-conflicts ——逐塊處理進行中的 merge 或 rebase 衝突，依意圖解決——追溯到每一方的主要來源，而不是挑選行——然後完成操作。它絕不執行 --abort。獨立且脫離所有流程：當你已經身處衝突之中時使用它。
• /prototype ——一個小型、一次性的程式，回答一個設計問題：這個狀態模型感覺對嗎，或這個 UI 應該長什麼樣子。一次性是對程式碼撰寫方式的約束，而不是銷毀它的承諾：答案會融入真正的程式碼，而原型本身以主要來源的身分保存在 main 之外的一條 prototype/<name> 分支上，並從實作的 issue 指向它。這是主流程第 2 步的繞道，但任何時候只要設計問題難以在紙上定案，都可以使用它。
• /research ——把閱讀的苦工委派給背景代理：它會針對主要來源調查一個問題，然後在 repo 中留下一份有引用的 Markdown 檔案。它閱讀時你可以繼續工作。它產出的檔案是要帶進主流程、在 /grill-with-docs 使用的素材——research 餵養思考，而不是取代思考。
• /to-questionnaire ——當卡住你的東西不在你的腦中或程式碼庫，而是在別人的腦中時，這個技能會為他們寫一份問卷來填寫。它是 /grill-me 的反向：不是訪談你有關主題的事，而是訪談你有關發送的事——要寄給誰、你需要什麼回覆——並把問題瞄準那個缺口。回來的內容是 /grill-with-docs 或 /to-spec 的素材。
• /wizard ——用於只有人類能做的步驟：佈建基礎設施、設定憑證或 CI secrets、點擊陌生的第三方儀表板、執行一次性遷移或切換（cutover）。它會產生一個互動式 bash 腳本，開啟每個 URL、捕捉每個值，並把它們寫入 .env 與 GitHub secrets——讓這個程序不再是每次都要向代理重新解釋的東西。由模型叫用，所以代理一旦碰到只有你能越過的牆，就會立刻使用它。如果代理能自己做，它就應該自己做；這是給人類真正身處迴圈（in the loop）之用的。
• /wait-what ——針對沒有傳達到位之訊息的事後矯正。在對話中途、任何其他技能內部使用它，代理會用你缺少的上下文、以淺白的英文，並使用 CONTEXT.md 的詞彙，重新說明它剛剛說的話。它在事後才有效；/grill-with-docs 才是事前解方，因為及早達成共識的共同語言，正是讓行話根本不會出現的原因。
• /teach ——在多次 session 中學習一個概念，把目前目錄當作有狀態的工作區。
• /writing-for-agents ——撰寫代理會消費之文件的參考：skills、AGENTS.md、被指向的文件。

前置條件

/setup-matt-pocock-skills ——在你的第一個工程流程之前執行，以設定其他技能所預設的 Issue 追蹤器、分診標籤與文件布局。自訂的 Issue 追蹤器也行。