ravan/hogwash

hogwash 是做什麼的？

掌握改寫循環。Hogwash 負責掃描和報告。您負責建立候選版本、改寫它、重新掃描，然後請使用者核准。

執行腳本

此技能內附自己的腳本。讓 $SKILL 代表包含此 SKILL.md 的目錄。如果該目錄缺少 node_modules，請先安裝相依套件一次：

cd "$SKILL" && bun install --frozen-lockfile

所有其他指令都從專案目錄執行，並傳遞相對於專案的路徑：

bun "$SKILL/scripts/hogwash.ts" scan --output json docs/post.md

腳本會從目前的工作目錄讀取 hogwash.json 和特徵檔案，因此請將專案目錄設為工作目錄。需要 Bun 1.4 或更新版本。如果缺少 bun，請回報並停止。

設定專案

如果專案中不存在 hogwash.json，請執行：

bun "$SKILL/scripts/hogwash.ts" init

這會寫入 hogwash.json，並從捆綁的範本中複製 profile/voice.md、profile/quality.md 和 profile/ban-list.md。它絕不會覆蓋已存在的特徵檔案。它不會安裝其他任何東西，因為此技能已安裝完畢。

複製出來的特徵檔案是種子檔案。/idiolect 技能會建立真正的特徵檔案：它會將聲音捕捉為有證據支持的機制，並可能在語音特徵檔案旁新增 registers/ 目錄，以加入特定格式的覆蓋層。只有使用者能執行 /idiolect。當特徵檔案需要調整時，建議使用者這麼做；永遠不要自行呼叫它。

遵守這些界限

• 每當需要掃描器結果時，明確執行 bun "$SKILL/scripts/hogwash.ts" scan。沒有其他指令會進行掃描。
• 在改寫循環期間，永遠不要修改原始檔案。
• 使用 <stem>-hogwash<ext> 作為候選檔名。對於 docs/post.md，請使用 docs/post-hogwash.md。對於 README，請使用 README-hogwash。
• 將設定的顧問和原生子代理視為唯讀顧問。他們永遠不會編輯共享檔案、執行掃描或主導循環。
• 僅在使用者明確要求接受候選版本時，才執行 bun "$SKILL/scripts/hogwash.ts" accept --approved <original>。

將工作流程顯示為即時計畫

當框架提供計畫或待辦事項清單（Codex 中的計畫工具、Claude Code 中的任務清單）時，請在整個工作階段中將 Hogwash 工作流程保留在上面，並在狀態變更時立即更新步驟。使用這些標準步驟，以便每個框架顯示相同的計畫：

1. 驗證配置和特徵檔案
2. 掃描原始檔案並凍結基準
3. 建立或恢復候選版本
4. 改寫候選版本（每次通過一個條目：「改寫次數 N」）
5. 判斷文字差異並重新掃描
6. 呈現決策和審查關卡
7. 接受候選版本（僅在明確要求後）

一次只保持一個步驟進行中。當循環暫停等待使用者決策時，待處理的步驟保持開啟，其單行註解說明使用者必須決定什麼。僅在確實有額外工作（例如諮詢）時才新增步驟；切勿填塞計畫。如果框架沒有計畫介面，則在每次交接時以單一狀態行開啟：剛剛完成的步驟，現在待處理的步驟。

保留作者的資訊

Hogwash 是一個編輯工作流程，而非研究或創作工作流程。原始文件是事實和論證內容的唯一來源。

• 您可以重新措辭、重新排序、拆分、合併或移除空洞的填充內容，同時修復掃描發現並套用特徵檔案。請保留每一個實質性的事實、主張、範例、數字、名稱、引用、立場、關係和不確定程度。
• 切勿添加原始文件中不存在的事實、主張、範例、數字、名稱、來源、引用、連結、論點、反論點、建議、結論、含義或其他資訊。請勿為了豐富、驗證、查找來源或填補改寫中的空白而進行瀏覽或研究。
• 特徵檔案絕不能凌駕於來源忠實度之上。如果掃描器的發現或特徵檔案要求需要原始文件中不存在的資訊，請讓該要求未滿足，並將衝突報告為一個非阻塞性的審查問題。請不要捏造一段符合要求的段落。同樣的情況也適用於解決發現的唯一方法是削弱、加強或刪除作者的主張（例如掃描器標記的獨特性或絕對化主張）：請將該列保留為未解決，並將其提出為一個選擇問題（保留主張並放棄發現、套用引用的改寫，或刪除主張），而不是默默地更改主張。如果使用者隨後明確確認該被標記的主張是預期的，則將該列標記為 Waived (owner)。被放棄的列在每個需要可操作清潔掃描的關卡中被視為已解決，但它會保留在報告中，以便決策是可見的。豁免僅涵蓋該次出現，僅來自本次對話中使用者的明確陳述，並且絕不能從沉默、建議或繼續的請求中推斷出來。此衝突例外僅涵蓋事實性主張：僅當句子的真值條件發生變化時，發現才會更改主張。修辭上的強調、評價性形容詞和宣告性的輔助詞（完美、真正的、確切地、尖端的）是風格，而不是主張；請透過命名具體事物來修復它們，即使之後句子讀起來感覺較弱。「刪除這個詞會削弱句子」本身絕不是升級的理由。當使用者指示一個能保留被標記主張的改寫時，請將該列記錄為 Waived (owner)，並將該指令作為豁免依據，切勿記錄為 Resolved：掃描器只是停止匹配，並且分類帳必須說明所有者保留了該主張。
• 如果使用者想要新的實質內容，請將其保留在 Hogwash 改寫循環之外。請他們更新原始文件，或啟動一個單獨的內容編輯任務。

保留命題邊界

• 保留的不僅僅是大概意思。對於每個命題，保持相同的行動者、行動、物件、所指對象、技術製品、範圍、模態、極性、量詞、時間、序列、條件、例外、原因、關係、比較、強調和不確定程度。
• 將語義限定詞視為實質性內容。像 may、might、can、would、must、only、always、never、under、when、taken literally 和 depending on 這樣的詞語和片語不能被添加、刪除或替換，除非結果命題是相同的。
• 切勿將一個主張從一個問題、元件、範例或情況擴展到一個框架、系統、類別或一般規則。切勿反向縮小一個主張。保留原始的技術名詞，而不是用一個更廣泛的近義詞來替換它。
• 將每個新的句子、標題、回呼、過渡、綜合和摘要視為需要在原始檔案中有直接支持的主張。合併兩個來源段落不得產生新的結論、含義、因果關係、比較或強調程度。
• 偏好能解決發現的最小本地編輯。僅在必要時才改寫整個段落或文件，因為較大的改寫會增加語義漂移的風險。

判斷文字差異

• 在每次自主或用戶導向的編輯通過後，針對原始檔案執行文字差異工具，並閱讀差異本身。在沒有判斷差異的情況下，打開圖形差異、憑記憶進行比較、保留大意或依賴掃描器都不是驗證。
• 同時判斷流暢性和忠實度。單獨閱讀每個被更改的句子。如果最小的本地編輯留下了一個不流暢的子句或循環陳述，請改寫整個句子，而不是發送修補程式。
• 同時判斷結構和命題。除非特定的發現或特徵檔案規則強制要求變更，否則請保留原始的段落邊界和句子長度分布。在整個文件中分割段落或均化句子長度是一種改寫缺陷，而不是修復。
• 審計每個被更改或添加的句子和標題，對照支持它的原始檔案段落。檢查上述每個命題邊界。移除或修正任何無法直接追溯到原始檔案的內容。
• 在審查關卡之前和接受之前，立即再次執行並判斷文字差異。一次乾淨的掃描僅證明掃描器沒有找到可行動的模式。它絕不能證明來源的忠實度。
• 當任何範圍、模態、限定詞、技術所指對象、關係、強調或不確定程度發生變化時，請勿報告來源忠實度合規。請改為報告確切的不匹配。

驗證專案

在任何工作流程操作之前，請讀取 hogwash.json 並確認所有三個 profile 路徑都存在且包含文字。確認 workflow.maxPasses 是一個正整數。缺少一個特徵檔案意味著骨架不完整。執行 bun "$SKILL/scripts/hogwash.ts" init 來建立缺失的骨架檔案。該命令會保留每個已存在的特徵檔案。

格式錯誤或 schema 無效的 hogwash.json 會停止工作流程。如果讀取檔案失敗或任何 Hogwash 命令報告配置錯誤，請報告確切的錯誤並要求使用者修復配置。請勿編輯或繞過配置、建立或恢復候選版本，或繼續進行另一個工作流程操作。

當特徵檔案需要調整時，請使用特徵檔案訪談指南。

選擇掃描器模式

掃描器確切知道三種模式——technical、prose 和 marketing——並根據每種模式校準每個文體學基準和規則權重。hogwash.json 設定專案預設值。在錯誤的模式下掃描的文件會得到有偏差的發現。

在首次掃描文件之前，請將其格式映射到掃描器模式：

• technical — 架構文件、ADR、README、API 參考、操作手冊、規格說明。
• prose — 部落格文章、散文、文章、電子郵件以及其他敘事性或個人寫作。
• marketing — 登陸頁面、產品文案、新聞稿、公告。

當映射的模式與專案預設值不同時，請在該文件的每次掃描中傳遞 --register <name>。對基準掃描和每個候選重新掃描使用相同的模式；在中途更改它會使掃描結果無法比較。當格式不明確時，請使用專案預設值並說明。

此選擇僅用於校準掃描器。個人語言的 registers/ 覆蓋層是一個單獨的機制：它們會根據格式塑造改寫的聲音，且其名稱是開放式的。兩者是按格式而非名稱對齊的——一個 blog 覆蓋層會與 prose 掃描器模式配對。

改寫一份文件

1. 執行 bun "$SKILL/scripts/hogwash.ts" scan --output json --register <register> <original>，使用上面選定的模式。
2. 從該報告中凍結一個基準檢查清單。切勿用後來的掃描結果替換其列或證據。完成狀態是唯一可變的欄位。
3. 用以下欄位記錄每個基準列：ID、規則、行號和列號、匹配、訊息、建議、可行動或建議狀態，以及完成狀態。
4. 透過複製原始檔案來建立候選版本，除非候選版本已存在。如果存在，請恢復它，而不要在其上複製。根據恢復的候選版本重建完成狀態，並開始一個新的自主傳遞預算。即使基準沒有可行動的發現，也總是產生候選版本。
5. 僅改寫候選版本。在來源忠實度邊界內套用基準檢查清單、個人語音特徵檔案、合併的品質和風格規則以及禁用清單。如果個人語音特徵檔案旁存在 registers/ 目錄，也請讀取名稱與文件格式（部落格、電子郵件、技術文件...）相符的覆蓋層；覆蓋層會在差異處覆蓋核心語音。匹配特徵檔案的機制，而不僅僅是其用詞選擇：保持作者句子的長度分布，而不是將句子均化；並保持他們的標點、縮寫和代詞習慣。當 idiolect 技能已安裝時，其 references/apply.md 自我檢查順序將主導改寫。
6. 針對候選版本驗證每個原始的可行動基準列。在每次傳遞後，針對原始檔案執行並判斷文字差異，並遵守命題邊界規則。移除任何引入的命題，並恢復任何被移除、擴展、縮小、加強、削弱或不精確重新命名的命題。僅當候選版本在不破壞特徵檔案或來源忠實度的情況下解決了該出現時，才將一列標記為完成。僅當訊息描述的問題已從段落中消失時，該列才算已解決。套用禁用清單意味著重新建構，而不是替換最接近的相似標記（以冒號或空格連字號代替被禁用的長破折號，以斜體代替被刪除的強調片語）。當被標記的主張或結構仍然存在時，一個停止模式匹配的標點、同義詞或詞序交換並不能解決該列。
7. 明確執行 bun "$SKILL/scripts/hogwash.ts" scan --output json --register <register> <candidate>，使用與基準掃描相同的模式。
8. 如果當前掃描包含所有者未豁免的可行動發現，請改寫候選版本並從步驟 6 重複。

建議性發現不會阻塞完成。在改寫內部處理每個建議性發現：修復它或保留它，並在一行中報告該操作。僅當選擇改變了意義、範圍或作者的主張，或者當特徵檔案與來源衝突時，才提出審查問題。對於硬性禁用清單已經要求的編輯，切勿請求核准；對於特徵檔案已經規定的常規風格編輯，也切勿請求核准。

顯示靜態掃描發現了什麼

在每次審查關卡或停止循環的交接時，在詢問使用者下一步要做什麼之前，先以摘要形式報告已凍結的初始掃描結果：基準發現的總數，分成可行動和建議性計數，以及有多少可行動列已解決和未解決。除非使用者要求查看詳情，否則不要呈現每個發現的表格。

即使處於摘要模式，有兩種列仍需要單獨報告，因為使用者必須決定它們：未解決的可行動列（每列一行：規則、匹配、未解決的原因）以及所有者豁免的列（每列一行：規則、匹配、豁免依據）。其他所有內容都保留在摘要格式中。

...

[翻譯時截斷]