self-learn git:20261012.676efbaA

Immutable. This exact content never changes and is served at /api/v1/blob/1d9b631f98c23fcd.

---
name: self-learn
description: Turn problems hit while editing in BashCut into lasting fixes — record a structured lesson (symptom, cause, fix) for this project or every project, the user's taste as preferences, project facts, a project skill for a repeated workflow, and draft a change to this skill kit when the lesson is general (a wrong rule, a missing step, a trigger that did not fire). Use right after a step failed or had to be redone, when the user corrected the approach, when a workaround was found, or at the end of an editing session. Triggers: "rút kinh nghiệm", "học từ lỗi này", "nhớ lần sau", "lần sau đừng", "cập nhật skill", "self-learn".
---

# Self-learn

Reply in the user's language. A problem solved in chat but not written down **will happen again**.

Run it after the problem is solved (you need the real cause), not in the middle of the user's step. At the end
of a session, sweep the conversation for anything missed, starting from `bashcut run log --kind correction`: in
Claude Code the kit's hook keeps every user message that reads like a correction there, quoted (and puts them back
after a compaction). They are candidates: most become one lesson, some are one-off instructions.

When a process audit ran (`bc:review`, "Process audit"), start from its lessons: they come from the checklist and
the run log, not from your memory of the session. Add what the user corrected on top.

Signals worth recording: the user corrects you ("không, dùng X", "thật ra…", "X chứ không phải Y") or rejects an
action you proposed; the user says to remember ("nhớ là…", "lần sau đừng…"); a `bashcut` command fails or a
result had to be redone. A question, a one-off instruction for this clip or vague feedback ("chưa ổn") is not a
lesson.

## 1. Write the lesson

Symptom → cause → what to do, with the number or error text that proves it.

| Good | Bad |
|---|---|
| "Whip transition refused: clips were not adjacent on one layer. Close the gap first (`timeline close-gap`)." | "Transitions are tricky." |
| "Music dipped 11 dB at every loop: the song has a quiet intro. Trim 2.6 s off its start before repeating." | "Watch the music." |

Only what was **observed** in this session (an error, a measurement, the user's words). A guess is not a
lesson. Before adding one, look for it by tag and keyword (`bashcut knowledge lessons --tag transitions`,
`--query "close-gap"`); the same problem is often worded differently. If it exists, update it with
`knowledge update-lesson ID` and add the new occurrence to its evidence ("seen again 2026-10-13, rev 52: «quote»")
instead of adding a second one. A project lesson seen again in another project belongs to every project
(`--scope user`).

**How often and how lately.** Each lesson's occurrences are its record: where BashCut shows `occurrences`,
`lastSeen` and `sources` on `knowledge lessons` rows, read them there; otherwise count the "seen again" lines in its
evidence. Use them, not your memory:
- sources from two or more projects: move it to every project (`--scope user`);
- seen three or more times although active: its fix or `--check` does not work; rewrite the fix, or propose the rule
  to the kit (step 3) when it is about how a skill tells you to work;
- a workaround whose last occurrence is before an app update where the plain way now works: disable it (below).
  Old alone is never a reason.

## 2. Put it in the right place

BashCut keeps knowledge as structured entries. Every session starts with a summary of the active lessons,
preferences and facts (`context get` → `knowledge`), so a recorded entry is followed next time without anyone
re-reading a memo.

| The lesson is about | Goes to |
|---|---|
| This project: something that went wrong and how to avoid it | a project lesson (below) |
| This project: people, places, footage notes, what the user approved | a fact: `bashcut knowledge set-fact host "Lan, speaks fast"` |
| The user's taste (length, pace, voice, style) | a preference: `bashcut knowledge set-pref pace calm` (for every project; waits in the Knowledge inbox, below). `--scope project` for this project only |
| A mistake that will happen in any project | a lesson for every project: `--scope user`; it waits in the user's proposals |
| A workflow repeated two or three times in this project | a project skill: `bashcut skills save NAME FILE` (shared with Claude and Codex) |
| A workflow the user repeats in every project | a skill for every project: `bashcut skills save NAME FILE --scope user` (needs the user's approval) |
| A rule in this kit that is wrong, missing or too vague | a proposed change to the kit (step 3) |
| A skill that should have loaded but didn't | the skill's `description` (add the user's real words), via step 3 |
| A plugin's skill (`<plugin-id>:<name>`) is wrong or missing a step | a lesson tagged with the plugin ID, or a project copy: `bashcut skills get ID` then `skills save NAME FILE`; plugin skills are read-only and come back unchanged with the plugin |
| A library item (preset, look, sound, sticker) that failed or was undone | improve or prune it (below) |
| BashCut itself (a bug, a missing command or effect) | a note for the BashCut maintainers with the command, input and error |

A lesson:

```bash
bashcut knowledge add-lesson "Whip refused on non-adjacent clips" \
  --symptom "transition add failed: clips not adjacent" --cause "a 3-frame gap on v1" \
  --fix "timeline close-gap before adding a transition" --evidence "rev 41, error text" \
  --check "Are the two clips touching on one layer?" \
  --tags transitions --status proposed
```

- **Write it as a case:** the rule, the user's words **quoted, not paraphrased** in `--evidence` (a paraphrase lost
  which title the user meant to hold, and the fix landed on the wrong one), and a `--check` question you will ask
  yourself before the next draft ("Does every moment the viewer should remember get a full still hold?"). Every
  session's knowledge summary shows the check next to the lesson. When feedback is unclear about *which* element,
  confirm the target before changing anything.
- **A graphic or effect block:** tag the lesson `block:<name>` (the example or catalog name, e.g.
  `block:stat-counter`) with the value that failed and the range that worked; `graphic examples <name>` shows it
  next to the block's variables the next time, in any project when the lesson is for every project.
- **Status:** `active` (the default) when the cause is proven; `--status proposed` when you are unsure, so the user
  reviews it first. A lesson for every project is always proposed.
- **Tags:** one or two of the area (captions, audio, pacing, color, transitions, export…), so `--tag` finds them.
- **Session:** pass `--session ID` when you know your agent session ID.
- **Keys:** short, lowercase, stable (`pace`, `caption.style`, `music.genre`, `host`), so a later `set-pref`
  replaces the value instead of adding a near-duplicate.
- **Preference for every project:** `set-pref` usually returns `"approval": "proposed"` with a `p-…` ID: the
  change waits in the Knowledge inbox and is **not applied yet**. Tell the user it is waiting there; do not repeat
  the command or treat the value as set. (It applies at once only when the user lets agents act without
  confirmation.) A newer proposal for the same key replaces the older one. `knowledge proposals` lists what waits.

Project entries live in the project folder, so a project that was never saved refuses project writes; save it
first. The free-text memos (`knowledge memo`) are for longer notes such as a style study's measurements; do not
append lessons to them. If `knowledge get` shows `legacy` (an older memo from the agent workspace or home folder),
tell the user; the Knowledge sheet can move it into the notes or this project.

Wrong or outdated: `knowledge update-lesson ID --status disabled` (kept for the record) or `remove-lesson ID`;
`set-pref KEY --remove`.

A lesson about a BashCut bug or workaround can stop being true after an app update: if the plain way works now,
disable the lesson and say so in its evidence. Do not retire lessons just because they are old.

**Undo a change.** Every change to lessons, preferences, facts, memos and skills is in `knowledge history`, with
who made it and a diff. When a change was a mistake (yours or one the user wants back), find it and revert it
rather than re-typing the old value:

```bash
bashcut knowledge history --kind lesson --target LESSON_ID --limit 5
bashcut knowledge revert CHANGE_ID   # the change's id from history
```

A revert brings back a removed entry, removes an added one or undoes an edit (later changes to the same entry
too). Reverting a change for every project waits for the user's approval like any other `--scope user` write.

**Splitting an old memo.** `knowledge get` shows `memoSplit` per scope: `pending` means a memo was never split into
entries. Only when the user asks (the Knowledge sheet's **Ask the agent to split it** button sends that request),
read the memo, write a JSON file and queue it once:

```bash
bashcut knowledge split-memo entries.json            # the project memo
bashcut knowledge split-memo notes.json --scope user  # the notes for every project (no facts)
```

`{"lessons": [{"title", "symptom", "cause", "fix", "evidence", "tags"}], "prefs": [{"key", "value"}],
"facts": [{"key", "value"}]}`: one short entry per idea, only what the memo says, written in the memo's own language
(a Vietnamese memo gives Vietnamese titles, fixes and values; keys and tags stay English). Long notes such as style
measurements stay in the memo; do not edit it. Everything waits in the Knowledge inbox, and existing entries are
skipped. `--keep` keeps the memo as notes and stops offering the split.

**Library items.** A saved preset, look, sound or sticker that failed, was undone right after `library apply` or
`library place`, or that the user corrected: fix, copy or prune it with `bc:library` ("Look after it"); never
remove without a yes.

## 3. Changing the kit

Installed skills are a copy managed by the plugin system; edits there are lost on update. Instead:

1. Read the current text: `bashcut skills get NAME --scope kit`. Make a small change to a copy (a few lines, never
   a rewrite; check the rule isn't already there), each line backed by what happened.
2. Show the change to the user. If they agree and the kit repository is available locally, apply it there on a
   branch and open a pull request.
3. Otherwise propose it so it is not lost:

   ```bash
   bashcut skills propose beat-cut SKILL.md --summary "close gaps before a transition" \
     --reason "whip refused twice on a 3-frame gap"
   ```

   BashCut stores the line diff against the kit's `SKILL.md` as a lesson for every project tagged `kit`, waiting in
   the Knowledge inbox. The installed kit is not changed.

Kit 0.1.0 renamed the skills: `bashcut-beat-cut` is now `beat-cut` (shown as `bc:beat-cut`), and so on for every
skill. When a project memo or project skill still names an old one, update the name.

Keep skills short: a SKILL.md over ~250 lines moves detail into a `REFERENCE.md` next to it.

## Report

Short: what went wrong → where the lesson went → the lines added. If nothing was worth recording, say so in one
line.