diff --git a/docs/conventions.md b/docs/conventions.md index f912008..54c7809 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -1,78 +1,66 @@ -# Project Conventions +# 常設工作規範 -The standing working rules of this project. Formerly the -project `CLAUDE.md`; moved here so that Claude Code subagents -do not inherit it into their context (blind-reading agents -must not see it). A main session working on this project -reads this file before touching the pipeline, the data, or -the documents. +本專案的常設工作規範。原專案 `CLAUDE.md`；移置於此， +使 Claude Code subagent 不將其繼承入 context（盲判型 +agent 不得見之）。凡於本專案工作的主會話，動手管線、 +資料或文件之前，先讀本檔。 -## Analysis pipeline +## 分析管線 -The pipeline has run to completion; these conventions govern -any rerun or extension. +管線已跑畢；本規範適用於任何重跑或擴充。 -- LLM analysis runs via Python scripts calling the Anthropic - Messages API, Batch API where possible. Steps 1 and 3 run - on `claude-sonnet-4-6` with `temperature=0` and thinking - disabled; steps 4 and 5 run on `claude-fable-5`, which - accepts neither parameter -- step 4 absorbs its sampling - variance by the majority vote, step 5 by consolidating the - three readings. -- Prompt definition files live in - `prompts/-.md` (e.g. 1-tag.md, - 5a-read.md; substeps are lettered, matching the step - numbering of the paper; no version suffix -- versions live - in git history) and are passed verbatim as the system - prompt. The number names a step of the research - procedure, not the file: the deterministic vocabulary step - (step 2) has no definition file yet holds its own number. -- Itemwise LLM judgments (per-song coding in step 3, - per-keyword group selection in step 4) run the same - definition file three times, independently, over the same - input; a deterministic tally then assigns an item (a - (song, keyword) or (group, keyword) pair) when at least - two of the three runs assign it ("3 runs + majority - vote"). Free-generation steps run - twice and both outputs are pooled. The step-5 qualitative - readings are neither: three independent readings per song, - consolidated per song and synthesized across songs by - their own definition files -- a qualitative protocol, not - a vote (see docs/methodology.md). The vocabulary is - built by a deterministic subcommand (embedding + - clustering), not by an LLM. If a validation outcome is - unexpected, revise the definition file and repeat that - cycle; never patch results by hand. -- Each run of a step is archived self-contained under the - destination directory given explicitly on the `run-llm` - command line (by convention `runs//run/`): - prompt snapshot, raw output, and `meta.json` (model ID, - parameters, timestamps, batch ID). The runs of a step are - that many separate invocations of `run-llm`. Replacing - an existing run archive requires an explicit flag; - superseded runs live in git history. Deterministic steps - archive under `runs//` with no `run` level. -- Token usage and cost of every `run-llm` execution are - recorded in `docs/run-costs.md` in the same commit as the - run archive. -- Scripts read the API key from the `ANTHROPIC_API_KEY` - environment variable (`.env`, gitignored). +- LLM 分析以 Python 腳本呼叫 Anthropic Messages API + 執行，能用 Batch API 處即用之。步驟 1 與步驟 3 以 + `claude-sonnet-4-6` 執行，`temperature=0`、thinking + 停用；步驟 4 與步驟 5 以 `claude-fable-5` 執行，該 + 模型兩個參數皆不受理——步驟 4 的取樣變異由多數決 + 吸收，步驟 5 由整合三份閱讀吸收。 +- 定義檔置於 `prompts/<步><次步>-.md`（如 + 1-tag.md、5a-read.md；次步以字母標示，與論文正文的 + 步驟編號一致；不帶版本號——版本即 git 歷史），逐字 + 作為 system prompt。 +- 逐項的 LLM 判斷（步驟 3 的逐首編碼、步驟 4 的逐碼 + 入群判斷）以同一份定義檔、同一份輸入獨立執行三次； + 再由確定性計票將三次執行中至少兩次指派的項目（一個 + （歌，關鍵字）或（群，關鍵字）配對）收入定案 + （「三次執行＋多數決」）。自由生成步驟執行兩次， + 兩份輸出進池。步驟 5 的質性閱讀兩者皆非：逐首三次 + 獨立閱讀，由各自的定義檔逐首整合、跨首統整——質性 + 協定，不是投票（見 docs/methodology.md）。詞彙表由 + 確定性子命令建構（嵌入＋分群），不經 LLM。驗證結果 + 不符預期時，修訂定義檔並重複該循環；絕不手改結果。 +- 一步的每次執行皆自我完備歸檔於 `run-llm` 命令列上 + 明示指定的目的目錄下（慣例為 + `runs/<步驟>/run/`）：定義檔快照、原始輸出與 + `meta.json`（model ID、參數、時間戳、batch ID）。 + 一步的 N 次執行即 N 次各自的 `run-llm` 呼叫。覆蓋 + 既有執行歸檔須明示旗標；被取代的執行留在 git 歷史。 + 確定性步驟歸檔於 `runs/<步驟>/`，不分 `run` 層。 +- 每次 `run-llm` 執行的 token 用量與費用記入 + `docs/run-costs.md`，與執行歸檔同一 commit。 +- 腳本自環境變數 `ANTHROPIC_API_KEY` 讀取 API key + （`.env`，gitignored）。 -## Data rules +## 資料規則 -- `data/source/` holds the immutable hand-placed raw files; - `data/captures/` is written only by the fetch commands and the - private import script; `data/manual/` is written only by the - user's own hand; `data/derived/` is written only by the - `build-db` subcommand. -- Full lyrics are copyrighted: they stay in `data/captures/lyrics/` - (gitignored) and must never be committed or reproduced in - full anywhere in the repo. +- `data/source/` 存手放後不動的原始檔； + `data/captures/` 只由 fetch 命令與私人匯入腳本 + 寫入；`data/manual/` 只由研究者親手寫入； + `data/derived/` 只由 `build-db` 子命令寫入。 +- 歌詞全文有版權：一律置於 `data/captures/lyrics/` + （gitignored），絕不 commit，亦絕不於 repo 任何處 + 全文重現。 -## Documents +## 文件 -- `results/` holds the final tallied tables (what the paper - cites); `runs/` holds raw audit records. The paper cites - `results/` only. -- Any change to a definition file or the plan is recorded in - `docs/decision-log.md` with date and reason. +- `results/` 存計票後的定案表（論文所引）；`runs/` 存 + 原始稽核紀錄。論文只引 `results/`。 +- **Commit 判準**：凡能由「committed 的輸入＋committed + 的程式」決定性再生者不 commit；凡不能者一律以文字 + 格式 commit，格式跟著上文「資料規則」一節所定的 + 層次走。例外：`results/` 定案表與 + `data/derived/` 人讀報表雖可再生仍 commit——理由是 + 引用穩定性、審稿人零門檻、撰稿期數字變動可 diff； + 兩者皆與工作儲存同一動作產出，稽核鏈無中間空缺。 +- 凡定義檔或研究規劃之更動，皆記入 + `docs/decision-log.md`，註明日期與原因。 diff --git a/docs/methodology.md b/docs/methodology.md index 5260be4..440d78f 100644 --- a/docs/methodology.md +++ b/docs/methodology.md @@ -1,12 +1,12 @@ # 方法細節 （全文方法節底稿。演算法在執行前寫定；任何修訂記入 -`decision-log.md`。定義檔全文見 `prompts/`，執行紀錄見 -`runs/`。） +`decision-log.md`。） ## 自然編碼管線總覽 -五個步驟：步驟 1 自由標註（兩次執行進池）→ 步驟 2 詞彙表 +五個步驟：步驟 1 自由標註（`claude-sonnet-4-6`， +temperature=0、thinking 關閉，兩次執行進池）→ 步驟 2 詞彙表 建構（詞向量分群，確定性）→ 步驟 3 全量編碼（三次執行＋ 多數決）→ 步驟 4 語意編碼群（三次執行＋多數決）→ 步驟 5 女性主義問題之質性深讀（三次閱讀＋逐首整合＋樣態統整）。 @@ -14,13 +14,6 @@ 不接觸歌詞，步驟 2 亦不呼叫 LLM。設計原則見 `research-plan.md`；本檔記載可重現的演算法細節。 -編號的所指為**研究程序的工序**，不是定義檔：步驟 1、 -步驟 3、步驟 4 與步驟 5 有定義檔（`prompts/`；步驟 5 依 -子工序有三份），步驟 2 沒有——它是單一確定性計算，由 -`cluster-keywords` 一個子命令完成。有無定義檔的區別即 -「該步是否為 LLM 判斷」，由 `prompts/` 是否存在同號檔案 -直接可見。 - ## 步驟 2 詞彙表建構——詞向量分群 詞彙表由確定性程序產生，不經 LLM。完整分割（每個關鍵字 @@ -30,8 +23,7 @@ ### 進池 兩次標註執行的全部關鍵字取聯集、逐字串精確去重、字典序 -排列。失敗與拒答的記錄跳過（其歌曲不貢獻關鍵字）；解析 -時偵測重複鍵，違規即失敗。 +排列。失敗與拒答的記錄跳過（其歌曲不貢獻關鍵字）。 ### 分群 @@ -39,14 +31,10 @@ （釘定 revision），關鍵字的連字號先還原為空格再編碼， 輸出 768 維向量並 L2 正規化。 - **分群**：階層式聚合分群（Ward linkage），k=100。 - 向量既已正規化，歐氏距離與餘弦相似度單調對應；三種 - linkage 實測比較，Ward 於各個 k 的組內一致性均最高 - （average 與 complete 皆產生吞噬半數語料的巨大異質 - 組）。 + 向量既已正規化，歐氏距離與餘弦相似度單調對應。 - **組數的取捨**：k 太小則壓縮比過高，樹上層被迫併入 - 不相干的詞，組雖大而無主題（k=30 最大組 491 詞、 - 組內一致性 0.41，成員橫跨籃球、海灘、外星人綁架）； - k 太大則人工難以通覽。定於 100，理由是實測顯示雜物櫃 + 不相干的詞，組雖大而無主題；k 太大則人工難以通覽。 + 定於 100，理由是實測顯示雜物櫃 組於此始裂解為有主題的組，且編碼實測未見碼數過多的 副作用——全量三次執行下 101 個碼全數用到；模型另行 造出的碼共 13 筆，佔 44,149 筆標籤指派的 0.03%。 @@ -55,39 +43,23 @@ 自己產出過的關鍵字，非任何人事後撰寫。已知限制： 組越大越異質時，medoid 只是折衷詞，可能代表不了組內 內容（實測 `mutual-individuality` 組內一致 0.70 而 - 編碼從未使用）；此類碼於結果中呈現為零使用，據實 - 報告，不事後改名。 -- **取捨紀錄**：曾以 LLM 單發收斂（merge／cap 兩步） - 實作本步，四種模型六次執行全部無法維持完整分割， - 已棄用（詳見 `decision-log.md` 2026-08-05；棄用的 - 定義檔止於 git 歷史，見 `git log -- prompts/`）。 -- **產物**：五份，前綴分別標示來源與結果。 - `source-keywords.txt`（進池後的關鍵字，一行一個） - 記錄進來的是什麼；`result-keywords.txt`（組名，一行 - 一個）與 `groups.csv`（欄位 Group、Keyword，一列一個 - 成員）記錄算出來的分割；`keywords-to-merge.json` - （`{"keywords": [...]}`）是實際交給模型的碼，即組名 - 加上先驗主題詞——五份中只有這一份含研究者的介入。 - `meta.json` 記錄執行本身：進池的兩份執行歸檔與其有效 - 筆數、嵌入模型與釘定 revision、分群參數與組數、外加 - 的先驗詞、關鍵字總數，以及產生數字的套件版本。凡命令 - 列上的選擇與環境事實皆在此，不記時間戳與輸入雜湊 - ——前者使同環境重跑逐位元組可再生，後者只會重述 git - 已保證的事。 + 編碼從未使用）；此類碼於結果中呈現為零使用。 +- **取捨紀錄**：詞彙表分群曾比較的替代法與棄用理由，見 + `decision-log.md` 2026-08-05 條。 +- **產物**：分群輸出中，只有實際交給模型的碼表——組名 + 加上先驗主題詞——含研究者的介入；其餘皆為分群過程本身 + 的機械紀錄。 - **可重現性**：同一輸入、同一釘定模型、同一參數逐次 重現。不同 CPU／BLAS 實作的浮點尾數差異可能使邊界 - 詞的歸屬翻動，屬已揭露的限制；論文所用碼表逐字 - commit，引用單位為該份定案檔案。 + 詞的歸屬翻動，屬已揭露的限制。 ### women-power 的注入 定案詞彙表為 100 個分群組名再加上 `women-power` 一詞， 共 101 個碼。`women-power` 是研究者任意決定的先驗主題（即本 論文的主題本身），不由資料產生，屬揭露的儀器介入。該詞 -於執行時以 `--extra-keyword` 明示加入，不寫死在程式裏 -——研究者的介入因此每次都出現在重現命令上，而非無聲 -發生；分群結果的兩份產物不含它，只有交給模型的碼表含 -它。 +的加入於每次執行皆為明示、可稽核的介入，而非無聲內建於 +判斷邏輯；分群結果本身不含它，只有交給模型的碼表含它。 注入而非另設篩選軌的理由：讓研究者的主題詞與模型自己 收斂出的類別（分群已自行長出 `female-empowerment` 等組） @@ -97,24 +69,17 @@ ## 步驟 3 編碼的三次執行與多數決 +- **模型**：`claude-sonnet-4-6`，temperature=0、thinking 關閉。 - **三次執行**：同一份定義檔、同一份輸入檔，獨立執行 - 三次，三份歸檔並列（`runs/3a-code/run1`、`run2`、 - `run3`），彼此無先後主從之別。 + 三次，三份歸檔並列，彼此無先後主從之別。 - **多數決**：一首歌的一個標籤，三次執行中至少兩次標出 即收入定案編碼。三票不平手，裁決規則因此無例外條款， - 計票由確定性子命令完成（見交接契約）。 -- **第三票取全量**：只對前兩次分歧的標籤補問第三票， - 計票結果相同；仍採全量執行——全部歌曲、全部關鍵字 - ——使三票在同一條件下取得。 + 計票由確定性程序完成（見交接契約）。 +- **第三票取全量**：第三次執行同為全量——全部歌曲、 + 全部關鍵字——使三票在同一條件下取得。 - **對邊緣標籤的作用**：兩次執行只分得出「兩次皆標」與 「僅一次標」；三次執行還分得出 3-0 與 2-1，故「定案 編碼中有多少比例僅以一票之差成立」成為可報告的量。 - 至於判定本身，兩次執行相左的標籤在何種協定下都由第三 - 個判斷定奪，票數不使不確定性消失：某標籤於單次執行被 - 標出的傾向若恰為一半，任何票數皆為擲幣。三票之效在 - 傾向偏離一半處——多數決將判定推向該傾向本身（單次 - 0.7 者為 0.78，0.9 者為 0.97），程序重跑的一致性因而 - 高於單次執行，唯獨恰半處無從改善。 ## 步驟 4 語意編碼群 @@ -125,103 +90,79 @@ 由 LLM 依編碼名的字面語意判斷。 - **任務**：每筆輸入為一個群名加 101 個編碼的字母序 清單，輸出為入選編碼的單層 JSON 陣列；定義檔 - `prompts/4-group.md` 只定格式，不含任何群的語意定義。 -- **模型**：`claude-fable-5`（步驟 1、3 為 - `claude-sonnet-4-6`）。該模型不受理 `temperature` 與 - `thinking` 參數，兩者均不送出；取樣變異由多數決吸收。 + 只定格式，不含任何群的語意定義。 +- **模型**：`claude-fable-5`；取樣變異由多數決吸收； 模型裁定的理由與對照實驗見決策日誌。 - **三次執行**：同一份定義檔、同一份輸入檔，獨立執行 - 三次，歸檔並列（`runs/4-group/run1`、`run2`、`run3`）。 + 三次，歸檔並列。 - **多數決**：一個（群，編碼）配對，三次執行中至少兩次 - 入選即屬該群；不在 101 碼詞彙表內的輸出項無效，每筆 - 丟棄印於標準錯誤。計票由確定性子命令 `tally-groups` - 完成：`tally-groups <執行歸檔 1> <執行歸檔 2> <執行歸檔 - 3> <合法碼清單> <輸出 CSV>`，合法碼清單之產法同步驟 3。 - 定案分群寫入 `results/groups.csv`，欄位 `Group`、 - `Keyword`、`Votes`，列序先依群名、再依編碼，一律以 - Unicode 碼位比較，換行為 CRLF。 -- **工作儲存**：`build-db --groups <定案分群 CSV>` 將定案 - 分群逐欄照存入 `groups` 資料表（群、編碼、票數），供 - 群層次查詢。 + 入選即屬該群；不在 101 碼詞彙表內的輸出項無效，逐筆 + 記錄後丟棄。計票由確定性計票程序完成，合法碼 + 清單之產法同步驟 3，結果為定案分群表。 ## 步驟 5 女性主義問題之質性深讀 -本步驟之 5a 至 5c 為**質性閱讀,非編碼**:輸出為自由 -文字的問題閱讀報告,無可逐項機械比對的單位,故不適用 -三票多數決與仲裁; -三次獨立閱讀為分析者三角檢核,逐首整合為整合而非裁決, -跨首統整之產出為草稿,終審與詮釋由研究者為之。論文引用 +本步驟之 5a 至 5c 為**質性閱讀，非編碼**：輸出為自由 +文字的問題閱讀報告，無可逐項機械比對的單位，故不適用 +三票多數決與仲裁； +三次獨立閱讀為分析者三角檢核，逐首整合為整合而非裁決， +跨首統整之產出為草稿，終審與詮釋由研究者為之。論文引用 本步驟時不作次數宣稱。 -- **對象**:定案編碼含 `women-power` 或 +- **對象**：定案編碼含 `women-power` 或 `female-empowerment` 的 145 首歌。 -- **5a 逐首閱讀**:每筆輸入為一首歌的完整歌詞逐字全文, - 不含歌名與演唱者(盲讀);定義檔 - `prompts/5a-read.md`。同一份定義檔、同一份輸入檔, - 獨立執行三次,歸檔並列(`runs/5a-read/run1`、 - `run2`、`run3`)。 -- **5b 逐首整合**:每筆輸入為該首歌的三份閱讀報告 - (不含歌詞);以問題機制為單位保守合併,標收斂註記 - ((3/3)、(2/3)),主清單僅列兩讀以上提出者,單讀發現 - 以一行存目;定義檔 `prompts/5b-consolidate.md`, - 執行一次,歸檔 `runs/5b-consolidate/run1`。 -- **5c 樣態統整**:單筆輸入為一批整合報告;歸納問題 - **樣態**——問題呈現與運作的重複形態,非問題分類, - 代表引句僅取自主清單;定義檔 - `prompts/5c-synthesize.md`。四種輸入範圍各執行 - 一次:全 145 首之基底統整(歸檔 - `runs/5c-synthesize/run1`),及依 `performer_gender` - (演唱聲音之性別)切分之三個發話脈絡統整——男聲 - (male,歸檔 `run2`)、女聲(female,歸檔 `run3`)、 - 混合(mixed,歸檔 `run4`);基底看橫貫各脈絡之樣態, - 分組看各權力脈絡下之樣態。genderfluid 與 non-binary - 共 3 首不設群——樣本數不支持歸納——僅入基底統整, - 由研究者以個案閱讀。同一輸入不重複執行:自由歸納之 - 產出無機械合併可言,其變異由 5a 三讀、5b 整合與 - 草稿地位承接,四份草稿互為對照,由研究者終審裁決。 -- **5d 樣態標註**:以 (歌, 樣態) 對為可逐項機械比對之 - 單位,回歸「三次執行＋多數決」協定。對象為「有問題」 - 的歌——三讀中至多一個「無」(多數決精神;恰兩「無」 - 者其整合報告主清單必為空,與 5b 主清單規則自洽), - 計 111 首(男聲 12、女聲 69、混合 29、genderfluid 1)。 - 樣態表為三份分組統整草稿原文:男聲 13 條(M1–M13)、 - 女聲 14 條(F1–F14)、混合 16 條(X1–X16);基底 15 條 +- **5a 逐首閱讀**：每筆輸入為一首歌的完整歌詞逐字全文， + 不含歌名與演唱者（盲讀）。同一份定義檔、同一份輸入檔， + 獨立執行三次，歸檔並列。 +- **5b 逐首整合**：每筆輸入為該首歌的三份閱讀報告 + （不含歌詞）；以問題機制為單位保守合併，標收斂註記 + （（3/3）、（2/3）），主清單僅列兩讀以上提出者，單讀發現 + 以一行存目；定義檔，執行一次。 +- **5c 樣態統整**：單筆輸入為一批整合報告；歸納問題 + **樣態**——問題呈現與運作的重複形態，非問題分類， + 代表引句僅取自主清單。四種輸入範圍各執行 + 一次：全 145 首之基底統整，及依演唱聲音之性別切分 + 之三個發話脈絡統整——男聲（male）、女聲（female）、 + 混合（mixed）；基底看橫貫各 + 脈絡之樣態，分組看各權力脈絡下之樣態。genderfluid + 與 non-binary 共 3 首不設群——樣本數不支持歸納—— + 僅入基底統整。同一輸入不重複 + 執行：自由歸納之產出無機械合併可言，其變異由 5a + 三讀、5b 整合與草稿地位承接，四份草稿互為對照，由 + 研究者終審裁決。 +- **5d 樣態標註**：以（歌，樣態）對為可逐項機械比對之 + 單位，回歸「三次執行＋多數決」協定。對象為「有問題」 + 的歌——三讀中至多一個「無」（多數決精神；恰兩「無」 + 者其整合報告主清單必為空，與 5b 主清單規則自洽）， + 計 111 首（男聲 12、女聲 69、混合 29、genderfluid 1）。 + 樣態表為三份分組統整草稿原文：男聲 13 條（M1–M13）、 + 女聲 14 條（F1–F14）、混合 16 條（X1–X16）；基底 15 條 不入矩陣——全體歸納之一條樣態可能疊合不同方向的 - 權力關係(男對女、女對男),實為多個樣態共用一名。 - 檢驗範圍:男聲樣態不檢驗純女聲歌、女聲樣態不檢驗 - 純男聲歌(發話位置範疇錯置,檢查無意義);混合樣態 - 檢驗全部(其男女聲部無系統化切分方式,無意義之標註 - 容忍之);genderfluid 歌三套全查(無自身透鏡,發話 - 位置無法先驗決定),其歸屬引用維持個案地位。每筆 - 輸入為一首歌之整合報告(「僅單獨提及」行於組裝時 - 剝除,標註僅依主清單)與該首適用之樣態表;定義檔 - `prompts/5d-annotate.md`,獨立執行三次 - (`runs/5d-annotate/run1`~`run3`),(歌, 樣態) 對 + 權力關係（男對女、女對男），實為多個樣態共用一名。 + 檢驗範圍：男聲樣態不檢驗純女聲歌、女聲樣態不檢驗 + 純男聲歌（發話位置範疇錯置，檢查無意義）；混合樣態 + 檢驗全部（其男女聲部無系統化切分方式，無意義之標註 + 容忍之）；genderfluid 歌三套全查（無自身透鏡，發話 + 位置無法先驗決定），其歸屬引用維持個案地位。每筆 + 輸入為一首歌之整合報告（「僅單獨提及」行於組裝時 + 剝除，標註僅依主清單）與該首適用之樣態表；定義檔 + 獨立執行三次，（歌，樣態）對 得兩票以上者定案。 -- **模型**:`claude-fable-5`(與先導深讀同儀器; - `temperature` 與 `thinking` 參數不適用,均不送出)。 -- **輸入組裝**:確定性行內腳本。5a:145 首依歌曲 ID - 升序,`content` 為歌詞逐字全文;5b:每筆 - `{"reports": [run1 輸出, run2 輸出, run3 輸出]}`; - 5c:單筆以 `song-` 為鍵、整合報告為值之 JSON - 物件,鍵集合為該次統整之範圍(基底為全 145 首, - 分組依工作庫 `performer_gender` 切分);5d:每筆 - `{"report": 主清單, "patterns": [{"id", "name", - "description"}]}`,樣態條目自分組統整草稿機械切出, - 代表引句不隨附——引句出自特定歌曲,判該曲時形同 - 預答。各輸入檔之 SHA-256 記入該步 meta。 +- **模型**：`claude-fable-5`。 +- **輸入組裝**：各步輸入檔由確定性程序自上游產物組裝。 + 5d 之樣態條目自分組統整草稿機械切出，代表引句不 + 隨附——引句出自特定歌曲，判該曲時形同預答。 ## 女性力量候選集 -候選集為兩類歌曲的合集：定案編碼含 `women-power` 者， -以及定案編碼含研究者指認之女性力量概念域分群組者。 -指認於詞彙表定案後、黃金標準編碼開始前完成，指認清單 -與理由記入決策日誌。 +候選集為定案編碼含 `women-power` 或 `female-empowerment` +（步驟 4 女性力量群的兩個編碼）之歌曲聯集：wp 66 首、 +fe 144 首，聯集 145 首。 ## 軌跡對映（診斷用） 沿收斂軌跡的機械對映：原始關鍵字 →（兩份標註執行歸檔的 -`output.jsonl`）歌曲、原始關鍵字 →（分群）組，純程式查表， +原始輸出）歌曲、原始關鍵字 →（分群）組，純機械查表， 決定性。以其結果與步驟 3 直接編碼的差異率作為「收斂軌跡 扭曲」的診斷量，不作主結果。 @@ -230,78 +171,36 @@ 每一步的輸出如何變成下一步的輸入，皆為確定性程序，規則 明定如下： -- **歌詞輸入檔（步驟 1）**：`export-llm-input` 自工作 - 儲存產出，每筆 `{"id": "song-", "content": <歌詞>}`， - 依歌曲 ID 升序。步驟 3 的輸入由同一子命令、同一工作 - 儲存產出（見下），兩步的語料同一性由此成立；各步 - 輸入檔的 SHA-256 記入該步 meta。 -- **步驟 1 → 2**：`cluster-keywords` 讀兩份執行歸檔的 - `output.jsonl`（一律以換行字元 `\n` 切行——歌詞含 - U+0085 等控制字元時，`str.splitlines()` 類的通用切行 - 會截斷 JSON 字串，實測踩中），進池後直接分群，一次 - 產出上列五份檔案。 -- **步驟 2 → 3 輸入檔**：`export-llm-input --extras - <定案碼表>` 自工作儲存產出步驟 3 的輸入，每筆 - `{"id": "song-", "content": <字串>}`，`content` 為 - 固定鍵序序列化的 `{"lyrics": …, "keywords": [...]}`， - 依歌曲 ID 升序。碼表以參數傳入而非填進定義檔——定義 +- **歌詞輸入檔（步驟 1）**：由確定性的匯出程序自工作 + 儲存產出，一筆一首歌，依歌曲 ID 升序。步驟 3 的輸入 + 由同一匯出程序、同一工作儲存產出（見下），兩步的語料 + 同一性由此成立。 +- **步驟 1 → 2**：確定性的分群程序讀兩份執行歸檔的 + 執行紀錄，進池後直接分群，產出詞彙表與交給 + 模型的碼表。 +- **步驟 2 → 3 輸入檔**：同一匯出程序自工作儲存產出 + 步驟 3 的輸入，一筆一首歌，兼含歌詞與定案碼表，依 + 歌曲 ID 升序。碼表以參數傳入而非填進定義檔——定義 檔只規定任務形狀，換詞彙表、換演算法都不必改它。 -- **步驟 3 定案**：`tally-codings <執行歸檔 1> <執行歸檔 - 2> <執行歸檔 3> <輸出 CSV> --corrections <更正表> - --valid-keywords <合法碼清單>` 讀三份執行歸檔的 - `output.jsonl`，依序套用更正表、驗證所有標籤皆在合法碼 +- **步驟 3 定案**：確定性的計票程序讀三份執行歸檔的 + 執行紀錄，依序套用更正表、驗證所有標籤皆在合法碼 清單之內、計票。 -- **更正表**：`data/manual/coding-corrections.csv`，研究者 - 逐列校定的人工著作，欄位 `Song ID`、`Run`、`Type`、 - `To Be Replaced`、`Correct Term`。`Type` 為 `keyword` - 或 `evidence`，分別更正標籤與引述；`Correct Term` 為 - 替代字串，或 `**REMOVE**` 表示刪去該筆標籤指派（`keyword`） - 或該句引述（`evidence`）。一筆 `evidence` 更正套用於該 - 首歌該次執行的所有出現處。兩個文字欄以歌詞慣例「 / 」 - 表示換行（與載入後的執行紀錄同一表示法，逐字比對、不再 - 轉換），故一列一行，純文字工具可逐列處理。表中任一列若 - 在資料中找不到對應者，即中止；校定的判準記於 - `decision-log.md`。 -- **合法碼清單**：純文字、一行一個碼，自詞彙表產出： - `{ cat runs/2-cluster/result-keywords.txt; echo - women-power; } | sort`。 -- **定案表**：`results/codings.csv`，欄位 `Song`、 - `Artist Credit`、`Keyword`、`Quote`，一列一個標籤。歌名 - 與演出者名銜逐首查工作儲存取得，故本子命令須在 - `build-db` 之後執行。`Quote` 為該標籤在計票中各份執行 - 所引的歌詞行：各份的引述串接後逐字去重，按 Unicode - 碼位排序，以單一 `|` 相接（三份執行彼此無先後主從之 - 別，引述之序取決於引述本身）；引述內的換行於執行紀錄 - 載入時一次換成歌詞慣例「 / 」，此後更正表、定案表與 - 工作儲存全鏈路同一表示法，不再還原。「 / 」的無歧義性 - 是語料事實而非結構保證：全 883 首歌詞經窮舉查核不含 - 「 / 」；換語料須重查。列序依印出的前三欄依序排： - 歌名、演出者名銜、 - 標籤，一律以 Unicode 碼位比較，換行為 CRLF（同專案 - 其他 CSV）。 -- **序列化通則**：所有中間檔為 UTF-8，欄序、鍵序與元素 - 序皆依上列規則明定，無時間戳、無隨機成分；JSON 解析 - 一律偵測重複鍵，違規即失敗。人讀為主的產物採純文字或 - CSV（CSV 依 RFC 4180，標題列字首大寫），機器交接檔採 - JSON。給定相同的 LLM 執行輸出，全部交接產物逐位元組 - 可再生。 +- **更正表**：研究者逐列校定的人工著作，逐筆更正標籤 + 或引述——以替代字串取代，或刪去該筆標籤指派或該句 + 引述。一筆引述更正套用於該首歌該次執行的所有出現處。 + 表中任一列若在資料中找不到對應者，即中止；校定的 + 判準記於 `decision-log.md`。 +- **合法碼清單**：自詞彙表產出：分群組名加上 + `women-power`。 +- **定案編碼表**：歌名與演出者名銜逐首查工作儲存取得。 + 每個定案標籤隨附其在計票中各份執行所引的 + 歌詞行，供逐碼查核（三份執行彼此無先後主從之別）。 ## 執行與稽核 -- LLM 步驟以 `run-llm <定義檔> <輸入檔> <歸檔目錄>` - 執行；一步的 N 次執行＝重現命令清單上的 N 行命令， - 各自歸檔（`runs/<步驟>/run1`、`run2`，三票制步驟另有 - `run3`）。 -- 確定性步驟（進池、分群、計票、對映）為子命令，其 - 輸入輸出檔同隨 `runs/` 歸檔；因無執行變異，歸檔目錄 - 下不分 `run` 層。 +- LLM 步驟以批次執行程序執行，一份定義檔配一份 + 輸入檔；一步的 N 次執行為 N 次各自獨立的呼叫，各自 + 歸檔自我完備。 - Batch API 的每筆請求自含全部脈絡且互不可見（平台 契約），歌與歌之間的獨立性由此成立；各次執行的獨立 性由「一次呼叫、一個批次、一份歸檔」的執行結構自明。 -- 每次 `run-llm` 執行的 token 用量與費用記入 - `run-costs.md`，被取代的執行一併保留供總支出核算。 - -## 映射分析方法 - -（依 2026-07-30 決策，於看到結果前寫定；待黃金標準 -編碼展開前補入。） diff --git a/docs/output-validation.md b/docs/output-validation.md index 687e705..d662953 100644 --- a/docs/output-validation.md +++ b/docs/output-validation.md @@ -46,9 +46,8 @@ song-750 run3: -use=[] -abuse=["I got a thing for the hard liquor on ice"] ``` -模型寫錯後綴、已輸出的 token 收不回，遂以空陣列收束該鍵， -再於正確的鍵補上引述。song-750 的 run1 與 run2 則整筆使用 -錯拼的鍵並附上引述，故該首的三票分裂於兩種拼寫之間。 +song-750 的 run1 與 run2 則整筆使用錯拼的鍵並附上引述， +故該首的三票分裂於兩種拼寫之間。 ## 引述的存在 diff --git a/docs/pilot-study.md b/docs/pilot-study.md index b389933..1ab3c7c 100644 --- a/docs/pilot-study.md +++ b/docs/pilot-study.md @@ -2,15 +2,14 @@ （2026-08-17 認清並記錄。本檔記述正式研究之前的先導研究: 它做了什麼、研究者檢視到哪一層、哪些成果被沿用、哪些被 -棄用,以及它如何促成正式研究的設計。散見於 -`decision-log.md` 的相關條目在文中逐一指出。） +棄用,以及它如何促成正式研究的設計。） ## 一、先導研究是什麼 正式研究之前,研究者曾以 Claude Code 對 Billboard Year-End Hot 100(2018–2025、684 首)的歌詞做過一輪探索性分析,檢視 「女性力量」語彙的使用狀況,並附帶分析 pussy 一詞作為女性 -代稱的修辭。2026 年 8 月投出的研討會摘要即根據該輪分析撰寫。 +代稱的修辭。2026 年 4 月投出的研討會摘要即根據該輪分析撰寫。 ## 二、它實際的執行方式 @@ -37,25 +36,22 @@ frame-aware 提示修正實驗,均由當時協作的 Claude Code 設計並 - **歌詞捕捉檔**:先導研究蒐集的 lyrics.json(684 首, 2018–2025)以私人腳本(不入版本庫)匯入歌詞快取,只取 識別欄位與歌詞本文,先導的分析欄位一概不匯入;出處記於 - `data/captures/lyrics-provenance.csv`,method 欄標 - `pilot-import`(見 `decision-log.md` 2026-07-31、08-02 條)。 + `data/captures/lyrics-provenance.csv` + (見 `decision-log.md` 2026-07-31、08-02 條)。 - **假說方向**:女性力量語彙的挪用與污染,成為正式研究的 研究問題。 - **粒度選擇**:正式研究鎖定 thematic keywords 這一粒度, 係繼承先導研究三種粒度的比較結果(keywords 過碎、themes - 過早抽象),且於執行前鎖定以防事後擇優。 + 過早抽象)。 - **`women-power` 一詞的來歷**:考據先導研究的 local agent 存檔可知,其第一步指令含數十個範例 thematic keywords, 其中即有 women-power——為當時協作的 Claude Code 依研究者 長期表達的關注主動加入(研究者端播種,非明示指定);先導 的標籤 `women-power-and-empowerment` 則是第三步強制合併 - 兩個關鍵字的管線人工產物。正式研究的探針因此指向被播種的 - 本詞 `women-power`,不用合併假影(見 `decision-log.md` - 2026-08-04 條)。**附帶認清:先導第一步並非零語意提示, - 此即正式研究「提示詞只定格式、不定語意」設計所矯正者。** + 兩個關鍵字的管線人工產物(見 `decision-log.md` 2026-08-04 + 條)。 - **簿記容量的教訓**:先導研究九百餘詞可以在單一回應內完成 - 分組,正式研究的 5,999 個關鍵字則四種模型六次執行全部未 - 通過完整分割驗證,遂改用詞向量嵌入＋確定性分群(見 + 分組;此法未沿用,詞彙表改由確定性程序產生(見 `decision-log.md` 2026-08-06 條)。 ## 四、被棄用的成果 @@ -63,35 +59,20 @@ frame-aware 提示修正實驗,均由當時協作的 Claude Code 設計並 以下先導研究的產物未進入正式研究,論文亦未引用: - **genuine／peripheral／fake 三分類與「44% 假女性力量」**: - 構念與分母皆與正式研究不同(正式研究為 145 首女性力量群 - 歌曲中 111 首有性別問題),兩者不可對讀。 -- **五種「假女性力量」類型(A–E)**:正式研究改由儀器分三個 - 發話脈絡各自歸納,得 43 條問題樣態(`results/patterns.csv`)。 -- **pussy 一詞的修辭分類**:正式研究範圍收斂至語彙的挪用與 - 污染,未納入。 + 構念與分母均未經稽核回溯,未沿用。 +- **五種「假女性力量」類型(A–E)**:未沿用。 +- **pussy 一詞的修辭分類**:未沿用。 - **frame-aware(框架感知)提示修正法**:先導研究以框架判準 - 寫進提示以提高準確率;正式研究刻意不定義編碼,因為研究 - 對象正是 LLM 未受引導的自然編碼——把框架寫進提示,即無法 - 再以其輸出為批判對象。兩者的設計方向相反,故未沿用。 -- **三個獨立 LLM subagent＋人工仲裁的流程**:正式研究改以 - Anthropic API 逐首獨立呼叫,原因是實測證實 subagent 會繼承 - CLAUDE.md 與環境資訊,context 無法僅憑定義檔重現(見 - `decision-log.md` 2026-07-30 條)。 + 寫進提示以提高準確率;未沿用。 +- **三個獨立 LLM subagent＋人工仲裁的流程**:未沿用,原因見 + `decision-log.md` 2026-07-30 條。 -## 五、它如何促成正式研究的設計 +## 五、它促成了可稽核的設計 先導研究的根本限制不在結論對錯,而在**不可稽核**:沒有定義檔 快照、沒有原始輸出歸檔、沒有參數紀錄,因此任何一個數字都無法 -回溯到產生它的那一次執行。正式研究的幾項設計正是針對這一點: - -- 所有 LLM 步驟改以 API script 執行,每次執行自我完備歸檔於 - `runs/`(定義檔快照、原始輸出、model ID 與參數、批次 ID、 - token 用量); -- 可逐項機械比對的判斷採三次執行＋多數決,並量測其穩定性 - (見 `reliability.md`); -- 定義檔只規定任務形狀,不給主題定義、判準或範例; -- 每一筆編碼必附歌詞引述,供逐筆查核; -- 輸出的契約遵從另行查核(見 `output-validation.md`)。 +回溯到產生它的那一次執行。正式研究的可稽核設計,正是針對這一點 +而立。 換言之,正式研究對 LLM 輸出所採取的「不信任、須查核」立場, 其第一個案例就是先導研究本身。 @@ -102,6 +83,3 @@ frame-aware 提示修正實驗,均由當時協作的 Claude Code 設計並 的前身),樹中不另存副本——摘要只是產物,不足以記述過程, 故另立本檔。 - 先導研究的歌詞捕捉檔沿用事實:`data/captures/lyrics-provenance.csv`。 -- 相關決策條目:`decision-log.md` 2026-07-30(不與先導比較、 - 不用 subagent)、07-31 與 08-02(歌詞沿用與私人匯入腳本)、 - 08-04(women-power 來歷考據)、08-06(詞彙表改用詞向量分群)。 diff --git a/docs/project-structure.md b/docs/project-structure.md deleted file mode 100644 index d093667..0000000 --- a/docs/project-structure.md +++ /dev/null @@ -1,139 +0,0 @@ -# 專案目錄結構 - -（2026-07-30 討論定案；2026-07-31 更新為 tools/ 子專案與 -SQLite 工作儲存架構；2026-08-17 依完成後的現況更新） - -``` -pop-fem-audit/ -├── README.md # 專案說明 -├── .gitignore # captures/lyrics/、.env、scratch -├── data/ # 依生命週期分層（文字格式） -│ ├── source/ # 源頭：手放後不動 -│ │ └── yearend_hot100_2016_2025.csv # 原始榜單 -│ ├── captures/ # 外部捕捉：只由 fetch 命令與 -│ │ │ # 私人匯入腳本寫入 -│ │ ├── artists-wikidata.csv # Wikidata 快照 -│ │ ├── lyrics-provenance.csv # 歌詞出處 -│ │ └── lyrics/ # 歌詞 .txt 快取 -│ │ # （gitignored，版權） -│ ├── manual/ # 人工著作：只由研究者手寫 -│ │ ├── coding-corrections.csv # 編碼與引述的校對表 -│ │ └── performer-gender-corrections.csv # 演唱聲音性別的 -│ │ # 手工修正 -│ └── derived/ # 衍生：只由 build-db 寫入 -│ ├── songs.csv # 歌曲報表（人讀；進 git） -│ └── artists.csv # 歌手報表（人讀；進 git） -├── prompts/ # LLM 定義檔（逐字作為 system prompt） -│ └── <步><次步>-.md # 1-tag.md、3a-code.md、 -│ # 4-group.md、5a-read.md、 -│ # 5b-consolidate.md、 -│ # 5c-synthesize.md、 -│ # 5d-annotate.md -│ # （次步以字母標示，與論文正文 -│ # 的步驟編號一致；步內僅一個 -│ # 執行時省略次步） -│ # 不帶版本號，版本即 git 歷史 -│ # （編號的所指是工序：確定性 -│ # 的步驟 2 無定義檔仍佔一號） -├── tools/ # 輔助工具子專案（src-layout） -│ ├── pyproject.toml # 發行名 pop-fem-audit-tools； -│ │ # pip install -e tools/ 安裝 -│ ├── README.rst LICENSE MANIFEST.in .env.example .gitignore -│ ├── docs/ # Sphinx API 文件 -│ ├── instance/ # SQLite 工作儲存（generated、 -│ │ # gitignored；含歌詞全文） -│ ├── src/pop_fem_audit_tools/ -│ │ ├── __main__.py # 套件 CLI 進入點（分派子命令） -│ │ ├── commands/ # CLI 子命令模組（登記於 __init__） -│ │ │ ├── build_db.py # build the SQLite working store -│ │ │ │ # from the inputs -│ │ │ ├── export_llm_input.py # export the LLM input JSONL -│ │ │ │ # (lyrics only) from the -│ │ │ │ # working store -│ │ │ ├── fetch_artists.py # fetch artist metadata from -│ │ │ │ # Wikidata into the snapshot CSV -│ │ │ ├── fetch_lyrics.py # fetch missing lyrics from the -│ │ │ │ # public APIs into the lyrics dir -│ │ │ ├── cluster_keywords.py # pool the tagging runs' -│ │ │ │ # keywords and cluster them -│ │ │ │ # into the codes (step 2) -│ │ │ ├── tally_codings.py # settle step 3 by majority -│ │ │ ├── tally_groups.py # settle step 4 by majority -│ │ │ ├── tally_annotations.py # settle step 5d by majority -│ │ │ └── run_llm.py # API 執行器：一份定義檔＋一份輸入 -│ │ │ # →歸檔至指定目錄（Batch API）； -│ │ │ # 多次執行的計票由獨立子命令承擔 -│ │ ├── config.py # pydantic-settings 設定（.env） -│ │ ├── database.py # SQLAlchemy engine / session / Base -│ │ ├── models.py # SQLAlchemy ORM 資料模型 -│ │ └── utils.py # 共用工具（format_duration） -│ └── tests/ # 單元測試（unittest） -├── runs/ # 現行執行的完整稽核紀錄（進 git； -│ │ # 重跑同一 run 須明示 --replace） -│ ├── <步驟名>/ # 一步一個目錄（1-tag、3a-code、 -│ │ # 4-group、5a-read、 -│ │ # 5b-consolidate、 -│ │ # 5c-synthesize、5d-annotate） -│ │ └── run/ # LLM 步驟：每個 run 一份自我 -│ │ ├── prompt.md # 完備歸檔（定義檔快照） -│ │ ├── output.jsonl # 該次執行原始輸出 -│ │ └── meta.json # model ID、temperature、時間戳、 -│ │ # batch ID、token 用量 -│ └── 2-cluster/ # 確定性步驟：無執行變異， -│ # 不分 run 層 -├── results/ # 論文引用的定案表 CSV（計票子命令 -│ │ # 產出；「可再生仍 commit」的例外） -│ ├── codings.csv # 步驟 3 定案編碼 -│ ├── groups.csv # 步驟 4 定案編碼群 -│ ├── patterns.csv # 步驟 5c 定案樣態表 -│ ├── annotations.csv # 步驟 5d 定案歌×樣態 -│ └── pattern-matrix.csv # 前四者的人讀寬表 -├── docs/ -│ ├── conventions.md # 常設工作規範（原 CLAUDE.md； -│ │ # 移入 docs/ 使 subagent 不繼承） -│ ├── research-plan.md # 研究步驟規劃（本檔之姊妹篇） -│ ├── project-structure.md # 本檔 -│ ├── output-validation.md # LLM 輸出的契約查核紀錄 -│ ├── decision-log.md # 決策日誌：每次改定義檔的原因 -│ ├── run-costs.md # 每次執行的 token 用量與費用 -│ ├── reliability.md # 信度：量測方式與結果 -│ ├── pilot-study.md # 先導研究的來歷與地位 -│ └── methodology.md # 方法細節（全文方法節底稿； -│ # 映射分析方法須在看結果前寫定） -└── paper/ - ├── abstract.md # 摘要 - └── 流行音樂中「女性力量」….odt # 全文 -``` - -## 設計理由 - -- **`runs/` 自我完備**：每個執行目錄含定義檔快照 + 原始輸出 + - meta，讀者不需 git 考古即可稽核任一筆結果。 -- **`runs/`（原始稽核資料）與 `results/`（最終表）分離**： - 論文只引 `results/`，其來源可回溯至 `runs/`。 -- **`prompts/` 檔名不帶版本號**：版本即 git 歷史，失敗的 - 版本不保留；論文引用的單位是 `runs/` 內隨執行保存的定義檔 - 快照（每個執行目錄自我完備），不需檔名可指的版本名。 -- **工作儲存的資料表**：`songs`（含 `performer_gender`＝演唱 - 聲音的性別）、`chart_entries`、`artists`、`song_artists`、 - `codings`（定案編碼：一歌一標籤一列，`quotes` 存該標籤所據的 - 歌詞引述，多句以 `|` 相接）、`groups`（語意編碼群）、 - `patterns`（深讀樣態）、`annotations`（歌×樣態定案矩陣）。 - 各定案表經 `build-db` 的 `--codings`、`--groups`、 - `--patterns`、`--annotations` 匯入，性別修正經 - `--gender-corrections` 套用，與其餘資料同一交易，儲存不會 - 半建；詳見 `research-plan.md`「資料儲存與模型」。 -- **Commit 判準**：能由「committed 輸入＋程式」決定性再生者不 - commit（SQLite 工作儲存、LLM 輸入檔）；源頭、捕捉、人工著作 - 一律以文字 commit。「可再生仍 commit」的例外有二： - `results/` 報表（引用穩定性、審稿人零門檻、撰稿期可 diff） - 與 `data/derived/` 人讀報表（與工作儲存同一動作產出，稽核 - 鏈無中間空缺）。詳見 `research-plan.md`「資料儲存與模型」。 -- **設定**經 pydantic-settings 統一：`.env`（gitignored，範本 - `tools/.env.example`）供應 `SQLALCHEMY_DATABASE_URL` 與 - `ANTHROPIC_API_KEY`，絕不寫入 repo。 -- **不設 CLAUDE.md**：實測證實 Claude Code subagent 會繼承專案 - CLAUDE.md 全文（原本因此只放極簡工作規則），2026-08-18 進一步 - 將其移為 `docs/conventions.md`——docs/ 不會自動注入 subagent - 的 context，盲判型 agent 便不會看到工作規範；主會話動手前 - 自行閱讀之。 diff --git a/docs/reliability.md b/docs/reliability.md index c3a5f2b..433f458 100644 --- a/docs/reliability.md +++ b/docs/reliability.md @@ -1,8 +1,7 @@ # 信度:量測方式與結果 -（2026-08-16 量測。對象為步驟 3a 的三份執行歸檔 -`runs/3a-code/run1`–`run3`,與步驟 5d 的三份執行歸檔 -`runs/5d-annotate/run1`–`run3`;數字由原始輸出直接計算。） +（2026-08-16 量測。對象為步驟 3a 與步驟 5d 各三次執行的 +原始輸出;數字由原始輸出直接計算。） ## 一、本研究的信度是什麼 @@ -34,11 +33,7 @@ Krippendorff 依產生資料的設計,把信度分成三型 **精密度(precision)**,而**準確度(accuracy)** 未經量測。 若儀器是確定性的,重複性無須量測;但 LLM 不是——同樣的提示、 同樣的輸入,三次會給出不同結果,因此重複性是必須報告的儀器 -規格,而非慣例儀式。 - -這一點與 LLM 標註的近期文獻一致:同一模型重複取樣量測的是 -自我一致性(self-consistency),而重複執行後取多數決可提升 -標註穩定度(如 Prompt Stability Scoring,arXiv:2407.02039)。 +規格。 ## 二、三個常用指標 @@ -106,7 +101,7 @@ Jaccard(只看「有標到」的格子,忽略雙方都沒標的)約 0.89–0.91, 比百分比一致率低而更誠實——因為 82% 的格子是雙方都判「無」, 那些一致並不費力。 -## 四、隨機性的規模與三票制的作用 +## 四、隨機性的規模 信度數字回答的實際問題是:**這台儀器的隨機性,大到會不會 改變結論?** @@ -116,12 +111,6 @@ Jaccard(只看「有標到」的格子,忽略雙方都沒標的)約 0.89–0.91, 一半會成為誤收、另一半會成為漏收。三票多數決把兩票以上者 收入、一票者剔除,處理的正是這一批。 -三票制並非消除隨機性,而是**把隨機性往案例原本的傾向推**。 -設某個邊緣案例的符合程度為 p,單次執行以機率 p 標出,三次 -多數決則以 p³+3p²(1−p) 標出:p=0.9 者由 0.9 提高到 0.972, -p=0.1 者由 0.1 壓低到 0.028,而 p=0.5 者仍是 0.5——真正 -模稜兩可的案例,任何票制都救不了。 - 以此規模判斷,結論層的三條帶狀結構(女性力量與陽剛群共現、 與脆弱群互斥、與厭女群獨立)不可能由這個量級的雜訊翻轉。 反過來說,若一致率只有 0.6,同一組結論就不能採信——信度 diff --git a/docs/research-plan.md b/docs/research-plan.md index d10956a..558c6ff 100644 --- a/docs/research-plan.md +++ b/docs/research-plan.md @@ -11,81 +11,33 @@ **不與先導研究做比較**； 全文數字一律以正式研究結果為準。先導研究僅作為假說的 內部來源，記於決策日誌，不進入論文敘事。 -- **執行原則**：主會話只做討論；所有分析由 deterministic - script 執行。LLM 步驟以 Python script 呼叫 Anthropic - Messages API（個人 Console 帳號、Batch API 五折），定義 - 檔逐字作為 system prompt。可逐項機械比對的判斷（步驟 3 - 編碼、步驟 4 選群、步驟 5d 樣態標註）採「同一定義檔 - 獨立執行三次＋多數決」，計票由確定性子命令完成。自由 - 生成（步驟 1 自由標註）兩次執行全數進池。步驟 5a 至 - 5c 為質性閱讀協定：三次獨立閱讀為分析者三角檢核、 - 逐首整合、樣態統整產出草稿，不適用投票與仲裁。詞彙表 - 不經 LLM，由詞向量嵌入＋確定性分群產生。驗證結果不符 - 預期則修訂定義檔重跑該循環，絕不手改結果。 +- **執行原則**：主會話只做討論，分析一律由確定性程序 + 執行。可逐項機械比對的判斷（步驟 3 編碼、步驟 4 選群、 + 步驟 5d 樣態標註）採「三次獨立執行＋多數決」定案， + 自由生成（步驟 1 自由標註）採兩次執行全數進池，步驟 + 5a 至 5c 定為質性閱讀協定；程序細節見 `methodology.md`， + 工作規範見 `conventions.md`。 - **提示詞只定格式、不定語意**：研究對象是通用 LLM 以其 網路語料知識背景所做的自然編碼與閱讀，其結果本身是 批判對象。定義檔只規定任務形狀（輸入、數量範圍、輸出 格式），不給任何主題的定義、判準或範例。LLM 判斷一律 要求逐項引述歌詞原句，作為檢視偏差的依據。 -- **模型**：步驟 1、3 用 `claude-sonnet-4-6`（temperature=0、 - thinking 關閉）；步驟 4、5 用 `claude-fable-5`（兩參數 - 不適用，均不送出；取樣變異由多數決或整合吸收）——實測 - 發現 sonnet 將「Women Power」拆讀為 women＋power 的組合 - 語意，fable-5 讀為詞彙化概念，語意層任務因此換用 - fable-5（經過見決策日誌）。 +- **模型**：步驟 1、3 用 `claude-sonnet-4-6`；步驟 4、5 + 用 `claude-fable-5`——實測發現 sonnet 將「Women Power」 + 拆讀為 women＋power 的組合語意，fable-5 讀為詞彙化 + 概念，語意層任務因此換用 fable-5（經過見決策日誌）。 - **信度與效度**：三次獨立執行量測穩定性（intra-rater reliability，可報告兩兩一致率）；封閉母體全量檢查取代 抽樣防衛。可重現性定義為「程序透明＋可稽核」：公開定義 檔、記錄 model ID 與執行時間、保存全部原始輸出。 -## 資料儲存與模型 +## 範圍性定案 -- **Commit 判準**：凡能由「committed 的輸入＋committed 的 - 程式」決定性再生者，不 commit；凡不能者——源頭資料、 - 外部世界的捕捉（Wikidata 快照、LLM 原始輸出）、人工 - 著作——一律以文字格式 commit。格式跟著層次走。 -- **分層**： - - 源頭：原始榜單 CSV（進 git）。 - - 捕捉：Wikidata 快照 CSV、`runs/` JSONL（皆進 git）； - 歌詞 `.txt` 快取（版權因素 gitignored，為已知的稽核 - 缺口）。 - - 人工：`data/manual/`（僅研究者親手寫入：編碼修正、 - 演唱者性別修正）。 - - 工作儲存：SQLite 單檔（`tools/instance/`，generated、 - 不進 git），SQLAlchemy 2.0 typed ORM 定義 schema， - 設定經 pydantic-settings（`.env` 供應 - `SQLALCHEMY_DATABASE_URL` 與 `ANTHROPIC_API_KEY`）。 - 歌詞全文入 DB（不進 git 故無版權疑慮）。 - - 衍生：`build-db` 建置工作儲存的同一動作產出人讀報表 - （`data/derived/`，進 git），與 SQLite 同交易語意。 - - 報表：論文引用的定案表進 `results/`—— - `codings.csv`（步驟 3 定案編碼）、`groups.csv` - （步驟 4 定案編碼群）、`patterns.csv`（步驟 5c 定案 - 樣態表）、`annotations.csv`（步驟 5d 定案歌×樣態 - 矩陣）。衍生與報表為「可再生仍 commit」的例外，理由： - 引用穩定性、審稿人零門檻、撰稿期數字變動可 diff。 -- **資料模型**：`songs`（含 lyrics、`performer_gender`—— - 演唱聲音之性別，由署名藝人之 Wikidata 性別推導後套用 - `data/manual/performer-gender-corrections.csv` 手工修正）、 - `chart_entries`、`artists`、`song_artists`、`codings`、 - `groups`（語意編碼群）、`patterns`（深讀樣態）、 - `annotations`（歌×樣態定案矩陣）。領域不變量（恰 1000 - 筆榜單、每歌至少一 primary 歌手等）檢查內建於 - `build-db`，違規即建置失敗。 - **歌手背景防火牆**：歌手背景資料只進人工解讀階段， **絕不進 LLM 輸入**——LLM 任務的 user message 維持 歌詞-only 或管線中間產物-only，避免光環偏誤。 -- **Pilot 歌詞沿用（私人匯入，不進發布管線）**：先導研究 - 捕捉檔（lyrics.json，684 首，2018–2025）以私人腳本 - 匯入歌詞快取；讀者的重現路徑純粹是 - `fetch-lyrics`；沿用之事實記於 - `data/captures/lyrics-provenance.csv`（進 git）。 -- **子命令**（`pop-fem-audit-tools `）：`build-db` - （`--codings`、`--groups`、`--gender-corrections`、 - `--patterns`、`--annotations`）、`cluster-keywords`、 - `export-llm-input`、`fetch-artists`、`fetch-lyrics`、 - `run-llm`（`--model` 於模型登錄表中擇一）、 - `tally-codings`、`tally-groups`、`tally-annotations`。 +- **Pilot 歌詞沿用**：先導歌詞沿用之來歷與細節詳見該檔 + （`pilot-study.md`）。 ## 分析管線（五步驟，全部完成） @@ -96,27 +48,19 @@ 階層式聚合分群 k=100，組名取 medoid；再併入研究者先驗 主題詞 `women-power`（據實揭露的儀器介入），共 101 碼。 3. **編碼（步驟 3）**：以定稿詞彙表對全 883 首編碼，逐 - 標籤附引述，×3＋多數決（`tally-codings`），定案 - `results/codings.csv`。「女性力量」候選集（wp 66 首、 - fe 144 首、wp∪fe 145 首）由此浮現。 + 標籤附引述，×3＋多數決，產出定案編碼表。「女性力量」 + 候選集（wp 66 首、fe 144 首、wp∪fe 145 首）由此浮現。 4. **語意編碼群（步驟 4）**：LLM 依編碼字面語意將 101 碼 選入研究者指定的四個主題群（women-power／misogyny／ - masculine／vulnerable），×3＋多數決（`tally-groups`）， - 定案 `results/groups.csv`；wp/fe 與各編碼、各編碼群之 - 關聯統計（BH-FDR 校正）入論文。 + masculine／vulnerable），×3＋多數決，產出定案分群表； + wp/fe 與各編碼、各編碼群之關聯統計（BH-FDR 校正）入 + 論文。 5. **女性主義問題之質性深讀（步驟 5）**：對 wp∪fe 145 首 ——5a 逐首盲讀（僅歌詞全文）×3；5b 逐首整合（收斂 註記、主清單限兩讀以上）；5c 樣態統整（全體基底＋ 男聲／女聲／混合三個發話脈絡分組）；5d 樣態標註—— - 以分組樣態表逐首標註「有問題」的 111 首，×3＋多數決 - （`tally-annotations`），定案 `results/patterns.csv` 與 - `results/annotations.csv`。 - -定義檔命名 `prompts/<步><次步>-.md`，次步以字母標示 -（與論文正文的步驟編號一致）；編號的所指是工序而非定義檔 -（確定性的第 2 步無定義檔仍佔編號）；檔名 -不帶版本號——版本即 git 歷史；每次執行的定義檔快照隨 -`runs/` 自我完備，token 費用逐筆記於 `docs/run-costs.md`。 + 以分組樣態表逐首標註「有問題」的 111 首，×3＋多數決， + 產出定案樣態表與歌×樣態定案矩陣。 ## 時程與剩餘工作 @@ -125,8 +69,3 @@ 污染」結論（步驟 5 素材已備）、信度說明、fe 與新自由 主義敘事之詮釋標註。 -## 其他已定案事項 - -- 歌詞受版權保護：完整歌詞不進 git - （`data/captures/lyrics/` gitignored），論文與 repo 只留 - 分析所引摘錄。