| name | aibdd-form-bdd-analysis |
| description | 系統抽象驅動的 BDD 分析（Reconciler）。從已確認的 .feature Rule 骨架推導系統抽象、 實體句型模型與覆蓋矩陣，再據此產出最小必要句型集的 .feature 檔案（含 Examples）。 以 desired-state reconciliation 模式運作：三階段各自讀取現有 artifact → 推導 desired state → 計算 diff → 增量更新。Greenfield 時 current = 空。 善用 Scenario Outline + Examples 做 Data-Driven 測試， 善用 Data Table 承載結構化輸入與驗證。 支援 Boundary 偵測——偵測到 Web Backend 時載入內建 preset（句型分析方針 + Handler 決策樹）。 由 @zenbu-powers:clarifier 在 Phase 03（BDD Analysis）親自呼叫， 或由 /zenbu-powers:aibdd-carry-on-engineering-plan 執行 Phase 03 卡片時觸發。
|
BDD 分析：系統抽象驅動的可執行規格產出（Reconciler）
從已確認的 .feature Rule 骨架出發，經三階段推導，產出最小必要句型集的 .feature 檔案（含具體 Examples）。
Reconciler 合約：啟動時 Read aibdd-core/references/reconciler-contract.md，全程遵循。本 skill 為嵌套式 reconciler，三階段（系統抽象 / 句型模型 / Examples）各自完整走完 contract 6 步流程，前綴採 Phase N - Step M 形式。
核心概念：Boundary → Operation → Handler
| 層級 | 定義 | 範例 |
|---|
| Boundary | 要測試的系統邊界 | web-backend（後端 API + DB） |
| Operation | 該邊界上可測試的操作 | 每個 API endpoint |
| Handler | 每種 Gherkin 句型對應的測試部位 | 6 種 web-backend handler |
4 種抽象測試角色（系統無關）
| 角色 | Gherkin 位置 | 職責 |
|---|
| States Prepare | Given | 直接注入狀態，繞過系統邊界 |
| Operation Invocation | Given / When | 調用系統操作 |
| Operation Result Verifier | Then | 驗證操作的直接輸出 |
| States Verify | Then | 驗證操作後的系統內部狀態 |
與非腦補原則的關係
Examples 可從已確認的 Rule 系統性推導——這是分析，不是腦補。
- Rule 已確認 → 可推導 Examples
- Rule 未確認（仍有 CiC） → 不可推導
- Rule 不存在 → 不可編造
輸入
- features 資料夾路徑：
${FEATURE_SPECS_DIR}
- 已確認的 .feature 檔案：含 Rule 骨架、已解決所有 CiC
- Execution Plan scope：哪些 domain 需要分析（create/modify）
- Clarify Session：
${CLARIFY_DIR} 中的澄清紀錄
產出結構
${FEATURE_SPECS_DIR}/
├── 系統抽象.md # Phase 1
├── {domain}/
│ ├── 句型.md # Phase 2
│ └── *.feature # Phase 3
└── ...
三階段串接概觀
每個階段都是獨立的 reconciler：derive desired → read current → diff → preview → apply → output。階段之間以 IMPL_IMPACT 與 scope 繼承串接。
Phase 1：系統抽象 Reconciliation
└── Step 1-6 完整走完 → 展示 → 等待使用者審核
1.5 Boundary 偵測（Phase 1 完成後、Phase 2 開始前的橋接）
├── 有 erm.dbml → boundary = web-backend
│ → Read references/web-backend/句型分析方針.md
│ → 後續句型分類使用 web-backend Handler 決策樹
└── 其他 → 使用通用推導（4 抽象角色框架，無 preset）
確認目標 domain（從 scope + features/ 子目錄推導）
Phase 2：句型模型 Reconciliation（per domain）
└── 對每個 scope domain，Step 1-6 完整走完 → 展示 → 等待使用者審核
2.5 共用句型萃取（僅多 domain 時觸發，所有 Phase 2 完成後執行）
├── 條件：scope 內有 2+ domain
│ ├── 掃描所有 domain 句型.md，找出句型文字完全相同的句子
│ ├── 搬至系統抽象.md 共用句型 section
│ └── 各 domain 句型.md 替換為引用（→ 見系統抽象 G1）
└── 只有 1 個 domain → 跳過，不萃取共用句型
Phase 3：Feature Examples Reconciliation
└── Step 1-6 完整走完 → 展示摘要 → 等待使用者審核
階段間的 Scope 繼承與 IMPL_IMPACT 傳播
- Scope 繼承：Phase 1 確立的「受影響 domain 清單」由 Phase 2 / Phase 3 沿用，下游不可自行擴張或縮減 scope。
- IMPL_IMPACT 傳播：Phase 1 / Phase 2 的 change_summary 中 IMPL_IMPACT 條目，會被 Phase 3 在 Step 1 Derive 時讀取並納入自己的 desired state（例如系統抽象變更 → 連動句型變更 → 連動 Examples 變更）。
- 中斷恢復：任一 Phase 的 Step 5 中斷時寫入
.reconciler-state.json，下次啟動同 Phase 時讀取續跑，跳過 Step 1-4。
Reconciliation 流程
Phase 1 - Step 1: Derive Desired State（系統抽象）
從所有 scope 內 .feature 推導「features/系統抽象.md 應該長什麼樣」。
推導步驟（嚴格按順序）
- 辨識操作 — 從所有 scope 內 .feature 的 Rule 列舉所有對外操作
1b. 拆解系統前置狀態 — 從操作的 Rule 反推狀態部件
- 辨識實體 — 從操作反推 Aggregate 或 Gateway
- 操作分類 — 按行為形狀分群（Creation / Mutation / Query / Diagnostic）
- 萃取共用契約 — 跨 domain 重複的 postcondition、violation、I/O 模式
- 辨識變異點 — 各 domain 特有行為
句型不在此階段萃取。 句型的 single source of truth 在各 domain 的句型.md（Phase 2）。
只有在 Phase 2.5（所有 domain 分析完成後）才萃取真正跨 domain 共用的句型。
輸出格式
Read assets/system-abstraction.template.md 取得模板。
Phase 1 - Step 2: Read Current State（系統抽象.md）
讀取 ${FEATURE_SPECS_DIR}/系統抽象.md。
- 不存在（greenfield）→ current = 空集，全部 desired 元素都是
create
- 存在 → parse 出操作清單、實體清單、操作分類、共用契約、變異點
格式異常時，依 contract Failure Handling 視為 empty current 但 REPORT 警告。
Phase 1 - Step 3: Compute Diff
| 類型 | 條件 | 範例 |
|---|
| modify | 既有操作分類變更 | Lead scoring 從 Query → Mutation |
| modify | 共用句型需更新 | 新增共用 Given 句型 |
| create | 新操作 | scoring-rules 操作 |
| create | 新共用契約 | 新 violation pattern |
Phase 1 - Step 4: Preview
依 contract 通用格式展示 diff，使用者選 (P) Proceed / (E) Edit scope / (Q) Question。
Phase 1 - Step 5: Apply with Clarify
先改後增：modify → create → delete（需確認）。
衝突解決依 contract 優先序：使用者直接 input > AI 推導；既有 CiC 標記強制走 clarify-loop；delete 永遠需使用者確認。
Phase 1 - Step 6: Output
寫入更新後的 系統抽象.md，回傳 change_summary（含 IMPL_IMPACT），交給 Phase 1.5 Boundary 偵測。
Phase 2 - Step 1: Derive Desired State（句型模型）
對每個 scope 內的 domain，從該 domain 的所有 .feature 推導「features/{domain}/句型.md 應該長什麼樣」。
推導步驟
- 句型分類：
- 若 boundary = web-backend：Read
references/web-backend/句型分析方針.md，用 Handler 決策樹分類
- 若無 preset：使用 4 抽象角色從行為形狀推導
- 列舉操作與參數 — 提取 When Data Table、Then Data Table、violation_type
- 產出完整句型清單 — 該 domain 所需的 Given / When / Then 全部列於此，不分繼承/專屬
- QA 分析 — Read
references/qa-analysis-guide.md，五維分析
- Scenario 結構決策 — Read
references/feature-writing-rules.md Rule 5
- 產出覆蓋矩陣
句型清單是 single flat list。 不分「繼承自系統層」與「本 domain 專屬」。
所有該 domain 需要的句型統一列出，避免與系統抽象.md 的資料重複。
輸出格式
Read assets/sentence-model.template.md 取得模板。
Phase 2 - Step 2: Read Current State（{domain}/句型.md）
對每個 scope 內的 domain，讀取 ${FEATURE_SPECS_DIR}/{domain}/句型.md。
- 不存在（greenfield）→ current = 空集
- 存在 → parse 出句型清單、QA 分析、覆蓋矩陣
Phase 2 - Step 3: Compute Diff
| 類型 | 條件 | 範例 |
|---|
| modify | 既有句型需新增參數 | Lead 的 Given 加 score 欄位 |
| modify | 覆蓋矩陣需更新 | 新增 scoring 相關的 Then 句型 |
| create | 新 domain | journey/ 全新分析 |
| create | 既有 domain 新句型 | lead/ 加 scoring 句型 |
Phase 2 - Step 4: Preview
依 contract 通用格式展示 diff（per domain），使用者選 (P) / (E) / (Q)。
Phase 2 - Step 5: Apply with Clarify
先改後增：modify → create → delete（需確認）。
每個 domain 完整走完 5 → 6 後，才進入下一個 domain 的 Phase 2。所有 domain 完成 Phase 2 後，觸發 2.5 共用句型萃取（僅多 domain）。
Phase 2 - Step 6: Output
寫入更新後的 {domain}/句型.md，回傳 change_summary（含 IMPL_IMPACT），準備傳給 Phase 3。
Phase 3 - Step 1: Derive Desired State（Feature Examples）
對每個 scope 內的 .feature 檔案，從句型.md + QA 五維分析推導「.feature 應該長什麼樣」（含具體 Examples）。
撰寫規則
Read references/feature-writing-rules.md 取得完整 9 條規則。
填入策略
對每個 scope 內的 .feature 檔案：
- 保留所有已確認的 Rule（不修改 Rule 文字）
- 移除
# ⚠ Example 區段 標記
- 移除
@ignore tag
- 依句型.md 的覆蓋矩陣填入 Scenario Outline / Scenario + Examples
- Data Table 欄位名與 Rule 確認的欄位 1:1 對應
- Examples 從 QA 五維分析推導，使用具體值（Spec by Example）
Feature File 結構
Read assets/feature-file.template.gherkin 取得模板。
Phase 3 - Step 2: Read Current State（.feature）
讀取每個 scope 內的 .feature 檔案。
- 僅有 Rule 骨架（@ignore） → current 視為「等待填 Examples」
- 已有舊 Examples → parse 出既有 Scenario Outline / Scenario / Examples table
Phase 3 - Step 3: Compute Diff
| 類型 | 條件 | 範例 |
|---|
| modify | 既有 Scenario 的 Examples 需更新 | Lead 建立加 score 欄位 |
| create | 新 Scenario Outline | Journey 的所有 scenarios |
| delete | 不再需要的 Example 行 | 需使用者確認 |
Phase 3 - Step 4: Preview
依 contract 通用格式展示 diff（per .feature），使用者選 (P) / (E) / (Q)。
Phase 3 - Step 5: Apply with Clarify
先改後增：modify → create → delete（需確認）。Example 行的 delete 永遠需使用者確認。
Phase 3 - Step 6: Output
寫入更新後的 .feature 檔案，回傳 change_summary（含 IMPL_IMPACT 表，見下節）。這是整個 BDD 分析最關鍵的 IMPL_IMPACT 來源。
IMPL_IMPACT 產出規則
Phase 3（Feature Examples）的每個 modify 操作評估對 implementation 的影響。這是最關鍵的 IMPL_IMPACT 來源——Gherkin 句型變更直接影響 Step Definitions。
| .feature Diff | Impact Type | Phase | 影響目標 |
|---|
| Given datatable +column | DATATABLE_SCHEMA | 05 | Step Def 的 table 解析（欄位數變更） |
| Given datatable -column | DATATABLE_SCHEMA | 05 | Step Def 的 table 解析 + 可能影響 Model |
| Given 句型文字變更 | SENTENCE_PATTERN | 05 | Step Def pattern/regex 斷裂 |
| When 參數增刪 | SENTENCE_PATTERN | 05 | Step Def 的 When handler 參數解析 |
| When 句型文字變更 | SENTENCE_PATTERN | 05+06 | Step Def + Frontend 操作觸發點 |
| Then datatable +column | DATATABLE_SCHEMA | 05 | Step Def 的 Then 驗證邏輯 |
| Then 句型文字變更 | SENTENCE_PATTERN | 05 | Step Def pattern/regex 斷裂 |
| Examples +row | （無 IMPL_IMPACT） | — | 新 test case，既有 Step Def 不受影響 |
| Examples -row | （無 IMPL_IMPACT） | — | 少跑一個 case，不影響 implementation |
| 新 Scenario Outline（create） | NEW_OPERATION | 05 | 需要新 Step Def（若句型是新的） |
關鍵判斷：只有句型結構（Given/When/Then 的文字 pattern 或 DataTable schema）變更才產出 IMPL_IMPACT。Examples 行的增減不影響 implementation（Step Def 是 parameterized 的）。
change_summary 中附帶 IMPL_IMPACT 表，格式見 aibdd-core/references/reconciler-contract.md。
規則
- 先分析再產出。 絕不跳過系統抽象和句型模型直接填 Examples。
- 每一層都需使用者審核。 系統抽象.md → 確認 → 句型.md → 確認 → .feature → 確認。
- 句型.md 是 .feature 的 single source of truth。
- 不發明無依據的句型。 必須追溯到系統抽象的行為分類。
- QA 分析不可省略。 五維分析，即使不適用也要標註。
- 具體資料，不用白話。 Spec by Example。
- Rule 已確認才可推導。 只從已通過 CiC 歸零的 Rule 推導 Examples。
- Reconciler 先改後增。 modify 既有 artifacts 先於 create 新 artifacts。
- Scope 限定。 只處理 Execution Plan 標記的 domain，不動未受影響的 artifacts。
- IMPL_IMPACT 必須評估。 每個 modify 操作的 change_summary 必須包含 IMPL_IMPACT 標記。
Hand-off / Next Agent
完成後交還呼叫者，回傳 change_summary（含 IMPL_IMPACT）：
- clarifier 路徑：回報 clarifier，由其接續 Phase 04 呼叫
/zenbu-powers:aibdd-form-api-spec
- carry-on 路徑：REPORT 給 carry-on，由 carry-on 進入該 Phase 的 Feedback Loop
- 獨立調用：直接回報使用者
