log/skills/learn/SKILL.md

name, description

name

description

learn

Record a lesson learned after a skill run to wiki LEARN_{HASH} plus LEARN_CONTENTS, or consult past lessons before a skill run. Each entry is one table row with date, skill, CLI, situation, lesson, and next-time approach. HASH follows the shared 8-char rule with the H-prefix fallback. Use when a skill run produced a reusable lesson, or before running a skill to consult past lessons; not for work-time logs (see worklog).

learn — lessons learned

Close the loop on skill runs: record what a run taught you, consult it before the next run. Two modes — record and consult. Page content is chart-first Traditional Chinese (STE100): markdown table entries, prose as the last resort.

Target pages

• Directory page: LEARN_CONTENTS. Content page: LEARN_{HASH}, one page per repository.
• Compute {HASH} from {owner}/{repo} with jsc-gitea/tools/hash-id. Exit 1 means no SHA-1 helper on this machine: stop and report that sha1sum or shasum has to be installed, and never hand-compute the hash.
• Wiki repo: run jsc-gitea/tools/gitea.sh wiki-repo LEARN. Exit 3 hands the question to jsc-gitea:wiki, which owns the resolution order and the wording; exit 2 means the type argument was misspelled, so fix it and rerun.
• All wiki reads and writes go through jsc-gitea:wiki.

Mode: record

Run after a skill run that produced a reusable lesson.

1. Collect the six facts below. Done when every field has a value.

   #	Field (page column)	Source
   1	日期	Today, yyyy-MM-dd
   2	技能	The skill that ran, as jsc-{domain}:{name}
   3	CLI	One of claude / codex / copilot / antigravity / kiro
   4	情境	What was happening when the lesson appeared, one sentence
   5	教訓	What the run taught, one sentence
   6	下次做法	How to apply it on the next run, one sentence

2. Resolve {owner}/{repo} from git remote get-url origin and compute {HASH} with jsc-gitea/tools/hash-id. Done when the page name LEARN_{HASH} is known.

3. Write the entry. This step MUST run as a sub agent; the main agent only confirms the write succeeded.

   • Read LEARN_{HASH} 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; creating the page from the template on any other code appends this one row to a blank table and drops every lesson already recorded.

     Exit	Do
     0	The table is in hand. APPEND the new row at the end of it and overwrite no existing row. Never rebuild the page from the template on this code
     4	The page really is absent. Create it from templates/learn-page.md, then add the row
     7	The token is invalid or lacks permission, so the old rows are unknown. Stop and report the token problem, and create no page
     8	Some other API failure. Stop and report that status, and create no page

   • Update LEARN_CONTENTS in the same pass (apply templates/learn-contents.md; add the repo row if missing, otherwise refresh its 最後更新時間), branching on its read exactly as above: only exit 4 creates the directory page from the template, while 7 and 8 stop the run instead of rebuilding a directory whose other repos' rows were never read. Touch no row that belongs to another repository.

   • A failed jsc-gitea:wiki write on either page: retry once. Still failing, stop and report which page was not written (LEARN_{HASH} or LEARN_CONTENTS) together with the row content that was meant to go in, so the lesson is not lost. Never report a page as written when it was not.

   • Done when the sub agent reports both pages written, the main agent has confirmed the row exists on LEARN_{HASH}, and the rows that were there before are still there.

Mode: consult

Run before a skill run, to apply past lessons.

1. Resolve {owner}/{repo} and compute {HASH} as in record mode. Done when LEARN_{HASH} is known.

2. Read LEARN_CONTENTS and the repo's LEARN_{HASH} via jsc-gitea:wiki, and branch on the exit code jsc-gitea/tools/gitea.sh returned. Only 4 means the page is absent; every other failure code means the read never happened, so an empty page must never be inferred from it.

   Exit	Do
   4	The page does not exist. Report 「無教訓紀錄」 for that page and let the caller proceed
   5	The page carries no html_url. Stop and report it; never assemble the URL by hand and never read it as an empty page
   7	The Gitea token is invalid or lacks permission (HTTP 401/403). Stop and report that the token has to be fixed. Reading this as 「無教訓紀錄」 is exactly the misread gitea.sh separates 7 from 4 to prevent
   8	Some other API failure, with the HTTP status in the message. Stop and report that status; retry only after the API is back

   Done when both pages are read, or reported missing under exit 4, or the run stopped on 5, 7 or 8.

3. Surface every row whose 技能 matches the skill about to run, and summarize each matched 下次做法 for the caller to apply. Done when the matched rows (or 「無相符教訓」) are reported.