gvozdb/semantic-spec-writer-skill

語意規格撰寫器

產出 .plan.ctx 與 .spec.ctx 檔案，讓實作代理程式無需載入本技能即可直接使用。

模式

• 新文件：直接根據請求與已確立的儲存庫事實撰寫最終的語意成品。請勿先建立散文草稿。
• 既有文件：僅按需求轉換，保留來源的意義與識別符。最終成品必須比來源更短。
• 交接或重複使用：為另一個代理程式或後續回合的獨立執行最佳化。
• 儲存庫執行封包：當使用者想要程式碼交接且程式碼庫可用時，請閱讀 references/execution-packets.md。在撰寫封包之前，先建立最小的讀取/編輯路徑。

請勿宣稱轉換能為一次性實作節省總代幣數。轉換會增加一個撰寫步驟；其經濟效益來自於更小的可重複使用上下文與更少的實作模糊性。

目標

最佳化整個實作循環，而非僅字元數：

• 保留每一個行為、約束、邊界情況與精確識別符；
• 移除敘述、重複、裝飾性中繼資料與泛用建議；
• 暴露從需求到編輯再到驗證的最短路徑；
• 優先使用直接語言，而非需要解譯的簡寫。

較小的檔案只有在能更快地正確執行時才有用。轉換既有文件時，請在撰寫前規劃精簡的結構，並避免擴充來源。請勿僅為了追求檔案大小而添加工具迴圈或重複改寫。

代幣紀律

• 除非缺少事實需要特定查閱，否則每個提供的來源只讀取一次。
• 僅檢查界定範圍、介面與驗證所需的檔案。
• 寫出一個最終成品。使其在初次撰寫時就比來源更短。對於轉換，請從此技能目錄執行 scripts/check_conversion.py SOURCE OUTPUT 一次。當目標分詞器已知且 tiktoken 可用時，請加上 --encoding NAME。如果檢查失敗，請移除重複內容一次，並再執行一次；切勿進入追逐大小的迴圈。除非被要求，否則請勿輸出大綱、草稿、轉換筆記、大小報告或說明。
• 請勿複製實作代理程式無需搜尋即可從確切目標檔案取得的儲存庫事實。包含能防止錯誤編輯或額外探索的事實。
• 優先使用確切路徑與一個可執行的驗證指令，而非泛用的實作建議。
• 對於執行封包，僅在能消除下游探索或防止錯誤編輯的事實上花費撰寫心力。請勿將封包變成儲存庫傾印。
• 給予執行封包參考資料中的標準有界下游循環：一次路由讀取、一次實作傳遞、一次宣告驗證，成功即停止。只有在出現具體矛盾或失敗時才進行擴展。

格式

• 以純文字 plan 或 spec 開頭。
• 計畫使用 .plan.ctx，規格使用 .spec.ctx，除非專案另有慣例。
• 使用明顯的本機區塊名稱。它們是標籤，而非保留的語言關鍵字。
• 僅包含承載資訊的區塊。請勿輸出空章節。
• 當分開的區塊會重複相同資訊時，合併目標、範圍與合約事實。
• 精確保留檔案路徑、符號、API 路由、欄位、表格、環境變數、指令、狀態、角色與錯誤文字。
• 精確保留欄位的所有權與巢狀結構。根據實作語言匹配欄位表示法：對於 Python JSON/映射使用 event["payment_id"]，而非 event.payment_id。切勿發明來源未定義的 data、payload 或其他包裝器。
• 將 .ctx 視為純文字，而非 Markdown。請勿將一般識別符以反引號、粗體或其他顯示標記包裹。僅在 verify 下的可執行指令使用反引號。
• 僅在能消除實際重複時定義本機術語。偏好描述性術語；避免單字母別名與發明的表示法。
• 僅在另一個項目參照時才加入 ID。
• 使用熟悉的表達式，例如 x=true、x in [a,b] 與 condition -> result。請勿依賴隱藏語法。
• 僅在結構化欄位會遺失關鍵細微差別時使用簡短的 # 註解。
• 將並行驗證、輸出欄位與確切錯誤分組在一個精簡的映射下，而非重複相同的句子框架。
• 在確立欄位所有權後，在驗證與錯誤映射中使用簡短明確的標籤，而非重複完整的擁有者路徑。
• 在錯誤映射中，讓區塊承載重複的文法。偏好 field: condition | ErrorType "exact message" 而非在每一行重複 invalid owner.field -> ErrorType。
• 每行保留一個可獨立測試的規則。當文法一致時，共享映射可以容納相關的欄位案例。
• 僅在 acceptance 下使用 A* ID 一次。請勿重複使用驗收 ID 作為規則或任務 ID。

奠基

當程式碼庫可用時，請在撰寫前先探查。捕捉已知的編輯範圍、既有介面、約束與可執行的驗證指令。僅在確切指令或既有命名檢查時包含 verify；請勿發明驗證場景。請勿猜測檔案名稱或架構。

未知的決策屬於 open_questions。當沒有未知事項時，省略該區塊。

資訊順序

按照實作代理程式需要的順序放置資訊。僅使用相關部分：

1. 目標或目的，包含已知時的確切編輯範圍；
2. 目標未陳述的合約；
3. 規則、不變量、狀態或流程；
4. 僅在相依性重要時的有序工作；
5. 驗證指令與可觀察的驗收；
6. 未解決的問題。

確切的範圍與驗證通常能比積極的散文壓縮節省更多代理程式工作。

壓縮規則

• 每個事實只陳述一次。
• 合併重複的需求。
• 當區塊的內容已由另一行承載時，省略該區塊。
• 讓驗收參照現有的規則、合約與驗證 ID，而非重述其散文。
• 僅在參照的區塊已陳述可觀察行為時，將驗收保留為參照。
• 僅在理由會改變實作決策時保留理由。
• 將模糊的動詞（例如 improve、support、handle、optimize 與 fix）替換為可觀察的結果。
• 保留罕見但後果嚴重的邊界情況。切勿為了讓檔案更短而刪除它們。
• 請勿僅為了減少字數而將一般需求編碼為公式。
• 當更容易正確執行時，偏好來自來源的確切整數公式，而非較長的散文描述。

範例

實作規格：

spec
target: [src/payments.ts,tests/payments.test.ts] :: 透過 Idempotency-Key 使 POST /payments 具有冪等性
keep: 回應結構、驗證行為

rules:
  R1: key 的作用域為 user_id
  R2: 相同使用者 + 相同 key + 相同 body -> 回放原始狀態與 body
  R3: 在回傳成功前保留結果

errors:
  E1: 缺少 Idempotency-Key -> 400 idempotency_key_required
  E2: 相同 key + 不同 body -> 409 idempotency_conflict

verify:
  V1: `pnpm test tests/payments.test.ts`

acceptance:
  A1: R1,R2,R3,E1,E2 -> V1

並行驗證映射：

validation:
  retries: int>=0 | ValueError "retries must be non-negative"
  timeout: int>0 | ValueError "timeout must be positive"

實作計畫：

plan
goal: 將會話儲存從記憶體遷移至 Redis，不改變 API 行為

facts:
  目前儲存: src/session/memory.ts
  合約測試: tests/session.contract.test.ts

tasks:
  T1: 在既有 SessionStore 介面後加入 Redis 適配器
  T2: 針對記憶體與 Redis 適配器執行合約測試
  T3: T2 通過後切換組合根節點

verify:
  V1: `pnpm test tests/session.contract.test.ts`

品質關卡

在完成前，請驗證：

• 新的實作代理程式可以在沒有此技能或未陳述的上下文的情況下執行；
• 每一行都會改變範圍、行為、實作順序或驗證；
• 沒有任何需求被重複，或被未定義的縮寫取代；
• 已知的檔案、介面與指令都是確切的；
• 驗收是可觀察的，並追溯至陳述的合約；
• 每個欄位仍擁有與來源相同的擁有者與巢狀結構；
• 結果是透過移除冗餘而變短，而非透過模糊意義。

首先輸出語意文件。僅在存在實際上會阻礙實作的未解決決策時，才附加單獨的筆記。