MarcoGarcian/preregister

/preregister — 預註冊文件產生器

產生一份可直接提交至註冊平台的預註冊文件。使用者需自行上傳至實際的註冊平台（OSF / AsPredicted / AEA RCT Registry）——此技能僅負責撰寫內容與結構，不負責提交。

為什麼要預註冊

預註冊是在看到數據之前（或對於觀察性分析，在分析已實現結果之前）對你的假設、設計和分析計畫做出的書面承諾。它能將確認性檢驗與探索性檢驗分開，保護你免於 p-hacking、HARKing 以及分叉路徑問題。不同領域使用不同的註冊平台：

• 政治科學、心理學、廣義社會科學 → 預設使用 OSF（osf.io/registries）。AsPredicted（aspredicted.org）是實驗常用的簡短格式。
• 經濟學實地實驗 → 自 2018 年起，AEA 期刊投稿必用 AEA RCT Registry（socialscienceregistry.org）。
• 公共衛生 / 臨床試驗 → 使用 ClinicalTrials.gov 或 ISRCTN（此技能不涵蓋——請使用該試驗註冊平台的專用模板）。

何時使用

• 在啟動實驗（實驗室、實地或問卷調查）之前。
• 在針對特定研究問題收集目標群體的觀察性數據之前。
• 在你已取得數據但尚未針對主要假設進行分析之前。
• 在修改與答覆階段，審稿人要求提供書面預分析計畫時。

何時不應使用

• 在你看過已實現結果後想進行「回朔性預註冊」——這不是預註冊。若輸入描述包含結果，技能將拒絕執行。
• 用於探索性分析——這類分析不需要預註冊，而是需要透明的標示。
• 用於統合分析——請直接使用 PROSPERO，而非此模板。

工作流程

第一階段 — 讀取輸入

兩種輸入模式：

1. --input <路徑> — 由 /interview-me 產生的研究規格（儲存於 quality_reports/specs/ 下）或任何結構化的 Markdown 檔案。讀取規格並提取：研究問題、假設（必須有方向性！）、數據來源、設計、樣本、分析方法。若規格中記錄了論文類型（/interview-me 會寫在 **Paper type:** 行，例如 survey-experiment），則可用來偏向選擇風格。
2. 無 --input — 提示使用者輸入 1–3 段的研究描述，然後繼續。若描述中遺漏方向性假設，則詢問一次。不要憑空捏造。

拒絕條件（必須在任何草擬之前檢查）：

• 描述包含已實現結果（「我們發現」、「估計值為」、「p =」）→ 拒絕，並回覆：「預註冊是前瞻性的；此描述包含結果。您是否是想使用 /respond-to-referees 或撰寫方法段落？」
• 描述完全沒有可檢驗的假設（純探索性框架）→ 標記並詢問使用者是否想要 OSF 模板的「探索性分析」版本（仍然有用，但非已註冊的確認性檢驗）。

第二階段 — 選擇風格

未提供 --style 時，依領域預設如下：

領域訊號	預設風格
**Paper type:** survey-experiment 或政治科學/心理學背景	osf
經濟學實地實驗 / 標示為「RCT」/ IRB 核准的隨機干預	aea-rct
9 題快速表格請求、實驗室心理實驗、時間壓力	aspredicted
其他	osf

使用者可透過 --style osf|aspredicted|aea-rct 覆蓋預設值。

第三階段 — 產生文件

讀取 templates/preregistration-template.md。該模板包含三個風格區段；僅使用與所選風格匹配的區段（不要合併——各註冊平台格式不同）。

所有風格共通的部分，文件必須包含：

• 標題與作者。
• 日期與版本。
• 指向來源規格的連結（若使用 --input），以確保可追溯性。

各風格特有的區段：

• osf — 假設（有方向、編號）· 設計 · 抽樣計畫 · 變數 · 分析計畫 · 推論標準 · 數據排除 · 缺失數據處理 · 探索性分析（明確標示）· 其他。
• aspredicted — 依據 AsPredicted 表格的 9 個編號欄位：(1) 數據收集狀態、(2) 假設、(3) 主要依變數、(4) 條件、(5) 分析、(6) 離群值/排除、(7) 樣本大小 + 停止規則、(8) 其他事項、(9) 名稱（研究而非論文）。
• aea-rct — 干預措施 · 結果（主要、次要）· 主要假設 · 樣本（目標 N、資格條件、隨機化單位、隨機化方法）· IRB 核准 · 試驗日期 · 檢定力計算 · 預分析計畫附件 · 狀態（尚未開始 / 進行中 / 已完成）。

每個區段標記以下之一：

• MUST — 註冊平台要求此項；文件缺少此項將無法提交。
• SHOULD — 強烈建議；審稿人預期會看到。
• MAY — 可選；若相關則納入。

重複使用 templates/requirements-spec.md 中的 MUST/SHOULD/MAY 框架。對於輸入中未提供的每個 MUST 項目，寫入 [CLARIFY: <具體問題>] 而非憑空捏造內容。

第四階段 — 交叉檢查（寫入磁碟前）

若以下任何檢查失敗，則拒絕將文件標記為「準備就緒」：

• 假設方向性。 每個假設必須包含方向（「高於」、「增加」、「負向預測」；在等效檢定下，「無效果」可接受為方向性陳述）。拒絕沒有方向的「與...相關」。
• 指定估計式。 分析計畫指名特定的估計式（OLS、logit、fixest::feols、lme4::lmer、ATT 差異平均值...）以及主要結果變數。僅寫「迴歸」不夠。
• 樣本計畫數值化。 出現目標 N、停止規則或檢定力計算目標。「盡可能多」不是樣本計畫。對於 RCT 和前瞻性設計，請遵循 /power-analysis 的 SKILL.md（讀取它——此技能僅由使用者調用，因此無法在此技能內部呼叫），以產生該領域的 MDE / 所需 N 以及可供貼上的檢定力段落。
• 事後排除規則。 離群值和排除規則須在看到數據之前陳述（「我們將排除完成時間 < 1 分鐘的觀察值」）。模糊的「我們會處理離群值」失敗。
• 內部一致性。 若設計是隨機化的，隨機化單位須與分析單位一致，或者分析計畫須處理集群效應。若為觀察性研究，須陳述識別策略。

對於每項失敗，文件會得到一個 [CLARIFY: …] 佔位符；文件會寫入磁碟，但在輸出摘要中標記為「不完整 — N 個 MUST 項目未解決」。

第五階段 — 事後驗證

若文件在理由部分引用了先前文獻（例如「基於 Hainmueller et al. 2014，我們預期…」），則透過 Agent 工具呼叫 /verify-claims 以事實查核這些引用。傳遞草稿路徑和明確引用列表。claim-verifier 代理（全新上下文，從未見過草稿）會針對每個引用回傳 PASS / PARTIAL / FAIL。在輸出摘要中呈現任何 FAIL/PARTIAL。

若符合以下條件則跳過事後驗證：

• 文件中沒有引用先前文獻。
• 使用者傳遞 --no-verify（此標記繼承自 /lit-review 和 /research-ideation 的事後驗證）。

第六階段 — 輸出

寫入 quality_reports/preregistrations/YYYY-MM-DD_<slug>.md（已加入 gitignore——預註冊應附上時間戳記並上傳至外部，不應與程式碼一起提交）。

在聊天中顯示：

✓ 預註冊草稿已儲存：quality_reports/preregistrations/<file>.md
  風格：<osf|aspredicted|aea-rct>
  區段：<數量> 總計 — <完整> 完整，<待釐清> 個 [CLARIFY:] 佔位符
  引用驗證：<通過>/<部分通過>/<失敗>  （或「無待驗證的引用」）
  下一步：檢視 [CLARIFY:] 佔位符，填寫完成後上傳至 <registry-url>

包含註冊平台網址：OSF → osf.io/registries、AsPredicted → aspredicted.org、AEA RCT → socialscienceregistry.org。

交叉參考

• templates/preregistration-template.md — 此技能使用的三種風格模板。
• templates/requirements-spec.md — 此處重複使用的 MUST/SHOULD/MAY 標註語言。
• .claude/skills/interview-me/SKILL.md — 透過 --input 產生此技能消費的規格。
• .claude/skills/power-analysis/SKILL.md — 遵循（但非呼叫）以提供樣本計畫欄位（RCT）的 MDE / 所需 N + 檢定力段落。
• .claude/skills/verify-claims/SKILL.md — 第五階段呼叫此技能進行引用事後驗證。
• .claude/references/discipline-cards.md — 驅動 --style 選擇的領域預設值。
• .claude/rules/replication-protocol.md — 預註冊是前瞻性承諾；重現性協定是回顧性合約。

範例

範例 1 — 來自規格的政治科學問卷實驗

使用者說：「預註冊這項研究」（附 --input quality_reports/specs/2026-04-15_priming-effects.md） 操作：

1. 讀取規格；**Paper type:** survey-experiment → 預設風格 osf。
2. 提取 2 個方向性假設、MTurk N=1,200、帶處理虛擬變數的 OLS。
3. 產生 OSF 文件，所有 MUST 區段已填寫，1 個 MAY 留空。
4. 規格之外無引用先前文獻——跳過事後驗證。 結果： 儲存至 quality_reports/preregistrations/2026-04-15_priming-effects.md。使用者上傳至 OSF。

範例 2 — 經濟學實地實驗，AEA RCT Registry

使用者說：「為現金轉移試點計畫草擬一份 AEA RCT 預註冊」（附 --style aea-rct --input quality_reports/specs/2026-03-10_ct-pilot.md） 操作：

1. 讀取規格；隨機化單位 = 村莊，主要結果 = 消費。
2. 產生 AEA RCT 欄位。規格中缺少 IRB 編號 → [CLARIFY: IRB 核准編號]。
3. 交叉檢查：估計式（集群穩健 OLS）、主要結果已陳述、排除規則（意向治療分析）已陳述。通過。
4. 無引用先前文獻——跳過事後驗證。 結果： 文件已寫入。輸出摘要標記 1 個 [CLARIFY:] 項目需在提交 AEA 前填寫。

範例 3 — 自由形式描述，AsPredicted 短格式

使用者說：「預註冊我的下一個促發實驗，AsPredicted 風格」（無 --input） 操作：

1. 提示輸入 1–3 段描述。
2. 使用者提供一段描述；假設缺乏方向 → 詢問一次：「方向為何？」
3. 使用者釐清；填入 9 個 AsPredicted 欄位。
4. 樣本大小停止規則遺漏 → [CLARIFY: 目標 N 或停止規則]。 結果： 短格式已寫入；一個 MUST [CLARIFY:] 被標記；告知使用者在貼上 AsPredicted 前先填寫。

疑難排解

「描述包含結果」 — 設計如此。請將結果移至方法 + 結果的撰寫中；預註冊是前瞻性的。

引用事後驗證失敗（FAIL） — claim-verifier 無法在 WebSearch / 語料庫中找到引用的論文。可能引用是真實的但驗證器漏掉（對於非常近期 / 付費牆後的作品很常見——請提供明確的 URL），或是引用是幻覺。上傳前請手動檢查。

不同註冊平台要求不同 — 若此技能的映射過於粗略，請使用該註冊平台本身的模板。這三種風格涵蓋了約 90% 的社會科學預註冊；邊際案例（PROSPERO、ClinicalTrials.gov、ISRCTN）需要使用該註冊平台的原生表格。

輸出目錄不存在 — 新分支中應存在 quality_reports/preregistrations/.gitkeep；若缺少，技能會先在寫入前建立目錄。