# 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。 --- ## 交接 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 ，禁 -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-.md（trade-off 取捨理由） 13. 重型 bug / 跨域問題 → docs/issues/pending/YYYY-MM-DD-.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 設計 謝謝。 ``` --- ## 收口清單（Session A 端） 本 handoff prompt commit 後，新 session 接手即可： 1. 讀 5 個必讀文件（design-A3 / handoff prompt 兩份 / plan-A1 / plan-A2 / requirement-understanding） 2. invoke superpowers:writing-plans 3. 對齊 design-A3.md §12 + §8 寫 plan 4. Plan review loop + user review 5. commit plan.md + 產 Session B→C handoff ## 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。 ## Session A 規範遵守 - [x] 顯式 `git add` 顯式檔名 - [x] design.md commit 含 `Co-Authored-By: Claude Opus 4.7 (1M context)` footer - [x] jedi-oscal 沒動 - [x] `pyproject.toml` dev-path 不 commit - [x] DDD 規範 design 內貫徹（matcher domain layer / 不開 transaction） - [x] 2 輪 spec review（subagent verdict: Approved） - [x] User 拍板 brainstorm dump 排序（留 Session E） - [x] Handoff prompt 放對位置（`docs/features/<feature>/handoff/`，CLAUDE.md 2026-05-20 新規）