log/skills/worklog/SKILL.md

name, description

name

description

worklog

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

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

Rows 3, 4, 5 and 6 each hit a different source and none of them reads another's output, so fetch the four in parallel. Rows 1 and 2 are two local git reads that join the same batch.

#	Item	Source
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}](<url>). Resolve the hosting repo with jsc-gitea/tools/gitea.sh wiki-repo PLAN, then take <url> from gitea.sh wiki-url <that repo> 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. wiki-url exit 5 → stop and report that the page carries no html_url; never assemble the URL by hand. wiki-url exit 7 (token invalid or no permission, HTTP 401/403) or exit 8 (other API failure) → stop and report the token or API status; never fill 「無」, because that records a page that exists as a page that does not
4	Work package id	Absolute link to the work package heading: [WP-xx](<url>#wp-xx). Resolve the hosting repo with gitea.sh wiki-repo ANALYZE, then take <url> from gitea.sh wiki-url <that repo> ANALYZE_{HASH}. A comment-fix round links to the same work package it belongs to. Same branching as row 3: wiki-repo exit 3 or wiki-url exit 4 → fill 「無」 and carry on; wiki-url exit 5 → stop and report that the page carries no html_url, never assemble the URL by hand; wiki-url exit 7 or 8 → stop and report the token or API status, never fill 「無」
5	Elapsed time	jsc-hooks/hooks/session-timer.sh report {session_id} prints {sid} {seconds} and always exits 0. Convert the seconds to h/m and read it at the moment the task ends, so it counts only this task. 0 means the timer holds no start record for that session, not a task that took no time: fill the literal 「無資料」 and say the timer had no record. Never estimate the duration from the transcript
6	Token usage	tools/token-usage.sh <cli> {session_id} per CLI that ran; it prints input<TAB>output. 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.

Write the entry

1. Resolve the LOG wiki repo and the entry's {HASH} in parallel — neither needs the other.

   • Repo: gitea.sh wiki-repo LOG. Exit 3 means no LOG wiki repo is configured; hand that to jsc-gitea:wiki, which owns the resolution order and the question to ask. Exit 2 means the type argument was misspelled, so fix it and rerun.
   • Hash: jsc-gitea/tools/hash-id "{owner}/{repo}" on the code repo from row 1. Exit 1 means this machine has no SHA-1 helper: stop and report that sha1sum or shasum has to be installed, and never hand-compute the hash.

   Done when the hosting {owner}/{repo} and the 8-character {HASH} are both known.

2. Run tools/worklog-target.sh "{HASH}" all and tools/worklog-target.sh friday in parallel. all prints PAGE=LOG_{HASH} and CONTENTS=LOG_CONTENTS; friday prints the Friday of the current work week as yyyy-MM-dd, which drives the page content and the row dates. Exit 2 means the arguments were rejected, so fix them and rerun. Exit 4 from friday means this machine's date does no date arithmetic: stop and report it, because a hand-picked Friday is exactly what goes wrong across a month or year boundary. Done when both page names and that Friday date are known.

3. 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.

4. 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.

   Exit	Do
   0	Carry on with MERGED and CLAIM. PENDING=0 is normal and still exit 0
   1	A read or write under $JSC_HOME/worklog-pending failed. Stop and report the path from the message; nothing was deleted, so a rerun loses nothing
   2	The {HASH} is not 8 uppercase alphanumerics, or the entry file argument is missing. Fix the argument and rerun from step 1

   Done when MERGED and CLAIM are known.

5. Read PAGE via jsc-gitea:wiki, and branch on the exit code the underlying gitea.sh wiki-get returned. Only exit 4 means the page is not there yet. Reading any other code as "it does not exist" builds a fresh page from templates/log-entry.md and appends to that — which replaces the whole existing work log with this one entry, and no entry on it can be recovered from the wiki afterwards.

   Exit	Do
   0	The existing content is in hand. Append the whole MERGED content at the end of it, and leave every existing entry byte for byte as it was. Never rebuild the page from the template on this code
   4	The page really is absent. Create it from the structure in templates/log-entry.md, then append MERGED
   7	The key is invalid or lacks permission, so the old content is unknown. Stop and report the key problem, write nothing and create no page — a page created here would take the place of a log that is still on the server
   8	Some other API failure. Stop and report that status, write nothing and create no page. Retry only after the API is back

   A failed write stops the run and goes to step 7 as a failure — never report the page as written when it was not. Done when every entry in MERGED is on PAGE, every entry that was already there is still there, and any 4 / 7 / 8 branch was followed as stated.

6. Update CONTENTS in the same pass (apply templates/log-contents.md; add the row if missing, otherwise refresh its 條目數 and 最後更新). Its read branches exactly as step 5 does: only exit 4 creates the directory page from the template, while 7 and 8 stop the run rather than rebuild a directory whose other rows were never read. Touch no row that belongs to another page. Done when the row for PAGE carries this week's Friday date from step 2 and every other row is unchanged.

7. Close the pending area on the result of steps 5 and 6: 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 4.

   Exit	Do
   0	Report the printed count. This is the only ending that clears pending content
   1	A pending file or the claim list could not be removed. Report the path and say the pending area still holds content, so the next run will merge it again — duplicate entries on PAGE are the thing to watch for
   2	The claim path is not the one merge produced, or it points outside this {HASH}'s pending directory. Rerun from step 4 with the CLAIM value that merge printed; never pass a hand-written path

   Done when one of the two ran and its exit code was reported.