From 5e61528ad0186d8c4db0437897e750083e133578 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 11:20:29 +0800 Subject: [PATCH] =?UTF-8?q?feat(worklog):=20=E6=AF=8F=E5=AE=8C=E6=88=90?= =?UTF-8?q?=E4=B8=80=E5=80=8B=E4=BB=BB=E5=8B=99=E5=B0=B1=E5=AF=AB=E4=B8=80?= =?UTF-8?q?=E7=AD=86=E6=97=A5=E8=AA=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`worklog` 技能改成一個任務一筆條目，任務有三種——一個工作包、一輪 PR 留言修正、一個獨立的修正提交，並新增「What counts as one task」一表寫明各自何時結束；寫入步驟改走 `merge`、`commit`、`abort` 三段式，十項資訊裡的花費時間、token 用量、任務狀態、執行細節四項改成只算這一個任務。`templates/log-entry.md` 的頁首說明同步改寫。 Why：原本一個階段只寫一筆，同一個工作包跑五輪留言修正也只留下一筆。花費時間與 token 用量被攤成一個總數，看不出哪一輪花掉多少；連「試了卻沒改到檔案」的那一輪也整段消失，而那段時間正是最該被看見的。 How：下一個任務開始前先把這一筆寫完，五輪就是五筆，各自帶自己的花費時間與 token 用量，一律附加到同一頁 `LOG_{HASH}`，既有條目不動。每筆的標題要寫清楚是哪一個任務（工作包代號、第幾輪、或提交標題），五筆並排才讀得下去。花費時間在任務結束的當下讀，token 用量傳同一個 session id，兩個數字才描述同一件事。 Who：`jsc-sdlc:implement` 與 `jsc-sdlc:maintain` 收尾時呼叫日誌的每一個工作階段。 --- skills/worklog/SKILL.md | 39 ++++++++++++++++++++++++++------------- templates/log-entry.md | 4 +++- 2 files changed, 29 insertions(+), 14 deletions(-) diff --git a/skills/worklog/SKILL.md b/skills/worklog/SKILL.md index 9c2b4fe..5498816 100644 --- a/skills/worklog/SKILL.md +++ b/skills/worklog/SKILL.md @@ -1,11 +1,23 @@ --- name: worklog -description: After finishing a work package, collect ten facts (repo, branch, plan link, work package link, elapsed time from session-timer, token usage per CLI, status, details, difficulties, PR target) and append a templated entry to wiki LOG_{HASH} plus LOG_CONTENTS. HASH follows the shared 8-char rule with the H-prefix fallback, and the work-week Friday still drives the page content. Merge whatever tools/worklog-pending.sh holds for that HASH into the same write, then clear the pending area once the wiki write succeeded. Trigger at the end of implement or maintain; not for planning notes. +description: Append one work-log entry to wiki LOG_{HASH} plus LOG_CONTENTS as soon as a task ends, where a task is one work package, one round of PR-comment fixes, or one standalone fix commit — one task, one entry, appended to the same page. Every entry carries the ten facts (repo, branch, plan link, work package link, elapsed time from session-timer, token usage per CLI, status, details, difficulties, PR target); HASH follows the shared 8-char rule with the H-prefix fallback and the work-week Friday drives the page content. Merge whatever tools/worklog-pending.sh holds for that HASH into the same write, then clear the pending area once that write succeeded. Trigger at the end of every such task in implement or maintain; not for planning notes. --- # worklog — work log -After work completes, collect the ten items below and append a `templates/log-entry.md` entry to the wiki log page. Collection and writing MUST run as a sub agent. The entry content is written in Traditional Chinese (STE100). +Collection and writing MUST run as a sub agent. Entry content is written in Traditional Chinese (STE100). + +## What counts as one task + +| Task | Ends when | +| --- | --- | +| A work package | its todos are done and its PR is open | +| One round of PR-comment fixes | that round's replies and pushes are done | +| A standalone fix commit | that commit is pushed | + +Write the entry for a task before the next task starts — that is the whole granularity rule. Five rounds of comment fixes on one work package produce five entries on the same `LOG_{HASH}`, each with its own elapsed time and token count, including a round that tried something and changed no file: the time it burned is the fact worth keeping. Give each entry a heading that names the task (work package id, round number, or commit subject) so the five stay readable side by side. + +Guardrail: append entries at the end of the page and leave the existing ones untouched. ## Items to collect @@ -14,23 +26,24 @@ After work completes, collect the ten items below and append a `templates/log-en | 1 | Repository name | Parse `{owner}/{repo}` from `git remote get-url origin`. This is the code repo — never pass it to `wiki-url`, which takes the wiki-hosting repo | | 2 | Branch name | `git branch --show-current` | | 3 | Plan name | Absolute link to the plan page: `[PLAN_{HASH}]()`. Resolve the hosting repo with `jsc-gitea/tools/gitea.sh wiki-repo PLAN`, then take `` from `gitea.sh wiki-url PLAN_{HASH}` — PLAN and LOG may live in different wiki repos, and `[[...]]` only resolves inside one wiki. `wiki-repo` exit 3 (no wiki repo configured for that type) or `wiki-url` exit 4 (page not found) → fill the literal 「無」 for this row and carry on; a `worklog` run triggered from `maintain` normally has no plan page | -| 4 | Work package id | Absolute link to the work package heading: `[WP-xx](#wp-xx)`. Resolve the hosting repo with `gitea.sh wiki-repo ANALYZE`, then take `` from `gitea.sh wiki-url ANALYZE_{HASH}`. Same fallback as row 3: `wiki-repo` exit 3 or `wiki-url` exit 4 → fill 「無」 and carry on | -| 5 | Elapsed time | `jsc-hooks/hooks/session-timer.sh report {session_id}` (seconds; convert to h/m) | -| 6 | Token usage | `tools/token-usage.sh {session_id}` per CLI that ran; it prints `inputoutput`. Pass the same `{session_id}` as row 5 so the elapsed time and the token count describe one session. Fill `N/A` in both columns when it prints `N/A`; exit 2 means the CLI name is not one of claude / codex / copilot / antigravity / kiro, so fix the name and rerun | -| 7 | Task status | One of the literal values 「完成」, 「部分完成」, 「阻塞」 (with reason when blocked). Derive it from the session when the session shows it; otherwise ask via `jsc-ask:ask`, offering those three literals as the options and stating each option's impact scope (「完成」 closes the work package, 「部分完成」 leaves the remainder open for the next run, 「阻塞」 records the blocker and hands it back to the operator) | -| 8 | Details and outputs | One line per changed file or produced page: what changed there and why | +| 4 | Work package id | Absolute link to the work package heading: `[WP-xx](#wp-xx)`. Resolve the hosting repo with `gitea.sh wiki-repo ANALYZE`, then take `` from `gitea.sh wiki-url ANALYZE_{HASH}`. A comment-fix round links to the same work package it belongs to. Same fallback as row 3: `wiki-repo` exit 3 or `wiki-url` exit 4 → fill 「無」 and carry on | +| 5 | Elapsed time | `jsc-hooks/hooks/session-timer.sh report {session_id}` (seconds; convert to h/m). Count only this task, so read it at the moment the task ends | +| 6 | Token usage | `tools/token-usage.sh {session_id}` per CLI that ran; it prints `inputoutput`. Pass the same `{session_id}` as row 5 so the elapsed time and the token count describe one task. Fill `N/A` in both columns when it prints `N/A`; exit 2 means the CLI name is not one of claude / codex / copilot / antigravity / kiro, so fix the name and rerun | +| 7 | Task status | One of the literal values 「完成」, 「部分完成」, 「阻塞」 (with reason when blocked). Derive it from the session when the session shows it; otherwise ask via `jsc-ask:ask`, offering those three literals as the options and stating each option's impact scope (「完成」 closes the task, 「部分完成」 leaves the remainder open for the next run, 「阻塞」 records the blocker and hands it back to the operator) | +| 8 | Details and outputs | One line per changed file or produced page: what changed there and why. A round that changed nothing says what was tried and why it was dropped | | 9 | Difficulties and resolutions | One pair per line. Ask via `jsc-ask:ask` when the session does not show them | | 10 | PR target branch | Link to the PR page | The `{HASH}` in every page name above is computed with `jsc-gitea/tools/hash-id`. -## Target page and work week +## Write the entry -1. Resolve the wiki repo hosting LOG pages: `JSC_WIKI_REPO_LOG` first, then `JSC_WIKI_REPO`, via `gitea.sh wiki-repo LOG`. Inspect the inherited shell environment variables first; ask the user per the `jsc-ask:ask` rules only when neither resolves. Never borrow another type's `JSC_WIKI_REPO_{TYPE}`. Done when the hosting `{owner}/{repo}` is known. +1. Resolve the wiki repo hosting LOG pages with `gitea.sh wiki-repo LOG`: it reads `JSC_WIKI_REPO_LOG` first and falls back to `JSC_WIKI_REPO` only when that one is unset. Inspect the inherited shell environment first, and ask the user per the `jsc-ask:ask` rules when neither resolves. Keep to the LOG variable — another page type's `JSC_WIKI_REPO_{TYPE}` never stands in for it. Done when the hosting `{owner}/{repo}` is known. 2. Compute `{HASH}` from the code repo's `{owner}/{repo}` with `jsc-gitea/tools/hash-id`. Done when the 8-character `{HASH}` is known. 3. Run `tools/worklog-target.sh "{HASH}" all`. Use `PAGE` for `LOG_{HASH}` and `CONTENTS` for `LOG_CONTENTS`. Done when both page names are known. 4. Fix the work week: the Friday of the current work week drives the page content and the row dates. Done when that Friday is fixed as a `yyyy-MM-dd` date. -5. Collect what the pending area holds for this `{HASH}`: run `tools/worklog-pending.sh cat {HASH}`. Exit 3 means nothing is pending — carry on with this run's entry alone. Anything it prints was written by an earlier SDLC stage that ended without a work log, so it goes into **this** write, ahead of this run's own entry, in the order printed. Done when the pending content is either merged into the entries about to be written, or confirmed empty. -6. Read `PAGE` via `jsc-gitea:wiki`. If it does not exist, create it with the structure described in `templates/log-entry.md`; otherwise APPEND the new entries at the end and never overwrite existing entries. Done when every entry from step 5 plus this run's own entry exists on `PAGE`. -7. Update `CONTENTS` in the same pass (apply `templates/log-contents.md`; add the row if missing, otherwise refresh its 條目數 and 最後更新). Done when the row for `PAGE` carries this week's Friday date. -8. Clear the pending area: run `tools/worklog-pending.sh clear {HASH}` **only after the wiki write of step 6 succeeded**. Clearing first and failing the write loses the content on both sides. Skip this when step 5 found nothing. Done when the script reports the cleared path, or step 5 was empty. +5. Fill `templates/log-entry.md` with the ten facts of this one task and save it to a file. Done when that file holds exactly one entry. +6. Run `tools/worklog-pending.sh merge {HASH} {entry file}`. It prints `MERGED=` (pending content in time order, then this task's entry), `CLAIM=` (the pending files it took) and `PENDING=` (how many). Pending content was written by an earlier stage that ended without a work log, so it belongs in **this** write. Done when `MERGED` and `CLAIM` are known. +7. Read `PAGE` via `jsc-gitea:wiki`. Create it from the structure in `templates/log-entry.md` when it does not exist, then append the whole `MERGED` content at the end. Done when every entry in `MERGED` exists on `PAGE`. +8. Update `CONTENTS` in the same pass (apply `templates/log-contents.md`; add the row if missing, otherwise refresh its 條目數 and 最後更新). Done when the row for `PAGE` carries this week's Friday date. +9. Close the pending area on the result of steps 7 and 8: `tools/worklog-pending.sh commit {HASH} {CLAIM}` after both succeeded, or `tools/worklog-pending.sh abort {HASH} {CLAIM}` after either failed. `abort` keeps every pending file for the retry, so keep the entry file too and rerun from step 6. Done when one of the two ran and printed its count. diff --git a/templates/log-entry.md b/templates/log-entry.md index 7a046eb..18ab93a 100644 --- a/templates/log-entry.md +++ b/templates/log-entry.md @@ -1,6 +1,8 @@ # 工作日誌頁 — LOG_{HASH} -> 由 `jsc-log:worklog` 維護。每完成一項工作附加一個條目在文末。 +> 由 `jsc-log:worklog` 維護。每完成一個任務就附加一個條目在文末，下一個任務開始前寫完。 +> 任務有三種：一個工作包、一輪 PR 留言修正、一個獨立的修正提交。同一個工作包跑五輪留言修正就是五筆， +> 標題各自寫清楚是哪一輪，時間與 token 分開記。 > `HASH` 依共享規則計算；頁名不再寫入年月週數，但頁內仍依本工作週的週五整理內容。 > {PLAN 頁絕對網址}、{ANALYZE 頁絕對網址} 由 `jsc-gitea/tools/gitea.sh wiki-url` 取得——LOG 與 PLAN／ANALYZE 可能分屬不同存取庫，`[[頁名]]` 跨庫不通。 > 解不出 wiki 存取庫或頁面不存在時，該欄填「無」，其他欄照填。由 `maintain` 觸發的日誌本來就沒有計畫頁與分析頁。