---
name: learn
description: 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.