idd-comment: human-facing comment mode — 逐點說清楚哪邊改了什麼 + perspective-writer 深度整合

[kiki830621]

Problem

Original text（2026-07-18）：
「我覺得如果是要給人看的comment，必須要說清楚哪邊改了什麼，可能我覺得可以跟perspective writer深度整合」
— Source: maintainer feedback，downstream research-repo session（/idd-close 後補「給 review 提出者的逐點回覆 comment」時）

情境：downstream private research repo 跑完 /idd-all → verify → merge → /idd-close 整條 pipeline 後，maintainer 要求對 review 提出者（人類 collaborator，非 AI）發一則「逐點回覆」comment：逐字引用對方原始 review 的每一點（blockquote）→ 緊接說明該點怎麼改（哪個 theorem / 哪段論證 / 哪個 commit）。這則 comment 本質是寫給人看的信件，不是 audit log——但現行 idd-* 的 comment 模板（closing 五段式、verify master report、idd-comment 六型）全部 audit-facing，沒有一型是 recipient-facing。結果是 maintainer 分兩輪口頭指揮才把格式排對（先「tag 他回應他」→ 再「逐點的處理要寫在最後給老師的 comment 裡面，說每一個怎麼改」）。

兩個 gap：

1. 「哪邊改了什麼」的粒度保證：給人看的 comment 必須 per-point 說清楚改動落點（file / theorem / section）＋改法＋錨定 merge SHA。audit 五段式把這些聚合在 Solution / Changes 段，對「寫 review 的人」不可導航——他要的是「我提的第 3 點你怎麼處理了」，不是聚合摘要。
2. 語氣與收件人 calibration：recipient-facing comment 本質是 correspondence。perspective-writer plugin（psychquant-claude-plugins）已有 writer voice、recipient context、T-schema referent 紀律（每句 claim 要指到真實事物）、role-calibrator、draft-learner / save-feedback 的 rules 學習迴圈——這些正是「給人看的 comment」需要、而 idd-comment 完全沒有的能力。

Type

feature

Expected

idd-comment（或新 mode / flag，如 --audience human / --reply-to-review）在 comment 的 audience 是人類 collaborator 時：

1. 模板切成 recipient-facing 逐點結構：對方原文逐點 blockquote → 該點的處理（哪裡改、怎麼改、cross-link commit / PR / theorem label）→ 結尾狀態（merged SHA、同步狀態、下一步）
2. Draft 經 perspective-writer 深度整合後才 egress：voice、對象關係（指導教授 vs 同儕 vs 外部 reviewer）、T-schema referent check（每句「已修正」都要能指到真實 diff）
3. Audit trail 不退化：human-facing comment 是 closing summary 之外的加項，不取代五段式

Actual

idd-comment 六型模板（decision / note / question / correction / link / errata）與 idd-close 五段式皆 audit-facing；「給人看」的 comment 只能靠 user 每次口頭指揮 ad-hoc 重排，無 voice calibration、無 per-point 錨定保證、且 perspective-writer 的 rules 學習迴圈吃不到 IDD comment 場景的 feedback（兩套系統各自為政）。

Impact

• 對外（advisor、合作者、reviewer）溝通品質仰賴每次一次性口頭指令，不可重複、不可累積
• 逐點回覆是學術協作的高頻場景（review reply、revision letter 的 issue-comment 版），值得 first-class 支援

Case study

• PsychQuantHsu/psychophysical_representations#141（private）：6 點 review 的逐點回覆 comment，兩輪口頭指揮才成形；最終格式（每點：原文 blockquote → 中文說明改法 → 錨定 merge SHA）可直接作為 recipient-facing 模板的雛形

---

Current Status

• Phase: closed
• Complexity: Spectra（Layer 2 + Layer 3；diagnosis: comment 5010841949）
• Next: /spectra-apply add-idd-comment-reply-type（proposal 已建並 parked；IDD comment 過多觸發 GitHub notification fatigue — human-only vs AI-only 分流? #116 extraction 已完成，perspective-writer@perspective-writer v2.10.0 上線）
• Last update: 2026-07-18

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

（feature → 需求分析）

需求拆解（源自 issue body 的兩個 gap）：

• R1 逐點結構：recipient-facing 模板 — 對方原文逐點 blockquote → 該點怎麼改、改在哪（file / theorem / section）→ 錨定 commit / PR / merge SHA → 目前狀態。
• R2 「哪邊改了什麼」的可驗證性：每句「已修正」都要指到真實已 merge 的 diff（T-schema referent）。寫 comment 前強制 verify completeness（git log --grep "#N" 找 commit、spot-check 改動實質性）。
• R3 perspective-writer 整合：draft 在 egress 前經 voice / 對象關係 calibration；per-recipient 規則（語氣、稱謂、結構偏好）由 draft-learner / save-feedback 學進 target repo 的 .claude/rules/correspondence-*.md，跨 session 累積。
• R4 audit 不退化：human-facing comment 是 closing summary 的加項，不取代五段式。

Prior art 對照（兩件都已存在、已在實戰驗證同構模式）：

能力	suggestion-report（ai_martech_principles .claude/skills/）	perspective-writer plugin（psychquant-claude-plugins）	本 feature 取用
逐點模板	客戶反映（blockquote 原文）→ 問題原因 → 解決方式 → 目前狀態	—	R1 模板骨架
claim 可驗證性	Step 2 verify completeness（per-issue commits check + acceptance）強制在寫報告之前	T-schema referent 紀律（每句 claim 指到真實事物）	R2（兩者收斂到同一原則）
語氣 / 對象	非技術語言（audience = 老闆）寫死在模板	voice、recipient context、role-calibrator 動態校準	R3
學習迴圈	—	draft-learner / save-feedback → .claude/rules/	R3

未決設計點（spectra 流程的議題）：

• D1 形態：idd-comment 新 --type=reply vs 正交 --audience human flag vs 獨立 skill（IDD 慣例反對 70% 重疊時開新 skill）
• D2 跨 plugin 依賴政策：hard fail-fast（確立「深度整合 >> hard-coded」rule（.claude/rules）並以 superpowers plugin 為首個深度整合對象 #209 superpowers delegation 前例：check-plugin-presence pre-flight + abort）vs graceful degrade（perspective-writer 缺席時照 post、只 warn 不 calibrate）。perspective-writer 住在個人 marketplace，對 IDD 公共使用者 hard dependency 偏重
• D3 「逐點」的 source：issue body 的 Original text blockquote / 指定某則 comment / user 貼上原文
• D4 recipient context 存放：--mention resolved login + target repo .claude/rules/correspondence-<person>.md（perspective-writer 既有慣例）

Impact

• plugins/issue-driven-dev/skills/idd-comment/SKILL.md — 新 mode / type 模板 + 整合步驟 + pre-flight
• references/（可能新增 human-facing comment 契約檔）、README type 對照表、CHANGELOG
• scripts/check-plugin-presence.sh — 直接重用（確立「深度整合 >> hard-coded」rule（.claude/rules）並以 superpowers plugin 為首個深度整合對象 #209 pattern），無改動
• 跨 repo：perspective-writer 端可能需要可程式呼叫的「calibrate draft」入口契約（psychquant-claude-plugins）— 見 Sister Concerns

Strategy

（實作層 checklist — 形態以 spectra 流程收斂後為準）

• spectra-discuss 收斂 D1–D4
• spectra-propose 寫 spec（human-facing comment mode 的 normative contract）
• idd-comment SKILL.md 加 mode：逐點模板（R1）+ verify-before-claim gate（R2，移植 suggestion-report Step 2、對齊 idd-close Step 1.6 semantic gate 不重造）+ perspective-writer delegation（R3，確立「深度整合 >> hard-coded」rule（.claude/rules）並以 superpowers plugin 為首個深度整合對象 #209 pattern）
• docs 同步（README / CHANGELOG / references）
• dogfood：用 issue body 的 case study（6 點 review 逐點回覆）回放驗收

Conflict Class

A_parallel_safe — 改動集中在 IDD repo 內 skill / doc 檔，無共享 mutable runtime 資源；perspective-writer 端是設計期契約、非實作期資源競爭。

Complexity

Spectra

• Layer 2（necessary）：命中 — 改動對外暴露 published plugin skill surface（idd-comment 新 mode / flag 是給 future callers 的公開行為契約）
• Layer 3（confirmation）：命中兩項 — (a) architectural decision with long-term maintenance（跨 plugin 依賴政策會被之後所有 human-facing 輸出繼承）；(b) 影響 2+ 既有 skill docs 的 consistency（idd-comment 六型對照、idd-close 指引、README）
• 硬閘 / Layer P：未評估 — routing 於序列 step 4（Spectra）已定案

→ 建議 pre-implementation staging: superpowers:brainstorming

Risks

• 公共 plugin 硬依賴個人 marketplace plugin → 可攜性風險（D2 是關鍵決策）
• verify-before-claim 與 idd-close Step 1.6 semantic gate 職責重疊 → 重用不重造
• voice calibration 改寫技術敘述時可能弄丟 referent（「已修正」語意漂移）→ calibration 必須在 per-point SHA 錨定之後執行，且不得改動錨定事實
• 隱私：human-facing comment 常發在含第三方內容的 private repo → 沿用既有 scrub-level 契約；per-recipient rules 檔留在 target repo、不進 plugin

Residue

issue 的深層意圖「IDD 對人的輸出本質是 correspondence」大於 issue-comment 這個切面 — PR description、discussion 匯報（suggestion-report 類 boss-facing report）都在同一 horizon。本 issue 只 operationalize issue-comment 切面；統一 audience model（老闆 / advisor / 同儕的 register 差異）留在 horizon，不納本次 scope。

Vagueness Pre-check

• V1: 2 — WHAT 明確：recipient-facing 逐點 mode + perspective-writer 整合，issue body 含具體 case anchor（6 點 review 逐點回覆）與兩個 named gap
• V4: 3 — acceptance 有 case study 當模板雛形（Expected 段 3 點），但「深度整合」的完成定義刻意留待 spectra 流程收斂（D1–D4）
• Triggered: no — both axes ≤ 3

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

• (deferred — blocked-on-design) perspective-writer 端「calibrate draft」programmatic 入口契約（psychquant-claude-plugins repo）：D1 / D2 未收斂前 filing 只會產生 vague tracking issue；spectra 流程定案整合形態後隨 proposal 一併 file。

[kiki830621]

🎯 Decision

Original（2026-07-18，spectra-discuss）：
「都對，然後 perspective-writer 我也想要讓它變成獨立的repo，也就是一個獨立的marketplace」

決定

spectra-discuss 收斂 diagnosis 的 D1–D4，並新增 D5（standalone marketplace）與 sequencing：

#	決策
D1	idd-comment 第 7 型 --type=reply（必填 --points-from）；不做 --audience 正交 flag（6 型 × audience 組合矩陣的 spec 面積爆炸）、不開新 skill（70% 重疊反模式）
D2	Soft integration + graceful degrade：presence check → 有 perspective-writer 則過 calibration、缺席則印一行安裝指令照 post。不寫 install-time dependencies
D3	--points-from 三層：顯式 comment URL → 預設 issue body 的 Original text blockquote → fallback 使用者貼原文
D4	recipient context 留在 target repo .claude/rules/correspondence-<person>.md（perspective-writer 既有慣例）；IDD 只傳 --mention resolved login
D5	perspective-writer 抽成 standalone repo + 獨立 marketplace PsychQuant/perspective-writer（鏡像本 repo 佈局：repo 名 = marketplace 名 = plugin 名）。工作項：PsychQuant/psychquant-claude-plugins#116
順序	先抽 repo（D5 / #116）→ 再 spectra-propose 本 issue —— spec 的 presence-check 座標（check-plugin-presence.sh perspective-writer perspective-writer）與 degrade notice 安裝指令引用最終位置。Calibration 執行序：referent 錨定在前、calibration 在後、不得改動錨定事實

Rationale

核心 trade-off 是 D2 的「替代 vs 加值」。superpowers-integration spec 的 fail-fast 有明文理由——superpowers 取代 IDD 自有 process 敘述（SHALL NOT fall back to built-in equivalent），缺席時無物可退；reply 型不同：逐點結構與 verify-before-claim gate 是 IDD 自有紀律，缺 calibration 時輸出仍完整正確，perspective-writer 是 enhancement 而非 canonical process 替代，故 soft + degrade。D5 是 D2 的前提補強：degrade notice 的安裝指令要對公共使用者成立，perspective-writer 需要 standalone 公共身份（個人 umbrella marketplace 不是合理 install target）；抽出成本極低（7 檔案 76K，CHANGELOG 自帶版本史，fresh repo 起步即可）。

Related

• 抽 repo 工作項：perspective-writer 抽成 standalone repo + 獨立 marketplace（鏡像 issue-driven-development 佈局） psychquant-claude-plugins#116
• 前例 spec：openspec/specs/superpowers-integration/spec.md（fail-fast 的邊界條件，本案刻意走另一側）
• Deferred sister concern（calibrate-draft 程式化入口契約）→ IDD comment 過多觸發 GitHub notification fatigue — human-only vs AI-only 分流? #116 完成後 file 到新 repo
• 下一步：IDD comment 過多觸發 GitHub notification fatigue — human-only vs AI-only 分流? #116 完成 → /spectra-propose（D1–D4 寫成 normative spec）

[kiki830621]

Verify (via PR #271)

Result: PASS（after round-1 fix ef61572）— 0 blocking，round-1 的 4 個實質不一致（含 1 個 HIGH：verify-before-claim per-point）已全部在 PR 內修掉，follow-up #272 filed。

Full report: #271 (comment)

[kiki830621]

Closing Summary

Problem

idd-* 產出的 comment 全部 audit-facing（closing 五段式、verify master、idd-comment 六型），沒有一型是寫給人類 collaborator（review 提出者、指導教授）看的。#141 六點 review 的逐點回覆分兩輪口頭指揮才排出格式，且無「每句『已修正』都指到真實 diff」的機械保證，也無語氣／對象 calibration。

Solution

idd-comment 新增第 7 型 --type=reply（v2.100.0，recipient-facing 逐點回覆），經 spectra 全流程（discuss → propose → apply）落地：

• 逐點模板：對方原文逐點 verbatim blockquote → 改了哪/怎麼改 → commit/PR/merge SHA 錨定 → per-point 狀態；結尾整體狀態行 + metadata marker。必填 --points-from（三層 value 解析：comment URL → issue-body sentinel → user-paste fallback；禁 paraphrase）。
• verify-before-claim gate（per-point）：每點宣稱已解決前，git log --grep 找到的 commit/PR 須實際含處理『該點』的改動——非 issue-level（round-1 DA-1 HIGH 修正）。
• perspective-writer soft integration + graceful degrade：presence-check 命中 → voice/recipient calibration；缺席 → 印安裝指令照 post。無 install-time dependency（刻意與 superpowers hard-dependency 相反）。錨定先於 calibration、calibration 不得改動錨定事實。
• 依賴 perspective-writer 抽成 standalone marketplace（perspective-writer 抽成 standalone repo + 獨立 marketplace（鏡像 issue-driven-development 佈局） psychquant-claude-plugins#116 → PsychQuant/perspective-writer v2.10.0），degrade notice 的安裝指令才對公共使用者成立。

Verification

6-AI 交叉驗證 round 1（4 lens opus + Codex gpt-5.6-sol + Devil's Advocate）→ Aggregate PASS（master report）。Round-1 找到 4 個實質不一致（含 DA-1 HIGH：verify-before-claim 誤為 issue-level），全部在 PR 內修掉（ef61572）並補測試鎖住。

• drift-guard suite idd-comment-reply 19 → 27 assertions（RED-verified 非 tautological）
• run-all-tests.sh 40 suites 0 fail
• spectra validate valid、analyze 0 critical/warning

Changes

• 14516f9（squash-merge PR feat(idd-comment): --type=reply human-facing point-by-point reply (v2.100.0, #269) #271）— feat + fix round：SKILL.md 第 7 型契約、drift-guard suite、docs（commands/workflows/README）、CHANGELOG、兩 manifest → v2.100.0
• 3d85e70 — spectra archive（spec 套用到 openspec/specs/idd-comment-reply/，6 requirements）
• tag idd-269-verified @ verified snapshot

Follow-ups

• reply 型第三方 verbatim payload 應強制 heightened scrub tier（不論 repo visibility）—— #269 DA-3 follow-up #272 — reply 第三方 verbatim payload 應強制 heightened scrub tier（DA-3 深層 tier-forcing，跨切面 privacy-scrubbing 決策）
• EXTERNAL-CONSUMER CONTRACT: calibrate-draft 程式化入口（供 IDD idd-comment --type=reply soft-integration） perspective-writer#1 — programmatic calibrate-draft EXTERNAL-CONSUMER CONTRACT（整合深度升級的前置）