Handoff Prompt — A3 Session A → Session B（writing-plans）

使用方式：把下方「交接 prompt 本體」整段貼到新 session 即可接手。 前置狀態：Session A（brainstorm + design + spec review）完成；design-A3.md shipped + 兩輪 spec review approved；working tree 乾淨（除 pre-existing pyproject.toml + 既有 conversation-history zip 異動）。 Session B 任務：invoke superpowers:writing-plans skill → 產 implementation-plan-A3.md + plan review + user review → commit。

§1

交接 prompt 本體（從此貼到新 session）

我要進 SSP 匯入匯出 Phase 2 / A3 phase Session B — writing-plans。

前置狀態
========

Branch: feature/ssp-import-export-phase2（BE，32 commits 未 push）
- A0 / A0.1 / A1 / A2 都 shipped；A3 design 已 ship（Session A）
- Session A 累計 2 commits：
  - 8e61def docs(ssp-import-export-phase2): A3 design.md — 共用 matcher 抽取（parties / org-units）
  - 6e0f103 docs(ssp-import-export-phase2): A3 design.md spec review fix — iteration 1
- 工具狀態：jedi-oscal 仍 path-dep；pyproject.toml dev-path 改動仍未 commit
- Test 基準：BE 既有 205 passed（A1 106 + A2 99）；A3 unit test 待 Session C 落地

A3 Session B 是 5 session 切分中的第 2 站，task：
  invoke superpowers:writing-plans skill
  → 產 implementation-plan-A3.md
  → plan review loop
  → user review
  → commit
  預估 0.25d

開工 SOP
========

第一步：必讀文件（順序）

1. docs/features/FR-011.2-2605-ssp-import-export-phase2/design-A3.md
   ← A3 完整 design，13 章 / ~670 行
   ← 重點看 §12 執行階段切分 5 session（T0-T7 task 拆解）
   ← §8 Acceptance Criteria 是 plan 必對的 ship 條件
   ← §13 brainstorm 拍板溯源（Q1-Q6 + Q3'/Q4'）
2. docs/features/FR-011.2-2605-ssp-import-export-phase2/handoff/2026-05-20-a3-brainstorm-kickoff.md
   ← Session A kickoff handoff（含預估規模 / 跨 repo 影響）
3. docs/features/FR-011.2-2605-ssp-import-export-phase2/implementation-plan-A2.md
   ← 樣板參考 — A2 plan 體例（T0~T8 拆 task + 預估 + 依賴）
4. docs/features/FR-011.2-2605-ssp-import-export-phase2/implementation-plan-A1.md
   ← 第二樣板 — A1 plan 體例
5. docs/features/FR-011.2-2605-ssp-import-export-phase2/requirement-understanding.md
   ← §6.2 Track A 階段表 A3 row（line 434）+ §6.4 A3 ship 條件（line 480）

讀完後給「我看完了，建議下一步 X」的簡短確認。

第二步：invoke superpowers:writing-plans skill

按 skill 流程：
1. skill 會引導切 phase / task / subtask 結構
2. 對齊 design-A3.md §12 5 session 切分（A 已完成；B 是 self；C / D / E 是 implementation sessions）
3. T0~T7 task 拆解對齊 design §12 表：
   - T0 verify（已部分完成於 Session A pre-flight，新 plan 內標已完成項目）
   - T1 抽 BaseReconciliationService + reconcilers + ParsedParty
   - T2 docx path 切換 + 門面化 + DI wiring
   - T3 A2 _confirm_*_flow 補 reconcile() 串接
   - T4 fuzzy 演算法（_strip_plus_alias / _strip_org_suffix / candidate cache）
   - T5 unit test + integration test 擴充
   - T6 cucumber regression scenario（跨 compliance-manager-test repo）
   - T7 changelog + tracker + design §11 reconciliation + final SUMMARY
4. 每個 T 列：subtask / 工時 / 依賴 / DoD / 涉及檔案
5. 加 pre-flight verification 段（plan 階段 implementer 開工前要再 verify）
6. 落地後 dispatch plan reviewer subagent（mirror Session A spec review pattern）

第三步：路徑 override（CLAUDE.md 規範）

implementation-plan-A3.md 寫到：
  docs/features/FR-011.2-2605-ssp-import-export-phase2/implementation-plan-A3.md
（不是 docs/superpowers/plans/）

第四步：commit message style

落地後 commit：
  docs(ssp-import-export-phase2): A3 implementation-plan.md — 共用 matcher 抽取執行計畫

review 修補 iteration commit：
  docs(ssp-import-export-phase2): A3 implementation-plan.md plan review fix — iteration N

第五步：跨 session 接續

plan.md user review approved 後，產 handoff prompt 給 Session C（架構抽出 + docx 切換）：
  docs/features/FR-011.2-2605-ssp-import-export-phase2/handoff/2026-05-XX-a3-session-B-to-C-implementation.md
然後給 user final SUMMARY，等 user GO 換 session。

A3 Session A 已產出（參考）
============================

design-A3.md 13 章：
  §1 為什麼要做 A3（含 issue 修補關係）
  §2 範圍 / 不在範圍（含 F1~F7 follow-up）
  §3 Architecture（file 結構 + BaseReconciliationService + 門面）
  §4 Data Structures（MatchMethod enum + ParsedParty 加欄位 + confidence 表）
  §5 Fuzzy Match 演算法（Person / Organization 三階段降級 + normalize helpers）
  §6 Caller 切換 + DI wiring（含 docx 兩處 reconcile）
  §7 Pre-flight Verification 結果（5 項假設驗證）
  §8 Acceptance Criteria（A3 ship 條件 + partial ship 允許）
  §9 風險與緩解（R1-R7）
  §10 跨 repo 工作
  §11 Implementation Reality / Reconciliation（implementation 時填）
  §12 執行階段切分（5 session 切法 + commit checkpoint）
  §13 設計決策溯源（brainstorm Q1-Q6 + Q3'/Q4' 拍板理由）

8 題 brainstorm 拍板摘要：
  Q1 A — domain/oscal/service/reconciliation/ sub-folder
  Q2 B — 三態 matched/fuzzy/unmatched + fuzzy 必進 user 確認
  Q3 A — 直接切換，cucumber regression 守
  Q4 B — Normalize + email domain (person) / name prefix (org)
  Q4' A — Client-side filter（拉全 tenant list，A3 不動 jedi-auth）
  Q5 A — 不整併 issue 修補 B（role normalize）
  Q6 A — Strategy Pattern + Generic Base
  Q3' A — A3 順手串 A2 _confirm_*_flow

鐵律（沿用 A0.1 + A1 + A2 + Session A 全部）
=============================================

1. 顯式 git add <file>，禁 -am / -A — commit 前 git status --short 確認
2. jedi-oscal 維持 path-dep，不 bump 版本不推 Nexus（Phase 2 整體完工才 bump）
3. pyproject.toml dev-path 改動不該 commit
4. BE 重啟必 lsof -ti:8000 | xargs kill -9
5. 改 BE service code 後必提醒 user 重啟 — BE 沒 hot reload
6. DDD 嚴格分層 — Route 不碰 DB，App Service @transaction，純函式 helper / matcher 不接 DB
7. 不寫 docstring / 註解除非真有 non-obvious 的 why
   - A3 例外：BaseReconciliationService hook docstring 屬「non-obvious why」
8. Test 用 mock 包 logger 避開 jedi DBLogHandler 撞 SessionLocal=None；@transaction 用 patch_session_scope
9. plan 階段假設不準確時主動修 design.md (§11 reconciliation)
10. 跨 repo 切換時提醒 user：cucumber 在 compliance-manager-test repo，commit / branch 分開
11. 改 docx parser 既有行為 → cucumber regression 必跑 — 是 ship 必要條件
12. 重大決策 → docs/analysis/YYYY-MM-DD-<topic>.md（trade-off 取捨理由）
13. 重型 bug / 跨域問題 → docs/issues/pending/YYYY-MM-DD-<title>.md（不擠在 changelog）
14. Handoff 文件統一放 docs/features/<feature>/handoff/（CLAUDE.md 2026-05-20 新規）
15. brainstorm dump 留 Session E 收口才一次 dump 到 docs/conversation-history/<date>/ssp-import-export-phase2/
    （user 拍板：等 task arc 收口才 dump，不跨 session 立即落地）

A3 phase 預估規模（剩餘）
========================

| Session | 範圍 | Task | 預估 |
|---------|------|------|------|
| B（self）| writing-plans | invoke skill + 產 plan + review + user review | 0.25d |
| C | 架構抽出 + docx 切換 | T1 + T2 | ~1d |
| D | A2 串接 + fuzzy 演算法 | T3 + T4 | ~0.75d |
| E | Test + cucumber + 收尾 | T5 + T6 + T7 | ~1.25d |

剩餘總計：~3.25d

工具預期
========

- superpowers:writing-plans skill（主）
- Plan review subagent（mirror Session A spec review pattern，dispatch general-purpose agent 扮演 plan reviewer）
- Read design-A3.md 各章節對齊 task 設計

謝謝。

§2

收口清單（Session A 端）

本 handoff prompt commit 後，新 session 接手即可：

讀 5 個必讀文件（design-A3 / handoff prompt 兩份 / plan-A1 / plan-A2 / requirement-understanding）
invoke superpowers:writing-plans
對齊 design-A3.md §12 + §8 寫 plan
Plan review loop + user review
commit plan.md + 產 Session B→C handoff

§3

Session A 累計 commits（feature/ssp-import-export-phase2）

6e0f103  docs(ssp-import-export-phase2): A3 design.md spec review fix — iteration 1
8e61def  docs(ssp-import-export-phase2): A3 design.md — 共用 matcher 抽取（parties / org-units）

外加本 handoff prompt + tracker README 更新 commit。

§4

Session A 規範遵守

顯式 git add 顯式檔名
design.md commit 含 Co-Authored-By: Claude Opus 4.7 (1M context) footer
jedi-oscal 沒動
pyproject.toml dev-path 不 commit
DDD 規範 design 內貫徹（matcher domain layer / 不開 transaction）
2 輪 spec review（subagent verdict: Approved）
User 拍板 brainstorm dump 排序（留 Session E）
Handoff prompt 放對位置（docs/features/<feature>/handoff/，CLAUDE.md 2026-05-20 新規）