# Draft Writing

> 論文草稿的撰寫、讀取、引用管理。 LOAD THIS SKILL WHEN: 寫草稿、draft、撰寫、Introduction、Methods、Results、Discussion、引用、citation、字數、patch、編輯草稿 CAPABILITIES: draft_action(action="write"|"section"|"read"|"list"|"insert_citation"|"sync_references"|"count_words"|"available_citations"|"patch")

- Skill: `u9401066/draft-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add u9401066/draft-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/u9401066/draft-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: u9401066 (https://skillmd.com/u/u9401066)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/u9401066/draft-writing

---


# 草稿撰寫技能

觸發：寫草稿、draft、section、引用、citation、字數、patch、寫作順序

## 前置條件

1. `project_action(action="current")` 確認專案
2. concept.md 存在且 🔒 區塊非空（寫 concept.md 本身除外）

---

## MCP Tools

### 撰寫

| 工具                                 | 說明                                              |
| ------------------------------------ | ------------------------------------------------- |
| `draft_action(action="write")`       | 建立/覆寫草稿（`filename`, `content`, `project`） |
| `draft_action(action="section")`     | 根據 notes 產出 section（`topic`, `notes`）       |
| `draft_action(action="read")`        | 讀取草稿                                          |
| `draft_action(action="list")`        | 列出所有草稿                                      |
| `draft_action(action="check_order")` | ⭐ 檢查寫作順序與進度（advisory, 不阻止）         |

### 引用（⚠️ 修改引用必須用 `draft_action(action="patch")`，禁止 `replace_string_in_file`）

| 工具                                         | 說明                                              |
| -------------------------------------------- | ------------------------------------------------- |
| `draft_action(action="available_citations")` | ⚠️ 編輯前必呼叫！列出可用 `[[citation_key]]`      |
| `draft_action(action="patch")`               | 部分編輯草稿，自動驗證 wikilinks                  |
| `draft_action(action="insert_citation")`     | 定點插入引用（`filename`, `target_text`, `pmid`） |
| `draft_action(action="sync_references")`     | 掃描 [[wikilinks]] 生成 References                |
| `draft_action(action="count_words")`         | 計算字數                                          |

**`draft_action(action="patch")` vs replace_string_in_file**：draft facade 會驗證引用、自動修復格式、拒絕不存在的引用。

---

## 自動快照（CONSTITUTION §22 Auditable）

所有草稿寫入路徑（透過 `draft_action(action="write"|"patch"|"insert_citation")`，以及 full-surface legacy verbs）在覆寫前**自動建立快照**，儲存於 `drafts/.snapshots/`。

- 最多保留 20 個快照/檔案，自動清理
- 不依賴 git 或 agent 合作，純粹在寫入路徑中觸發
- 使用 `DraftSnapshotManager`（`infrastructure/persistence/`）

---

## 寫作順序（Advisory）

| Paper Type        | 順序                                                                  |
| ----------------- | --------------------------------------------------------------------- |
| original-research | Methods → Results → Introduction → Discussion → Conclusion → Abstract |
| systematic-review | Methods → Results → Discussion → Introduction → Conclusion → Abstract |
| case-report       | Case Presentation → Discussion → Introduction → Conclusion → Abstract |
| review-article    | Introduction → Body → Conclusion → Abstract                           |

前置：Results 需 Methods、Discussion 需 Results+Intro、Conclusion 需 Discussion、Abstract 需全部。
`draft_action(action="check_order")` 產生警告，不阻止。警告出現時詢問用戶是否繼續。

---

## Flow A: 撰寫新 Section

1. `draft_action(action="check_order")` → 確認前置
2. `validate_for_section(section)` → ✅/❌
3. `draft_action(action="read", filename="concept.md")` → 提取 🔒 NOVELTY + 🔒 SELLING POINTS
4. 參考下方 Section 指南撰寫
5. `draft_action(action="count_words")`
6. `pipeline_action(action="approve_section", section=section, decision="approve|revise")` → 用戶審閱 approve/revise（Phase 5 時 MANDATORY）

## Flow B: Citation-Aware 編輯

1. `draft_action(action="available_citations")` → 取得可用 citation keys
2. `draft_action(action="patch", filename=..., old_text=..., new_text=...)` → 自動驗證 wikilinks
3. `draft_action(action="sync_references", filename=...)` → 生成 References

---

## 🔒 受保護內容

- Introduction 開頭/結尾必須呼應 🔒 NOVELTY
- Discussion 必須逐條強調 🔒 SELLING POINTS
- 不可刪除或弱化 🔒 區塊。修改前必須詢問用戶

---

## Section 寫作指南

> 以下每條指南都有對應的 Code-Enforced Hook（B9-B16），`run_quality_checks(action="writing_hooks")` 會自動檢查。

### Introduction (400-600 words)

**結構（Funnel Model — Hook B12 自動偵測）：**

1. **Broad Context** (1-2 段)：臨床問題的重要性與盛行率，用具體數字（發生率、死亡率）
2. **Evidence Base** (1-2 段)：目前文獻的發現，必須有 `[[wikilinks]]` 引用
3. **Knowledge Gap** (1 段)：先前研究的不足之處→ 對應 🔒 NOVELTY
4. **Study Objective** (最後一段)：「This study aimed to...」或「We sought to...」

**時態（Hook B9）：**

- 已確立的事實 → **現在式**（「Diabetes is characterized by...」）
- 先前研究的結果 → **過去式**（「Smith et al. reported that...」）

**禁止事項：**

- 🚫 "In recent years..." / "With the rapid development of..."
- 🚫 每段開頭用 "Furthermore" / "Moreover" / "Additionally"
- 🚫 在 Introduction 透露自己的 Results（Hook B12 CRITICAL）
- 🚫 過多 hedging：「may potentially suggest...」（Hook B15）

**Checklist（Agent 自行確認）：**

- [ ] 第一段有具體流行病學數字
- [ ] 有 ≥3 個引用支持 Evidence Base
- [ ] Knowledge Gap 用轉折語（however, nevertheless, yet）
- [ ] 最後一段明確陳述研究目的

---

### Methods (800-1200 words)

**結構：**

1. **Study Design & Setting**：研究類型、單/多中心、時間範圍
2. **Participants**：納入/排除標準、年齡、母群體
3. **Intervention / Exposure**：介入描述或暴露定義
4. **Outcomes**：Primary + Secondary endpoints，明確定義
5. **Statistical Analysis**：分析方法、軟體版本、顯著性標準

**時態（Hook B9 CRITICAL）：**

- 所有描述必須用**過去式**（「We enrolled...」「Data were collected...」）
- 🚫 禁止用現在式描述已完成的方法步驟

**倫理聲明（Hook B14 CRITICAL）：**

- ✅ 必須包含 IRB / Ethics committee approval + 核准編號
- ✅ 必須包含 Informed consent statement（或 waiver 說明）
- ✅ 如為介入研究：必須包含 Trial registration number (e.g., NCT12345678)

**統計報告規範（Hook B8 / B16）：**

- 必須在 Methods 中預先列出 Results 中所有用到的統計方法
- Events 應能對應到 Methods 中的 Outcomes 定義

**Checklist：**

- [ ] 研究設計一開始就聲明
- [ ] 納入排除標準明確列出
- [ ] 統計方法對應所有結果變量
- [ ] 倫理聲明 + Informed consent 存在
- [ ] 如 RCT：有 randomization 和 allocation concealment 描述

---

### Results (600-1000 words)

**結構：**

1. **Participant Flow**：篩選→納入→分析的人數（搭配 CONSORT 流程圖）
2. **Baseline Characteristics**：Table 1 描述，組間比較
3. **Primary Outcome**：主要結果 + 效果量 + 95% CI + p-value
4. **Secondary Outcomes**：次要結果分組報告
5. **Adverse Events / Safety**：如適用

**時態（Hook B9 CRITICAL）：**

- 所有結果描述必須用**過去式**（「was observed」「were significantly higher」）

**客觀性（Hook B11 CRITICAL — 最常見 Reviewer 意見）：**

- ✅ Results 只報告觀察到的資料和統計結果
- 🚫 禁止解讀性語言：「suggesting that」「indicating」「demonstrating that」
- 🚫 禁止主觀形容：「interestingly」「surprisingly」「remarkably」
- 🚫 禁止推測：「may be due to」「possibly reflects」「we believe」
- → 解讀屬於 Discussion

**統計報告（Hook B16）：**

- ✅ 報告精確 p-value（p = 0.032），不只用 p < 0.05
- 🚫 禁止 「p = 0.000」→ 應寫 p < 0.001
- ✅ 效果量（OR, HR, RR, MD, Cohen's d）必須伴隨 p-value
- ✅ 所有效果量應附帶 95% CI

**Checklist：**

- [ ] 有明確的參與者篩選數字
- [ ] Primary outcome 有 effect size + 95% CI + p-value
- [ ] 無解讀性語言（B11 PASS）
- [ ] 全部用過去式
- [ ] 圖表有正文敘述對應

---

### Discussion (1000-1500 words)

**結構（Hook B13 自動偵測）：**

1. **Main Findings** (第 1 段)：重述主要發現（含 🔒 SELLING POINTS）
2. **Literature Comparison** (2-3 段)：與先前研究比較，有 `[[wikilinks]]` ≥3 個
3. **Mechanism / Explanation** (1 段)：可能機制或臨床解釋
4. **Clinical Implications** (1 段)：臨床實踐意義或未來方向
5. **Limitations** (1 段，Hook B13 CRITICAL)：誠實承認研究局限
6. **Conclusion** (最後 1-2 句)：簡潔重述核心發現

**Limitations 段落（必要 — Hook B13 觸發 CRITICAL）：**

- ✅ 必須包含 "limitation" / "weakness" / "shortcoming"
- ✅ 至少提 2-3 個具體限制：研究設計、樣本量、追蹤時間、選擇偏差等
- ✅ 對每個限制解釋為什麼不影響主要結論（或承認可能影響方向）

**Hedging 控制（Hook B15）：**

- Discussion 可以適度使用 hedging（may, might, could）
- 但密度超過 6/1000 字 → CRITICAL（文稿顯得不確定）
- 目標：3/1000 字以下

**禁止事項：**

- 🚫 重複引用 Introduction 已提過的背景知識
- 🚫 在 Discussion 引入新數據（屬於 Results）
- 🚫 過度擴大結論到研究設計無法支持的範圍

**Checklist：**

- [ ] 第一段重述 main findings
- [ ] 有 ≥3 個與先前文獻的比較引用
- [ ] Limitations 段落存在且具體
- [ ] 有 clinical implications 或 future directions
- [ ] 結論簡潔、不超出數據支持範圍

---

### Abstract (250-350 words)

**結構（Structured）：**

1. **Background** (2-3 句)：問題 + gap + 目的
2. **Methods** (3-4 句)：設計、受試者、主要測量
3. **Results** (3-5 句)：主要結果 + 關鍵數字 + p-values
4. **Conclusions** (1-2 句)：核心發現 + 意義

**規則：**

- ✅ Abstract 是獨立的微型論文，不依賴正文即可理解
- ✅ Abstract 中的數字必須與 Results 完全一致
- 🚫 不在 Abstract 中引用文獻
- 🚫 不使用未定義的縮寫（Abstract 中的縮寫要重新定義）

---

## Code-Enforced Writing Hooks 對照表

| Hook | 名稱                 | 觸發時機     | 嚴重度        | 檢查重點                             |
| ---- | -------------------- | ------------ | ------------- | ------------------------------------ |
| B9   | Section Tense        | POST-WRITE   | CRITICAL/WARN | Methods/Results 過去式               |
| B10  | Paragraph Quality    | POST-WRITE   | WARN/INFO     | 段落長度、單句段落                   |
| B11  | Results Objectivity  | POST-SECTION | CRITICAL      | Results 禁止解讀性語言               |
| B12  | Intro Funnel         | POST-SECTION | CRITICAL/WARN | Introduction 漏斗結構 + 禁止透露結果 |
| B13  | Discussion Structure | POST-SECTION | CRITICAL      | Limitations 必須存在                 |
| B14  | Ethical Statements   | POST-SECTION | CRITICAL      | IRB + Consent + Trial Reg            |
| B15  | Hedging Density      | POST-WRITE   | CRITICAL/WARN | may/might/could 密度                 |
| B16  | Effect Size          | POST-SECTION | CRITICAL/WARN | p-value 格式 + 效果量 + CI           |

使用方式：`run_quality_checks(action="writing_hooks", hooks="B9,B11,B13")` 或 `run_quality_checks(action="writing_hooks", hooks="post-section")`

---

## Wikilink 格式

✅ `[[author2024_12345678]]` → 自動修復 `[[12345678]]` → `[[author2024_12345678]]`