JantonioFC/skillsbank

/tc — 技術變更追蹤器

執行一個 TC（技術變更）命令。引數：$ARGUMENTS。

如果 $ARGUMENTS 為空，則顯示此選單並停止：

/tc init                       在此專案中初始化 TC 追蹤
/tc create <名稱>               建立新的 TC 記錄
/tc update <tc-id> [...]       更新欄位、狀態、檔案、交接
/tc status [tc-id]             顯示單一 TC 或註冊表摘要
/tc resume <tc-id>             從前一個工作階段恢復 TC
/tc close <tc-id>              將 TC 轉換為已部署狀態
/tc export                     重新產生衍生產物
/tc dashboard                  重新產生註冊表摘要

否則，將 $ARGUMENTS 解析為 <子命令> <其餘部分> 並分派至下方對應的通訊協定。所有腳本位於 engineering/tc-tracker/scripts/。

子命令

init

1. 執行：

   python3 engineering/skills/tc-tracker/scripts/tc_init.py --root . --json
   

2. 如果狀態為 already_initialized，回報目前統計資料並停止。
3. 否則回報已建立的內容，並建議下一步執行 /tc create <名稱>。

create <名稱>

1. 將 <名稱> 解析為 kebab-case 格式的 slug。如果缺少，要求使用者提供一個。
2. 逐題提示使用者輸入：
   • 標題（5-120 字元）
   • 範圍：feature | bugfix | refactor | infrastructure | documentation | hotfix | enhancement
   • 優先級：critical | high | medium | low（預設 medium）
   • 摘要（10 字元以上）
   • 動機
3. 執行：

   python3 engineering/skills/tc-tracker/scripts/tc_create.py --root . \
     --name "<slug>" --title "<標題>" --scope <範圍> --priority <優先級> \
     --summary "<摘要>" --motivation "<動機>" --json
   

4. 回報新的 TC ID 及記錄檔的路徑。

update <tc-id> [意圖]

1. 如果缺少 <tc-id>，從 tc_status.py --all 列出活躍的 TC（狀態為 in_progress 或 blocked）並詢問選擇哪一個。
2. 從自然語言判斷使用者的意圖：
   • 狀態變更 → --set-status <狀態> 加上 --reason "<原因>"
   • 新增檔案 → 一個或多個 --add-file 路徑[:動作]
   • 新增測試 → --add-test "<標題>" --test-procedure "<步驟>" --test-expected "<結果>"
   • 更新交接 → --handoff-progress、--handoff-next、--handoff-blocker、--handoff-context 的任意組合
   • 新增備註 → --note "<文字>"
   • 新增標籤 → --tag <標籤>
3. 執行：

   python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [旗標] --json
   

4. 如果結束碼非零，逐字顯示錯誤。狀態機與驗證器會拒絕無效的轉移——不要盲目重試。

status [tc-id]

• 如果提供了 <tc-id>：

  python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id>
  

• 否則：

  python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all
  

resume <tc-id>

1. 執行：

   python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json
   

2. 顯著顯示交接區塊：progress_summary、next_steps（編號）、blockers、key_context。
3. 詢問：「恢復 並從下一步驟 1 繼續？(y/n)」
4. 如果回答是，執行更新以記錄恢復：

   python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \
     --note "工作階段已恢復" --reason "session handoff"
   

5. 開始執行 next_steps 中的第一個項目。不要重新推導上下文——信任交接內容。

close <tc-id>

1. 透過 tc_status.py --tc-id <tc-id> --json 讀取記錄。
2. 驗證目前狀態為 tested。如果不是，拒絕並告知使用者仍需哪些轉移。
3. 檢查 test_cases：如果任何測試為 pending、fail 或 blocked，則發出警告。
4. 詢問使用者：
   • 「核准人是誰？（您的姓名，或 'self'）」
   • 「核准備註（可選）：」
   • 「測試覆蓋狀態：none / partial / full」
5. 執行：

   python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \
     --set-status deployed --reason "由 <核准人> 核准" --note "核准：<核准人> — <備註>"
   

   然後如果您的腳本版本支援，透過後續更新直接編輯 approval 區塊；否則指示使用者在 notes 中記錄核准。
6. 回報：「TC-NNN 已關閉並部署。」

export

此技能沒有自動的 HTML 匯出。請改為重新驗證所有內容：

1. 讀取註冊表。
2. 對於每筆記錄，執行：

   python3 engineering/skills/tc-tracker/scripts/tc_validator.py --record <路徑> --json
   

3. 執行：

   python3 engineering/skills/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json
   

4. 回報：已驗證的記錄總數、任何錯誤、無效項目的路徑。

dashboard

執行所有記錄的摘要：

python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all

鐵則

1. 絕對不要手動編輯 tc_record.json。 一律使用 tc_update.py，以便附加修訂歷史並執行驗證。
2. 絕對不要跳過狀態機。 即使感覺多餘，也要逐步向前推進狀態。
3. 絕對不要刪除 TC。 歷史是僅附加的——加入最終修訂並標記為 [CANCELLED]。
4. 背景記帳。 在任務進行中時，衍生一個背景子代理來更新 TC。不要為了文書工作而暫停編碼。
5. 在回報成功之前先驗證。 如果腳本結束碼非零，顯示錯誤並停止。

相關技能

• engineering/tc-tracker — 完整的 SKILL.md，包含結構定義參考、生命週期圖表以及交接格式。
• engineering/changelog-generator — 與 TC 追蹤器搭配使用：TC 用於逐變更的審計軌跡，changelog 用於使用者面向的版本說明。
• engineering/tech-debt-tracker — 用於追蹤長期存在的技術債，而非離散的程式碼變更。