ticket

name	ticket
description	Use this skill whenever the user wants to create, track, query, or manage tickets. Triggers include: creating new tickets, claiming or releasing tickets, checking ticket status or progress, completing tickets, handing off work between agents, resuming interrupted tasks, migrating tickets between versions, converting plans to tickets, or any mention of /ticket, task tracking, or ticket lifecycle operations.
argument-hint	<subcommand> [args]
allowed-tools	Bash(ticket *), Read, Write, Edit, Grep, Glob

Ticket System v1.0

統一 Ticket 系統 - 整合 create/track/handoff/resume/migrate/generate 六大功能。

---

執行方式

禁止直接執行 Python 檔案！ ticket_system 是 Python 套件，必須透過 pyproject.toml 定義的入口點執行。

全局安裝（推薦）

# 首次安裝
(cd .claude/skills/ticket && uv tool install .)

# 之後在任何目錄執行
ticket track summary
ticket track claim 1.0.0-W4-001

修改原始碼後必須重新安裝（IMP-023）：

# 必須用 --reinstall（--force 不會更新套件程式碼）
uv tool install .claude/skills/ticket --reinstall

本地執行

(cd .claude/skills/ticket && uv run ticket track summary)

常用範例

ticket track summary                                    # 摘要
ticket track query 1.0.0-W4-001                       # 查詢
ticket track claim 1.0.0-W4-001                       # 認領
ticket track complete 1.0.0-W4-001                    # 完成（auto-stage：自動 git add ticket md + worklog md + cascade children，stdout 提示 commit 指令）
ticket track complete 1.0.0-W4-001 --no-stage         # 完成但跳過 auto-stage（保留用戶手動掌控 stage 範圍，W11-035）
ticket track complete 1.0.0-W4-001 --force            # 強制完成（旁路未完成 children 阻擋，W11-003.2）
ticket create --version 0.31.0 --wave 4 --action "實作" --target "XXX"  # 建立

subagent 派發時 claim 推薦用法

被派發的 subagent 認領自身 ticket 時，推薦使用裸 ticket track claim <id>（不加任何旗標）。

Why：裸 claim 走預設路徑，不執行 AC 驗證、不讀 stdin、不偵測 TTY，metadata 寫入在 file_lock 保護下為單一原子操作（load → modify → save），不存在「部分寫入」的中間狀態。subagent 無 TTY 的互動環境受限對裸 claim 完全無影響。

Consequence：若 subagent 改用 --verify（明示啟用 AC 自動驗證，僅供除錯場景），在無 TTY 環境下會觸發 fail-closed：未加 --yes 時直接 return 1 並印出「非互動環境且未指定 --yes，已取消」，subagent 可能誤判 ticket 未 claim 而重試或放棄。--verify 還會在 claim 時跑 AC 對應的驗證指令（如 npm test 全套件），造成同 wave 並行 claim 衝突（PC-078）。

Action：

場景	推薦命令	說明
subagent 認領被派發的 ticket（常態）	ticket track claim <id>	預設不驗證，原子寫入，無半成功風險
除錯時想 claim 並同時跑 AC 驗證	ticket track claim <id> --verify --yes	--yes 在非互動環境短路驗證 prompt 為 y，避免 fail-closed
只想看 AC 驗證結果不 claim	ticket track verify <id>	與 claim 解耦（W4-019 後 --skip-verify 已移除，改用此子命令）

半成功歷史背景：早期 claim --yes 在 subagent 無 TTY 環境曾因互動受限出現 metadata 部分寫入、需 --skip-verify 二次嘗試確認的半成功狀態（W1-048.4.1 觀察）。此 root cause 已由 W3-046（claim 預設不驗證）+ W4-019（移除 --skip-verify）兩階段修正消除；現行裸 claim 路徑無此問題。

---

無子命令時的預設行為（dashboard-first，v2.7.0 起）

當用戶輸入 /ticket（無子命令或參數）時，依序執行以下流程：

1. 取得接手聚合視圖 — 執行 ticket track dashboard --top 5

   dashboard 一次回傳 [In Progress] + [Ready Top N] + [Stale Warning] 三章節，Ready 章節含可直接 claim 的編號 [1] [2] [N] 與 priority 標籤。設計目的：將 PM 接手流程從 W10-113 baseline 7 tool call 降至 2-3 tool call（W3-013 ANA 結論方向 a）。

   • dashboard 有 in_progress 或 ready 任務 → 使用 AskUserQuestion 依 dashboard 順序列出選項：
     • in_progress 任務優先列出（label: [ip] {ticket_id} - {title}，description: 進行中（resume 接手））
     • Ready 任務依 dashboard [1] [2] [N] 編號順序列出（label: [{N}] {ticket_id} - {title}, description: [{priority}]）
     • 額外選項：「建立新 Ticket」（description: 執行 /ticket create）
     • 用戶選擇：
       • in_progress 任務 → ticket resume <selected_id>
       • Ready 任務 → ticket track claim <selected_id>
       • 建立新 Ticket → 引導進入 /ticket create 流程
     • 流程結束
   • dashboard 無 in_progress 也無 ready → 進入步驟 2 fallback

2. Fallback：完整 pending/in_progress 清單（僅當步驟 1 dashboard 無結果時觸發） — 執行 ticket track list --status pending,in_progress

   • 有待辦任務 → 使用 AskUserQuestion 列出選項：
     • 各待辦任務作為選項（label: {ticket_id} - {title}, description: 狀態: {status}）
     • 額外選項：「建立新 Ticket」（description: 執行 /ticket create）
     • 用戶選擇既有任務 → 依狀態處理（pending → claim，in_progress → resume）
     • 用戶選擇「建立新 Ticket」→ 引導進入 /ticket create 流程
     • 流程結束

3. 無任何待辦 → 顯示子命令總覽（下方表格）

完整待恢復清單檢視/除錯：可改用 ticket resume --list（子命令保留，獨立於 dashboard-first 流程）。 scheduler 接手建議單獨查詢：可改用 ticket track runqueue --context=resume --top 3（保留作除錯/腳本用途，但 PM 接手流程不再呼叫）。

---

統一命令格式

/ticket <subcommand> [options]

命令層級慣例：create / batch-create / show / handoff / resume / migrate / generate 是頂層命令（ticket create ...）；claim / complete / append-log / query / list / set-acceptance 等狀態操作在 track 之下（ticket track <op> ...）。常見誤打：ticket track create（錯，create 非 track 子命令）、ticket claim（錯，claim 在 track 下）。本標註僅說明既有慣例，零 CLI 行為變更（Never break userspace）。

子命令總覽

子命令	用途	範例
create	建立新 Ticket	/ticket create --version 0.31.0 --wave 1 --action "實作" --target "XXX"
batch-create	批次建立 Tickets	/ticket batch-create --template impl-parsley --targets "a,b,c" --wave 28
track	追蹤 Ticket 狀態	/ticket track summary
track dashboard	PM 接手聚合視圖（W10-114）	ticket track dashboard --top 5
track list	預設 top 10 priority 排序（W10-115）	ticket track list --status pending --top 20
track td-status	TD 清單校準（PC-094）	ticket track td-status 0.18.0-W10-017
track depth	查詢嵌套深度與 can_descend（W1-056.8，沿 parent_id 鏈）	ticket track depth 1.0.0-W1-056.5
track parallel-check	偵測子任務/兄弟 ticket 檔案衝突（W17-203.1，對齊 askuserquestion-rules 規則 7）	ticket track parallel-check 0.18.0-W17-203
track dispatch-validate	Context Bundle 自動填料合理性檢查（W17-003，C 方案安全網；exit 0=pass / 1=軟警告 / 2=硬失敗或 IO 錯誤；與 dispatch-check 的 exit code 語意不共享，需以命令名稱判別）	ticket track dispatch-validate 0.18.0-W17-003
track dispatch-readiness	派發前認知負擔閾值檢查（W17-053；三項閾值：功能職責數 / 修改檔案數 / Context Bundle tokens；exit 0=pass / 1=軟警告 / 2=強制拆分或 IO 錯誤；與 dispatch-check / dispatch-validate 的 exit code 語意不共享；閾值 1 以 acceptance 條目近似，含驗證類條目時可能高估，PM 於 WARN/FAIL 應手動覆核——詳見 references/track-command.md）	ticket track dispatch-readiness 0.18.0-W17-053
show	顯示 Ticket（含渲染）	ticket show W17-015 / ticket show W17-015 -r
handoff	任務交接	/ticket handoff 1.0.0-W1-002 --to-sibling 1.0.0-W2-003
resume	恢復任務	/ticket resume <id>
migrate	Ticket ID 遷移	/ticket migrate 1.0.0-W4-001 1.0.0-W5-001
generate	Plan 轉換為 Tickets	/ticket generate plan.md --version 0.31.0 --wave 5

---

子命令詳細說明

各子命令的完整用法和參數說明，請參閱對應的 reference 檔案：

create - 建立新 Ticket

建立 Atomic Ticket，支援 5W1H 引導式建立、子 Ticket 建立、版本目錄初始化（init）。

決策樹：Read references/workflow-create.md 詳細用法：Read references/create-command.md 血緣 vs 衍生：--parent vs --source-ticket 對比表見 references/create-command.md「--parent vs --source-ticket 對比表」章節（PC-073） 重複偵測：Tier 1 警告層（相似度 >= 0.3，不阻擋）+ Tier 2 阻擋層（同窗口高相似度 exit 1，--allow-duplicate 旁路）；見 references/create-command.md「重複偵測（兩層防護）」章節（W1-040.1 冪等防護）

常用範例：

# 建立根任務（必須提供 decision-tree 三參數）
ticket create --version 0.2.0 --wave 2 --action "實作" --target "HTTP Handler" --type IMP \
  --decision-tree-entry "第五層:TDD" \
  --decision-tree-decision "Phase 3b 完成後建立重構 Ticket" \
  --decision-tree-rationale "quality-baseline-rule-5"

# 建立子任務（--parent 自動產生子序號，可省略 decision-tree 參數）
ticket create --parent "1.0.0-W2-001" --action "實作" --target "事件融合層"

# DOC 類型（可省略 decision-tree 參數）
ticket create --version 0.2.0 --wave 2 --action "撰寫" --target "工作日誌" --type DOC

# 多值參數格式
#   --acceptance：多次指定或用分隔符（vertical bar）分隔
ticket create ... --acceptance "條件A" --acceptance "條件B"
ticket create ... --acceptance "條件A|條件B|條件C"
#   注意（W3-089）：分隔符是 --acceptance 的多條拆分字元。
#   若 acceptance 內文本身需含該字元（如描述 shell pipe「-q | tail」），
#   用反斜線跳脫保留字面，避免被靜默拆條：
ticket create ... --acceptance "重現實證 -q \| tail 導致 0 行"
#   未跳脫時，單一 --acceptance 值被拆成多條會印出 [WARNING] 供確認。

#   --where：逗號分隔
ticket create ... --where "file1.py,file2.py"

#   --blocked-by / --related-to：逗號分隔
ticket create ... --blocked-by "1.0.0-W2-001.1,1.0.0-W2-001.2"

batch-create - 批次建立 Tickets

從模板 + 目標清單快速建立多個 Tickets。適用於大量同質任務場景（如 30 個實作子任務）。

邊界：batch-create 只建立 tickets，不派發 agents。多任務派發前先寫 dispatch-plan，保留每張 ticket 的獨立 prompt、commit policy 與 Exit Status；禁止把 batch-create 誤用為 batch dispatch CLI。

使用情境：

• W28 場景：快速建立 30 個相同類型的實作任務
• 需要多個同質 Ticket，避免逐一手工填寫

命令格式：

# 基本用法
ticket batch-create --template impl-parsley --targets "目標1,目標2,目標3" --wave 28

# 指定版本
ticket batch-create --template impl-parsley --targets "a,b,c" --version 0.31.0 --wave 28

# 預演模式（只顯示摘要，不建立檔案）
ticket batch-create --template impl-parsley --targets "a,b,c" --dry-run

# 建立子任務
ticket batch-create --template impl-parsley --targets "a,b" --parent 1.0.0-W28-001

參數說明：

• --template (必填)：使用的模板名稱（如 impl-parsley）
• --targets (必填)：目標清單，逗號分隔（如 "BookCard Widget,LibraryListPage"）
• --version (可選)：目標版本，預設自動偵測
• --wave (可選)：Wave 編號，預設為 1
• --parent (可選)：父 Ticket ID，用於建立子任務
• --dry-run：預演模式，只顯示摘要不建立檔案

預定義模板：

• impl-parsley：parsley-flutter-developer 實作 Ticket 模板（type: IMP, who: parsley-flutter-developer）
• 更多模板可在 ticket_system/templates/ 目錄中定義

詳細設計：參考評估報告（CLI 設計、使用者體驗、批次操作流程）

track - 追蹤和更新 Ticket 狀態

包含 READ 操作（summary/query/version/tree/chain/deps/full/log/list/board/agent/5W1H/validate/runqueue/dashboard/stale-list/td-status）和 UPDATE 操作（claim/complete/release/set-who/set-what/set-when/set-where/set-why/set-how/phase/check-acceptance/set-acceptance/append-log/add-child/batch-claim/batch-complete/audit/accept-creation）。list 支援 --wave、--status、--format、--top、--all 篩選參數（W10-115 預設 --top 10，priority 排序）。

Scheduler — runqueue（W17-011.1）：回答「下一個該做哪個 ticket」。Linux schedule()/runqueue/top/ps 類比。合併原 next+schedule+resume-hint 為單一命令。

ticket track runqueue --wave 17                    # 可執行清單（blockedBy=[] pending，priority 排序）
ticket track runqueue --wave 17 --format=dag       # 完整 DAG + 關鍵路徑高亮
ticket track runqueue --context=resume --top 3     # 與 handoff/pending 交集（接手建議）

新 session 啟動時 session-start-scheduler-hint-hook 自動呼叫 runqueue --context=resume，結果以 hook additionalContext 顯示。PM 迷失方向時優先執行，免靠記憶判斷先後順序。詳見 references/track-command.md「track runqueue 子命令」章節。

Dashboard — dashboard（W10-114 / W10-113 M1+M4'）：PM 接手新 session 的聚合視圖。一次回傳 [In Progress] + [Ready Top N] + [Stale Warning] 三章節，Ready 章節含可直接 claim 的編號 [1] [2] [3] 與 priority 標籤，免拼 ID。

ticket track dashboard                      # 預設：top 5 ready，stale 60min，text 格式
ticket track dashboard --top 10             # 擴大 ready 列數
ticket track dashboard --wave 10            # 限定 wave 範圍
ticket track dashboard --no-stale           # 隱藏 stale 章節
ticket track dashboard --stale-threshold 30 # 調整 stale 判定門檻（分鐘）
ticket track dashboard --format=json        # JSON 輸出（自動化用）

設計目的：將 /ticket 裸命令流程從 7 個 tool call（list + runqueue + stale + ToolSearch + AUQ + claim + read）降至 3 個（dashboard + claim by number + 後續動作）。詳見 references/track-command.md「track dashboard 子命令」章節。

Parallel-check — parallel-check（W17-203.1）：偵測目標 ticket 的 children（或同 parent 兄弟）pending 集合中，依 where.files 路徑前綴判斷哪些可平行派發、哪些互相衝突。輸出三章節（可平行派發 / 衝突任務 / 單獨派發）並對「可平行集合中 >= 3 個觸及 .claude/ 的 ticket」發出 PC-137 警告，輔助 PM 套用 .claude/pm-rules/askuserquestion-rules.md 規則 7。

ticket track parallel-check 0.18.0-W17-203   # 分析 W17-203 的 children pending 集合

路徑比較使用 pathlib.PurePosixPath（禁 string startswith）。共同祖先深度 >= 3 段視為弱衝突（如 .claude/skills/ticket/ 級）。exit code：0=分析成功 / 1=ticket 不存在或無 pending children / 2=ID 格式或 IO 錯誤。

List 預設行為 — list --top / --all（W10-115 / W10-113 M3）：list 預設 --top 10 並依 priority(P0>P1>P2>P3) → created → id 排序，避免 dump 全量 67+ 筆造成 PM 認知負擔。

ticket track list                            # 預設 top 10 by priority
ticket track list --top 20                   # 擴大列數
ticket track list --all                      # 取全量（覆蓋 --top；共存時 --all 優先並 emit warning）
ticket track list --format ids               # 純 ID 輸出（適合 pipe 到 xargs）
ticket track list --status pending --top 5   # 篩選 pending 且只取 top 5

--format 可選值：table（預設）/ ids（每行一個 ID，適合 pipe）/ yaml。詳見 references/track-command.md「track list 子命令」章節。

Stale ticket 明細 — stale-list（W17-200）：列舉 pending 且建立日期超過閾值的 ticket，補 list 命令僅顯示彙總計數無法定位個別 ticket 的缺口。

ticket track stale-list                           # 預設 --threshold warning（warning + critical）
ticket track stale-list --threshold info          # 三級全收（info + warning + critical）
ticket track stale-list --threshold all           # 同 info
ticket track stale-list --threshold critical      # 僅 critical
ticket track stale-list --wave 17 --format ids    # 僅輸出 ID（適合 pipe）

閾值複用 lib/staleness.py：info ≥ 7 天 / warning ≥ 14 天 / critical ≥ 30 天。輸出依 days 降序。詳見 references/track-command.md「track stale-list 子命令」章節。

TD 清單校準 — td-status（W10-083 / PC-094）：掃描指定 ticket 的 body 與 git commit 訊息，將 TD 編號分類為「已處理 / 無需處理 / 仍待處理」三狀態。用於 Phase 3a/3b/4 結束時即時校準 TD 清單，防止 Phase 4 評估時誤判已完成項（PC-094 根因）。

ticket track td-status 0.18.0-W10-017          # 校準指定 ticket 的 TD 清單
ticket track td-status 0.18.0-W10-017 --version 0.18.0  # 明確指定版本

輸出分三組：[已處理] / [無需處理] / [仍待處理]，pending TD 會附 PC-094 校準提示，建議於 body 標註或在 commit 訊息引用 TD 編號。呼叫時機：Phase 3a 策略文件完成後、Phase 3b commit 前、Phase 4 派發前。詳見 .claude/pm-rules/tech-debt.md「TD 清單即時校準（td-status）」章節。

注意：complete 在父 ticket 含未完成 children（非 terminal：pending / in_progress / blocked）時會以 exit 1 阻擋（W11-003.2）。提供 --force 旁路強制完成，會在 stderr 列出未完成 children 作為警告，cascade 解鎖機制仍會執行。建議優先完成 children 後再 complete 父 ticket。

注意：5W1H 欄位由 set-who ~ set-how 6 個命令更新。blockedBy 用 set-blocked-by、relatedTo 用 set-related-to（均支援 --add/--remove）。priority 等欄位無 CLI 命令，需手動編輯 frontmatter。完整對照表見 references/track-command.md。

注意：append-log 必須加上 --section 必填參數：ticket track append-log <id> --section "Problem Analysis" "內容"。有效區段值：Problem Analysis、Context Bundle、重現實驗結果、Solution、Test Results、Execution Log、NeedsContext、Exit Status。重現實驗結果 為 ANA type 必填章節（PC-063 / ticket-body-schema.md）。Context Bundle 用於派發前寫入 PCB（PC-040）；NeedsContext/Exit Status 用於代理人結束狀態協議（W17-010）。

Status precondition（W3-044 / W1-058）：append-log 要求 ticket status 為 in_progress（completed 亦放行，補 review 場景）。例外（W1-058）：派發前章節 Problem Analysis / Context Bundle 允許 pending 直寫——PM 依 PC-040 / PC-100 於 create 後立即寫入派發 context 屬合法 bookkeeping，不需 --force、不記 audit。其餘章節（Solution / Test Results / Execution Log 等執行產出）於 pending / blocked / closed 仍阻擋（status 失敗 exit 2）；--force 逃生閥行為與 hook-logs audit 紀錄不變。

副作用（W7-001）：append-log 寫入 body 後會 auto-commit 該 ticket md（精確路徑，commit message chore(<id>): append-log <section>）。Why：body 即時進 commit 歷史可使 git checkout -- <file> / git reset --hard / git stash 三種還原全失效，根除 W1-017「未 commit body 被 git 還原覆蓋回 placeholder」遺失問題。Consequence：每次 append-log 會新增一個 chore commit（碎 commit 為設計取捨，對 ticket md chore 類可接受）；body 無變更時 graceful skip 不產生空 commit。Action：非 git repo / index.lock 競爭 / commit 失敗時 append-log 仍 exit 0 + stderr 警告，body 保留 working tree 可手動 commit。不使用 --no-verify（維持 pre-commit hook 把關；ticket md 非 JS，lint-staged 無匹配）。

注意：check-acceptance 只接受單一 index（如 1）或 --all；不支援 1 2 3 多索引。一次勾選多項請改用 set-acceptance --check 1 2 3。先用 ticket track query <id> 查看驗收條件清單和編號。詳見 references/track-command.md「驗收條件操作詳解」（含決策樹 + 5 常見錯誤）。

注意：set-acceptance 是 check-acceptance 的明確語意版（：--check <index> / --uncheck <index>（可多個）、--all-check / --all-uncheck。禁止 subagent 直接 Edit frontmatter 的 acceptance 欄位。

注意：validate <id> 驗證 Ticket frontmatter 4 關鍵欄位（status/completed_at/acceptance/who）合規性，違規時給出建議修復命令。

身份申報（--as，W1-048）：complete / check-acceptance / set-acceptance 三個寫入命令支援選用 --as <agent-name>，與 ticket who.current 精確對照。Why：防 generic agent 收 Ticket ID 即越權收尾（PC-V1-002 前提一，W1-044 探針實證）。判定邏輯——--as 值 ≠ who.current（含空值）→ deny（exit 1，純前置檢查不寫入狀態）；--as rosemary-project-manager 一律放行（PM bookkeeping 豁免，如代收尾 / stale cleanup）；未提供 --as 僅 stderr 警告不阻擋（過渡期向後相容）。Action：subagent 收尾時帶自身身份，例 ticket track complete <id> --as thyme-python-developer；轉強制（無 --as 即阻擋）的 trigger 待獨立監測 ticket 評估。

注意：deps <id> 顯示衍生關係（spawned_tickets + source_ticket），與 tree/chain 純血緣語意（parent_id/children/chain）分離，對齊 Jira/Linear/GitHub 業界慣例（W15-004）。支援遞迴展開與循環引用防護（標記 CYCLE DETECTED）。用法：ticket track deps <ticket-id>。

注意：depth <id> 沿 parent_id 鏈計算嵌套深度（非 ID 字串數點，避免完整版本前綴 1.0.0-W1-056.5 含 3 個點被誤算為 depth 4 的 linux F1 fatal bug）。輸出 depth / max_depth（= MAX_TICKET_DEPTH=3）/ can_descend（depth < MAX_TICKET_DEPTH）。深度定義：根任務（parent_id: null）= depth 1，每往下一層 +1。用途：agent 自檢層級自覺（協議 v2 D3），無需上層 prompt 傳遞層級資訊。用法：ticket track depth <ticket-id>。

注意：create --parent <id> 時，若新子任務深度 >= MAX_TICKET_DEPTH（3）會 emit warning（不硬擋，留旁路）。深度同樣沿 parent_id 鏈計算（W1-056.5 協議 v2 D3）。此為嵌套派發深度上限的 CLI 強制層，使協議深度上限不只是文件建議。

六欄位語意 SSOT：parent_id / children / source_ticket / spawned_tickets / blockedBy / relatedTo 的權威定義、阻擋語意、用戶情境對照表、決策樹見 references/field-semantics.md。其他規則 / 方法論 / error-pattern 涉及這些欄位時應引用該檔，不重複定義。

派發前提示：當 ticket 是 group、含 children、含 spawned_tickets，或同輪會派 2+ agents 時，先在 Ticket Problem Analysis / Solution 寫 dispatch-plan。欄位使用 .claude/references/agent-dispatch-template.md：ticket / agent / files / deps / context source / commit policy / run mode。dispatch-plan 是 orchestration description，不是 batch dispatch CLI。

決策樹：Read references/workflow-execute.md 和 references/workflow-query.md 詳細用法：Read references/track-command.md

show - 顯示 Ticket 內容（含 Markdown 渲染）

終端閱讀專用。TTY 下自動以 glow/mdcat/bat 渲染；pipe 時自動降純文字，避免污染下游消費者。

ticket show 0.18.0-W17-015     # 完整 ID
ticket show W17-015            # 短 ID（自動補當前版本）
ticket show W17-015 -r         # 純文字（同 track full）
ticket show W17-015 -R bat     # 指定渲染器
ticket show W17-015 -P         # 停用分頁

短 flag：-r raw / -R renderer / -p pager / -P no-pager。完整說明 ticket show --help。

與 ticket track full <id> 差異：track full 永遠純文字（腳本友善，向後相容）；show 預設渲染（閱讀友善）。

handoff - 任務鏈管理與 Context 交接

支援自動判斷方向、指定交接到父/子/兄弟任務。五種交接情境。

設計原則：handoff = 純指針，禁含任務描述 / acceptance / 5W1H（這些屬 ticket md 範圍）。完整原則見 .claude/methodologies/handoff-design-principle-methodology.md。

--next <target-ticket-id> 子旗標（W17-164 / L2-A）：以絕對指向語意建立 handoff，直接寫入 target_ticket_id 欄位，讓下 session 從「該做的 ticket」（target）讀取，而非從 source + direction 間接推導。

ticket handoff --next <target-ticket-id> --from-ticket-id <source-id>

--next 與 --auto 互斥；產生的 JSON direction="context-refresh"、auto_generated=False。讀取端（GC / SessionStart hint / Stop hook / resume）優先讀 target_ticket_id，缺則 fallback 至 direction 後綴解析（向後相容，舊 JSON 不破）。

新增 --from-worklog 子命令（W17-083.2）：解析 worklog 最新交接段，提取 ticket ID 並批次補建 .claude/handoff/pending/<id>.json，修復「worklog 寫了但未執行 CLI」雙軌不同步缺口。搭配 stop-worklog-handoff-sync-check-hook（Stop event 偵測）形成自動防護。

ticket handoff --from-worklog [--worklog-path PATH] [--dry-run]

決策樹：Read references/workflow-handoff.md 詳細用法：Read references/handoff-command.md

resume - 恢復任務

從 handoff 檔案載入 context。SessionStart hook 提醒 → 用戶 /ticket 或 /ticket resume <id> 觸發。

決策樹：Read references/workflow-handoff.md 詳細用法：Read references/resume-command.md

migrate - Ticket ID 遷移

支援單一和批量遷移，自動更新所有 ID 引用和 chain 資訊。

決策樹：Read references/workflow-migrate.md 詳細用法：Read references/migrate-command.md

generate - Plan 轉換為 Tickets

從 Plan 檔案自動生成 Atomic Tickets（Plan-to-Ticket 轉換）。

詳細用法：Read references/generate-command.md

---

參考資料

資料	說明
references/architecture.md	目錄結構、共用模組設計、自動化分析功能
references/workflow-create.md	建立流程決策樹
references/workflow-execute.md	執行+更新+批量+完成流程決策樹
references/workflow-query.md	查詢流程決策樹
references/workflow-handoff.md	交接+恢復流程決策樹
references/workflow-migrate.md	ID 遷移流程決策樹
references/completeness-check.md	指令完整性驗證（39 個指令/選項覆蓋狀態）
references/ticket-lifecycle-details.md	Ticket 生命週期詳細規則
references/track-command.md	track 子命令；含 format_error() 雙路徑（legacy str / ErrorEnvelope 結構化）、ArgparseFormatErrorParser 業務 vs 語法錯誤分流、版本標記 __error_envelope_v1__（W17-008.5 group）

Ticket Body Schema（type-aware）

不同 type 的 body 章節填寫要求：

Section	ANA	IMP	DOC
Problem Analysis	必填	選填	選填
重現實驗結果	必填（PC-063）	免填	免填
Solution	必填	選填	免填
Test Results	選填	必填	免填
Completion Info	必填	必填	必填（附變更摘要）

ticket create --type ANA/IMP/DOC 會在 body 各章節插入 <!-- Schema[TYPE/Section]: 狀態 --> 標註，指引填寫者。完整規則見 .claude/pm-rules/ticket-body-schema.md。

相關文件

• .claude/pm-rules/ticket-body-schema.md - Ticket body type-aware schema
• .claude/methodologies/atomic-ticket-methodology.md - Atomic Ticket 方法論
• .claude/methodologies/ticket-lifecycle-management-methodology.md - Ticket 生命週期管理
• .claude/pm-rules/ticket-lifecycle.md - Ticket 生命週期流程

---

Version: 2.7.0 Last Updated: 2026-05-27 Status: Completed

Change Log:

• v2.7.0 (2026-05-27): /ticket 裸指令預設行為改為 dashboard-first 流程（W3-013.1 落地，源於 W3-013 ANA 結論方向 a）
  • 步驟 1 從 ticket track runqueue --context=resume --top 3 改為 ticket track dashboard --top 5
  • AskUserQuestion 選項對齊 dashboard [1] [2] [N] 編號 + priority 標籤（用戶可直接說編號選擇）
  • in_progress 任務優先列出（label 加 [ip] 前綴），用戶選擇後走 resume 而非 claim
  • dashboard 無結果時 fallback 到原 list --status pending,in_progress 路徑（向後相容）
  • ticket resume --list 與 ticket track runqueue --context=resume 子命令保留作除錯/腳本用途
  • 量測收益：W10-113 baseline 7 tool call → dashboard-first 2-3 tool call（改善 57-71%）
• v2.6.0 (2026-05-13): 補 W10-114 dashboard 命令與 W10-115 list 預設行為文件（W10-116 落地）
  • 子命令總覽表新增 track dashboard 與 track list 兩列
  • track 章節 READ 操作清單補 dashboard / stale-list / td-status，並註明 list --top/--all 預設行為
  • 新增 Dashboard — dashboard callout 說明聚合視圖、編號 claim、降低 7→3 tool call
  • 新增 List 預設行為 — list --top / --all callout 說明預設 top 10 排序與 --format 三選值
• v2.5.2 (2026-05-12): 子命令總覽表新增 track td-status；track 章節新增 td-status callout（W10-083 / PC-094 落地，0.18.0-W10-106）
• v2.5.1 (2026-05-10): handoff 章節新增「設計原則」引用指向 handoff-design-principle-methodology.md（W17-175 落地）
• v2.5.0 (2026-05-08): handoff 章節同步 W17-164 落地的 --next CLI 與 target_ticket_id 欄位
  • 新增 --next <target-ticket-id> 用法說明（絕對指向語意）
  • 註明與 --auto 互斥、direction 預設 context-refresh
  • 註明讀取端優先序：target_ticket_id > direction fallback（向後相容）
• v2.4.0 (2026-04-21): /ticket 裸指令入口切換為 scheduler 接手建議
  • 流程步驟 1 從 ticket resume --list 改為 ticket track runqueue --context=resume --top 3
  • AskUserQuestion 選項順序改反映 runqueue scheduler 排序
  • ticket resume --list 子命令保留，作為完整待恢復清單與除錯入口
• v2.3.0 (2026-03-11): /ticket 裸指令新增待辦任務檢查步驟
  • 流程調整為三層：(1) 檢查 handoff → (2) 檢查 pending/in_progress 待辦 → (3) 顯示子命令
  • 待辦任務以 AskUserQuestion 列出，含「建立新 Ticket」選項
• v2.2.0 (2026-03-02): /ticket 裸指令自動檢查 handoff 待恢復任務
  • 新增「無子命令時的預設行為」章節
  • /ticket → 檢查 pending handoff → AskUserQuestion 選擇 → resume
  • 搭配 handoff-prompt-reminder-hook v2.0.0 停用自動接手
• v2.1.0 (2026-03-02): 決策樹拆分為 5 個 workflow 檔案（Progressive Disclosure）
  • decision-trees.md（327 行）拆分為 5 個按工作流分組的檔案
  • 各子命令說明新增對應決策樹引用
  • 參考資料表更新為 5 個 workflow 檔案
• v2.0.0 (2026-02-10): SKILL.md 拆分為入口 + references
  • 從 1273 行精簡為 ~170 行入口文件
  • 9 個子命令/架構/決策樹/完整性驗證移至 references/ 目錄
  • 遵循官方 Supporting Files 模式（SKILL.md < 500 行）
  • 保留執行方式和命令總覽作為入口必讀資訊
• v1.9.0 (2026-02-06): 語意化重命名 commands_messages_a/b
• v1.8.0 (2026-02-06): 變更後文件一致性同步
• v1.7.0 (2026-02-06): 文件同步更新 - 新增 generate/board/audit 文件

---

修改 source 後必須重新安裝

重要：本 skill 透過 uv tool install 安裝為獨立 CLI，source（本目錄）與 installed（~/.local/share/uv/tools/<package>/）是兩份獨立 Python package。修改 source 後若未 reinstall，CLI 仍使用 stale installed 版本，新增的函式會 AttributeError 或被 hasattr 包裝靜默吞掉（W11-037 根因）。

修復指令：

cd .claude/skills/<本 skill 目錄> && uv tool install . --force --reinstall

自動偵測：每次 SessionStart 由 uv-tool-staleness-check-hook 比對 source vs installed SHA256，偵測 stale 時提示修復指令。對應 ticket-skill 本身另有 ticket-reinstall-hook 自動 reinstall。