@@ -0,0 +1,43 @@
# jsc-log 技能行為清單
本頁記錄 jsc-log 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
## learn
| 項目 | 內容 |
| --- | --- |
| 觸發時機 | 一次技能執行留下可重用的教訓時，用 record 模式記錄。要跑某支技能之前，用 consult 模式查過去的教訓。工時與 Token 紀錄不走這支，走 worklog |
| 關鍵步驟 | record 模式收齊日期、技能、CLI、情境、教訓、下次做法這六欄、從 `git remote get-url origin` 解出 `{owner}/{repo}` 、用 `hash-id` 算出 `{HASH}` 、開 sub agent 讀 `LEARN_{HASH}` 、依 `wiki-get` 的退出碼分支（0 在表尾追加一列、4 才用 `templates/learn-page.md` 建頁、7 與 8 停止並回報）、同一輪更新 `LEARN_CONTENTS` 、寫入失敗重試一次；consult 模式算出 `{HASH}` 、讀 `LEARN_CONTENTS` 與 `LEARN_{HASH}` 、挑出「技能」欄相符的列、整理每一列的「下次做法」交給呼叫端 |
| 外部呼叫 | `jsc-gitea/tools/hash-id` 、`jsc-gitea/tools/gitea.sh wiki-repo LEARN` 、`jsc-gitea:wiki` （全部 wiki 讀寫）、`git remote get-url origin` 、`templates/learn-page.md` 、`templates/learn-contents.md` |
| 完成條件 | record 模式要 sub agent 回報兩頁都寫入成功，主代理確認新列在 `LEARN_{HASH}` 上，原有的列一列不少。consult 模式要兩頁都讀到，或以退出碼 4 回報頁面不存在，或在 5、7、8 停止並回報狀態 |
| 可驗證跡象 | wiki 的 `LEARN_{HASH}` 表尾多一列教訓，`LEARN_CONTENTS` 上該 repo 那一列的「最後更新時間」換新。頁面原本不存在時，會新建 `LEARN_{HASH}` 或 `LEARN_CONTENTS` 。consult 模式無寫入跡象，只有回報內容 |
## report
| 項目 | 內容 |
| --- | --- |
| 觸發時機 | 有人要一段期間的工作總結時用，期間分年、月、週、日四種。單一工作包的紀錄不走這支，走 worklog |
| 關鍵步驟 | 呼叫端沒指定期間就依 `jsc-ask:ask` 問、跑 `tools/report-range.sh` 取得起訖日與標籤、平行做四件事（`tools/report-template.sh resolve` 解出範本、讀 `LOG_CONTENTS` 與它列出的每一頁工作日誌、年報另外讀 `LEARN_CONTENTS` 、解出 REPORT 的 wiki repo）、把頁面內容存成檔案後跑 `tools/log-aggregate.sh` 算出條目數、涵蓋 repo、花費時間、Token 用量、任務狀態、從存活條目挑出阻塞與未完成工作包、照範本的標題與表格填出報告、讀 `REPORT_{HASH}` 後把本期當成新章節追加在最前、更新 `REPORT_CONTENTS` |
| 外部呼叫 | `tools/report-range.sh` 、`tools/report-template.sh` 、`tools/log-aggregate.sh` 、`jsc-gitea/tools/gitea.sh wiki-repo` （ `hash-id` 、`jsc-gitea:wiki` 、`jsc-ask:ask` 、`templates/report-{period}.md` 、`templates/report-contents.md` |
| 完成條件 | 回報頁面 URL，或回報跳過寫入與它的原因，或在讀取回 7、8 時停下並回報狀態。收尾要講出期間標籤、條目數、涵蓋的 repo、範本來源、頁面 URL、帶到下一期的未完成工作包清單，以及 `ELAPSED_MISSING` 與 `TOKEN_MISSING` |
| 可驗證跡象 | wiki 的 `REPORT_{HASH}` （雜湊取自 `{owner}/{repo}/{period}` ）多一個本期章節，`REPORT_CONTENTS` 該列的「最新一期」、「期數」、「最後更新」換新。本機留下工作日誌頁面內容的暫存檔，供 `log-aggregate.sh` 讀取。沒設定 REPORT wiki repo 時不寫 wiki，只印出報告本文 |
## stats
| 項目 | 內容 |
| --- | --- |
| 觸發時機 | 使用者問某支技能用了幾次，或問技能之間的呼叫鏈用了幾次。Token 與工時統計不走這支，走 worklog |
| 關鍵步驟 | 直接跑 `tools/usage-stats.sh skills` 或 `tools/usage-stats.sh chains` 、需要時加 `--cli` 篩選單一 CLI、先讀退出碼再看輸出、退出碼 0 就把每一行印成表格一列、一行都沒印也是退出碼 0，代表次數為零，要說明 `jsc-hooks` 還沒經 `jsc-hooks:hooks-install` 安裝接線且不出表、退出碼 2 代表子指令或 `--cli` 參數被拒，改正參數後重跑 |
| 外部呼叫 | `tools/usage-stats.sh` ；資料由 `jsc-hooks/hooks/skill-usage.sh` 持續寫進 `$JSC_HOME/usage/*.jsonl` ，這支技能只讀不寫 |
| 完成條件 | 讀到退出碼，並走完該退出碼指定的分支 |
| 可驗證跡象 | 無寫入跡象，只有回報內容 |
## worklog
| 項目 | 內容 |
| --- | --- |
| 觸發時機 | implement 或 maintain 階段每結束一項任務就寫一筆。一項任務是一個工作包、一輪 PR 意見修正，或一次獨立的修正提交。下一項任務開始前就要寫完。規劃階段的筆記不走這支 |
| 關鍵步驟 | 全程由 sub agent 收集與寫入、平行取得十項事實（`git remote get-url origin` 的 repo、`git branch --show-current` 的分支、PLAN 頁絕對連結、ANALYZE 頁工作包絕對連結、`session-timer.sh report` 的花費時間、`token-usage.sh` 的各 CLI Token、任務狀態、細節與產出、困難與解法、PR 目標分支）、平行解出 LOG wiki repo 與 `{HASH}` 、跑 `tools/worklog-target.sh` 取得頁名與本週五日期、用 `templates/log-entry.md` 填出單筆條目檔、跑 `tools/worklog-pending.sh merge` 併入待寫內容、讀 `PAGE` 後依退出碼分支（0 追加在頁尾、4 才建頁、7 與 8 停止且不建頁）、同一輪更新 `CONTENTS` 、最後依成敗跑 `worklog-pending.sh commit` 或 `abort` |
| 外部呼叫 | `jsc-hooks/hooks/session-timer.sh report` 、`tools/token-usage.sh` 、`tools/worklog-target.sh` 、`tools/worklog-pending.sh` 、`jsc-gitea/tools/gitea.sh wiki-repo` 與 `wiki-url` 、`jsc-gitea/tools/hash-id` 、`jsc-gitea:wiki` 、`jsc-ask:ask` 、`git remote get-url origin` 、`git branch --show-current` 、`templates/log-entry.md` 、`templates/log-contents.md` |
| 完成條件 | `MERGED` 的每一筆條目都在 `PAGE` 上，原有條目逐字不動，`CONTENTS` 該列帶著本週五日期且其他列不動，`worklog-pending.sh` 的 `commit` 或 `abort` 其中一個跑過並回報退出碼 |
| 可驗證跡象 | wiki 的 `LOG_{HASH}` 頁尾多一筆條目，`LOG_CONTENTS` 該列的「條目數」與「最後更新」換新。`$JSC_HOME/worklog-pending/{HASH}` 底下的待寫檔在 `commit` 後清空，`abort` 後原樣保留。本機留下填好的條目檔 |