From 3b09ee9aa13f309df53232eef68be05f40496b2d Mon Sep 17 00:00:00 2001 From: che cheng Date: Fri, 14 Aug 2026 05:48:05 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20/idd-reorganize=20=E2=80=94=E2=80=94=20?= =?UTF-8?q?=E4=B8=8A=E6=B8=B8=20artifact=20=E9=8C=AF=E8=AA=A4=E6=99=82?= =?UTF-8?q?=E7=9A=84=20re-baseline=20=E6=93=8D=E4=BD=9C=20(#200)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit IDD 是 append-only 的鏈，上游前提一錯就被下游繼承並放大。既有的兩種應對都不夠： idd-edit 只改一處文字（無法傳播），idd-verify 在鏈的末端才抓到（成本高且不保證抓到）。 新 skill 把傳播變成明確操作：一句話指名錯的 artifact → 機械枚舉所有下游產物 → 逐一裁定 still-valid / redo / invalidate 並附理由 → post ## Re-baseline 紀錄 → phase 退回重做起點。 兩個刻意的約束：still-valid 必須寫理由（「看起來沒關係」是這個操作最常見的失效 方式）；紀錄要有「為什麼現在才發現」欄位（那是唯一會累積成「我們的上游錯誤長什麼 樣」的資料，也正是 #144 那條 MANIFESTO 規則的證據來源）。 worked example 就是本 repo 的 #295：diagnosis 把 root cause 判在 marker 比對上， 七輪之後才發現真正的原因在 gh 的取得層、根本不在分類器 —— 下游全部建在錯誤前提上， 靠人工逐一回頭修，而那正是散文分岔連四輪復發的原因。 45/45 suites 綠（含 docs-catalog-sync 對新 skill 的登錄要求）。 --- docs/skill-dimensions.md | 1 + .../.claude-plugin/plugin.json | 2 +- plugins/issue-driven-dev/CHANGELOG.md | 25 ++++ .../skills/idd-reorganize/SKILL.md | 114 ++++++++++++++++++ 4 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 plugins/issue-driven-dev/skills/idd-reorganize/SKILL.md diff --git a/docs/skill-dimensions.md b/docs/skill-dimensions.md index 59c12b4..86d78ab 100644 --- a/docs/skill-dimensions.md +++ b/docs/skill-dimensions.md @@ -233,6 +233,7 @@ IDD plugin 已累積 14+ skills(`idd-issue` / `idd-diagnose` / `idd-implement` / | `idd-update` | Sep | Atom | Side | W | Fwd | S / Batch | SHALL phase sync | Unatt-capable | Sk | Cl-non | | `idd-comment` | Sep | Atom | Side | W | Fwd | S / Batch | SHOULD template | Unatt-capable | Sk + flags | Cl-non | | `idd-edit` | Sep | Atom | Side | W | (任) | S / Batch | SHALL preview before write | Att-only | Sk | Cl-non | +| `idd-reorganize` | **修復** | 上游 artifact 的前提錯了、而下游已經建在它之上時的 re-baseline 操作（#200）。與 `idd-edit` 的分界：edit 改**一處文字**，reorganize 讓修正**向下傳播** —— 機械枚舉所有下游產物，逐一裁定 still-valid / redo / invalidate，並留下含「為什麼現在才發現」的 re-baseline 紀錄 | | `idd-list` | (n/a) | Atom | n/a | R | (查) | S | n/a | Unatt-capable | Sk + flags | Cl-non | | `idd-clarify` | Sep | Atom | Delib(surface-only) | W (annotation block) | Fwd | S | SHALL hard-gate consumer (diagnose Step 0.5) | Unatt (deferred-row 機制 #137) | Sk + flags | Cl-non | | `idd-find` | (n/a) | Atom | n/a | R | (查) | S | n/a | Unatt-capable | Sk + flags | Cl-non | diff --git a/plugins/issue-driven-dev/.claude-plugin/plugin.json b/plugins/issue-driven-dev/.claude-plugin/plugin.json index 610fdef..57b62e0 100644 --- a/plugins/issue-driven-dev/.claude-plugin/plugin.json +++ b/plugins/issue-driven-dev/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "issue-driven-dev", "description": "v2.102.2: Deep Research light integration (#277, ruling b). idd-diagnose gains a non-binding pointer (the #111 superpowers hand-off shape: pure suggestion, no presence check, no dependency) fired when the diagnosis's quality depends on facts OUTSIDE the repo — with trigger examples AND counter-examples (the overly-broad-signal risk). Output flows back via '/idd-comment --type note' as summary + link, never full text (#116) — that is what keeps external research inside the audit trail. Both real-user misconceptions get canonical answers where they lived: research attaches AT diagnose (not after plan), and research vs implement are different phases' work, not substitutes. usecase-routing scenario 32 + a three-row internal-corpus vs external-world boundary table (idd-find / idd-ask / Deep Research). Deep integration stays a recorded residue until a plugin-dependable primitive exists.", - "version": "2.106.0", + "version": "2.107.0", "author": { "name": "Che Cheng" }, diff --git a/plugins/issue-driven-dev/CHANGELOG.md b/plugins/issue-driven-dev/CHANGELOG.md index cbf1d20..c33e076 100644 --- a/plugins/issue-driven-dev/CHANGELOG.md +++ b/plugins/issue-driven-dev/CHANGELOG.md @@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.107.0] - 2026-08-14 + +### Added + +- **`/idd-reorganize` — a first-class re-baseline when an upstream artifact was wrong (#200)** — user's words: + 「idd 有一個問題就是如果前面有問題的化，會對後面造成毀滅性的影響，我覺得 idd-edit 可能還不夠」. IDD is an append-only + chain, so a wrong premise upstream is inherited and amplified downstream, and the two existing responses are both + insufficient: `idd-edit` changes **one piece of text** (it cannot propagate), and `idd-verify` catches the problem at + the **end** of the chain (expensive, and only if it catches it). The new skill makes propagation an explicit + operation: name the wrong artifact in one sentence, **mechanically** enumerate everything built on it (comments, plan, + spec/tasks, branch, PR, commits, issues referencing it), adjudicate each as still-valid / redo / invalidate **with a + reason**, post a `## Re-baseline` record, and roll the phase back to the redo point. + + Two deliberate constraints. `still-valid` requires a written reason, because "looks unrelated" is this operation's + commonest failure — downstream artifacts inherit premises in non-obvious places (a test's stated rationale, a + CHANGELOG's causal narrative). And the record has a **"why was this only found now"** field, because that is the one + thing that accumulates into evidence about what our upstream errors look like — the same evidence base the MANIFESTO + rule added in #144 draws on. + + Its worked example is this repo: `#295`'s diagnosis located the root cause in the marker comparison; seven verify + rounds later the real cause turned out to be in `gh`'s **acquisition layer**, not the classifier at all. Everything + downstream — the Strategy, four rounds of test rationale, the CHANGELOG's causal account, and four prose + descriptions of the rule — had been built on the wrong premise and was repaired by hand, which is exactly why the + prose-drift defect recurred four rounds running. + ## [2.106.0] - 2026-08-14 ### Added diff --git a/plugins/issue-driven-dev/skills/idd-reorganize/SKILL.md b/plugins/issue-driven-dev/skills/idd-reorganize/SKILL.md new file mode 100644 index 0000000..50e99dc --- /dev/null +++ b/plugins/issue-driven-dev/skills/idd-reorganize/SKILL.md @@ -0,0 +1,114 @@ +--- +name: idd-reorganize +description: | + 當上游 artifact（issue framing / diagnosis / spec）被判定錯誤時，有意識地讓修正**向下傳播**：列出所有建立在它之上的下游產物，逐一裁定「仍然有效 / 需重做 / 作廢」，並留下 re-baseline 紀錄。 + Use when: 走到一半發現「前面就錯了」—— root cause 選錯、scope 切錯、spec 凍進錯誤假設、或多個 issue 糾纏需要重切。 + 防止的失敗：只改上游那一處文字，而下游已經建在舊版本上的 diagnosis / plan / spec / PR 悄悄留著錯誤前提繼續走。 +argument-hint: "#issue [--artifact issue|diagnosis|plan|spec] [--reason '<一句話>']" +allowed-tools: + - Bash(gh:*) + - Bash(git:*) + - Read +--- + +# /idd-reorganize — 上游錯了，讓修正向下傳播 + +## 核心原則 + +> IDD 是 append-only 的鏈：`issue → diagnose → (plan | spec) → implement → verify → close`。每個 artifact 都建立在前一個之上，所以**上游一錯，下游全部繼承並放大**。 +> +> `idd-edit` 改的是**一處文字**；本 skill 處理的是**結構性**的錯 —— 修正必須被推到每一個已經建在錯誤前提上的地方，否則它們會安靜地繼續走。 + +## 何時用（與相鄰工具的分界） + +| 情境 | 用 | +|---|---| +| 一處措辭、typo、補一句說明 | `/idd-edit` | +| 進度 / phase / checklist 同步 | `/idd-update` | +| **上游 artifact 的前提錯了，下游已經建在它上面** | **本 skill** | +| 只是實作沒寫好，前提沒問題 | 照常 `/idd-implement` 修 | + +判準一句話：**問題出在「我們當初理解錯了什麼」，而不是「我們寫壞了什麼」時，用這個。** + +## Execution + +### Step 0: Bootstrap Stage Task List（強制） + +``` +TaskCreate(name="name_the_wrong_artifact", description="Step 1: 明確指出哪一個上游 artifact 錯了（issue framing / diagnosis 的 root cause / Strategy / plan / spec 的某條 acceptance criterion），以及它錯在哪 —— 一句話，不是一段") +TaskCreate(name="enumerate_downstream", description="Step 2: 機械枚舉所有建立在它之上的產物：後續 comment、plan、spec/proposal/tasks、branch、PR、已 merge 的 commit、以及引用本 issue 的其他 issue") +TaskCreate(name="adjudicate_each", description="Step 3: 逐一裁定 still-valid / redo / invalidate，每一項都要寫理由（無理由的裁定等於沒裁定）") +TaskCreate(name="post_rebaseline_record", description="Step 4: post 一則 ## Re-baseline comment，記錄錯在哪、影響了什麼、每一項的裁定與理由") +TaskCreate(name="execute_redo", description="Step 5: 對判為 redo 的項目，依其類型 chain 到對應 skill（diagnosis → /idd-diagnose；plan → /idd-plan；spec → /spectra-propose）") +TaskCreate(name="sync_phase", description="Step 6: /idd-update 把 phase 退回到重做的起點（例如 diagnosis 重做 → phase 退回 created）") +``` + +完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規。** + +### Step 1: 指名錯的那一個 artifact + +**一句話說清楚錯在哪。** 「diagnosis 不夠好」不算；「diagnosis 把 root cause 判成分類器的 regex，實際上在取得層」才算。 + +若說不出一句話，代表還沒診斷完 —— 先回去 `/idd-diagnose`，不要用本 skill 掩蓋一個還沒想清楚的判斷。 + +### Step 2: 枚舉下游（機械，不憑印象） + +```bash +gh issue view $N --repo $REPO --json comments --jq '.comments[] | "\(.createdAt[0:10]) \((.body | split("\n")[0])[0:70])"' +gh pr list --repo $REPO --state all --search "in:body \"#$N\"" # 精確比對見 references/pr-issue-matching.md +git log --oneline --grep "#$N" +ls openspec/changes/*/ 2>/dev/null # spec-driven 路徑的產物 +gh issue list --repo $REPO --state all --search "#$N" # 引用本 issue 的其他 issue +``` + +**枚舉要機械**。憑印象列下游，正是 #200 要修的那個失敗 —— 漏掉的那一項不會舉手。 + +### Step 3: 逐一裁定 + +| 裁定 | 意義 | 必須附 | +|---|---|---| +| `still-valid` | 該產物不依賴錯掉的那個前提 | **為什麼不依賴** —— 這是最容易搞錯的一格 | +| `redo` | 依賴了，且要重做 | 從哪一步重做 | +| `invalidate` | 依賴了，且不該存在了（例如整條 branch 走錯方向）| 怎麼處置（關 PR？revert？留著加註？）| + +**`still-valid` 要最嚴格地審。** 「看起來沒關係」是這個 skill 最常見的失效方式：下游產物往往在不明顯的地方繼承了上游的前提（一句措辭、一個測試的斷言理由、一段 CHANGELOG 的因果敘述）。 + +### Step 4: Re-baseline 紀錄 + +```markdown +## Re-baseline + +### 錯的是什麼 +{哪一個 artifact，錯在哪 —— 一句話} + +### 為什麼現在才發現 +{誠實寫。「verify 第 N 輪抓到」「實作到一半撞到」「使用者指出」都可以，重點是留下這個訊號給下次} + +### 下游影響與裁定 +| 產物 | 裁定 | 理由 | +|---|---|---| +| ... | still-valid / redo / invalidate | ... | + +### 重做起點 +{phase 退回到哪裡，下一個指令是什麼} +``` + +**「為什麼現在才發現」這一欄不可省。** 它是唯一會累積成「我們的上游錯誤都長什麼樣」的資料 —— 而那正是 MANIFESTO「設計階段的抽象度，作者自己看不出來」那條規則的證據來源。 + +### Step 5–6: 執行重做、退回 phase + +依裁定 chain 到對應 skill，並用 `/idd-update` 把 phase 退回重做的起點。**phase 必須真的退回** —— 留在 `implemented` 而實際上 diagnosis 正在重做，會讓 `/idd-list` 與 `/idd-close` 對這張 issue 說謊。 + +## 鐵律 + +- **不用本 skill 掩蓋「還沒想清楚」。** Step 1 說不出一句話就回去 diagnose。 +- **枚舉必須機械。** 憑印象列下游 = 重演本 skill 要修的失敗。 +- **`still-valid` 要寫理由。** 沒有理由的 still-valid 就是沒有裁定。 +- **不刪除既有 artifact。** 錯的 diagnosis 留著並標記為 superseded，不要抹掉 —— 「當時為什麼那樣想」是下次的資料。 +- **phase 要退回。** 否則工具鏈會對這張 issue 說謊。 + +## 實例（本 repo，PR #297） + +`#295` 的 diagnosis 判定 root cause 是「marker 的比對方式」，Strategy 是「分四類 + 解析 markdown」。走到第五輪，維護者裁定**拆掉 parser**；走到第七輪才發現真正的 root cause **根本不在分類器**，在 `gh` 的取得層（只回最舊 100 則 comment）。 + +下游影響：diagnosis 的 Strategy、四輪的測試斷言理由、CHANGELOG 的因果敘述、以及散文 reader 對「判準是什麼」的四份描述，全部建立在那個錯誤的 root cause 上。那次是**人工**逐一回頭修的 —— 而「散文與實作分岔」連續四輪復發，正是因為沒有一個機制在推動這種傳播。這張 skill 就是要讓那件事變成一個有步驟、有紀錄的操作。