Lintel on GitHub Copilot. Generated from skills/lessons-add/SKILL.md; edit the canonical file, then run
li-copilot init.
- Resource root:
../../.. from this skill's base directory (the Lintel source with bin/,
lib/, skills/). Write plans, state and evidence into the working repository's .claude/
tree, never into the resource root.
- Skill-relative paths: this skill's own
scripts/, references/ and data/ folders (and a
<base> that the workflow defines as its own directory) mean
../../../skills/lessons-add/ in the Lintel source, not this generated folder.
${LINTEL_SKILLS_DIR:-skills} means the skills root, ../../../skills. A bin/li-run step
runs in the working repository, so use $LINTEL_SKILLS_DIR/lessons-add/ there.
- Shell steps: run Bash snippets with Bash (Git for Windows'
bash.exe on Windows, never
System32\bash.exe). Save a snippet to a temporary .sh file and run
bash "<resource root>/bin/li-run" <file>; it prepares LINTEL_SOURCE_ROOT, LINTEL_REPO_ROOT
and the profile context.
- Tools: Read=
view, Write=create, Edit=edit, Bash=bash/powershell, Grep=grep,
Glob=glob, AskUserQuestion=ask_user, TodoWrite=the plan checklist, Task or a named role=task
with that custom agent, WebFetch=web_fetch.
- Other Lintel workflows are native skills: invoke
/li-<name> rather than reading their
files. Named roles such as CodeReviewer are custom agents.
Lessons add
Captures something worth remembering across sessions: a correction from the operator, a discovered pattern, a workaround for a specific quirk. Lands as an ID-managed L-NNN entry in the project lessons store (lintel_lessons_file; .claude/memory/lessons.md on the v5 layout). No operator-global lessons sink is activated.
Use the existing memory helpers so allocation, lookup, conditional writes and supersession
keep the same grammar across fresh sessions.
When to use
- Operator just corrected the assistant's approach — record the pattern
- A debugging session revealed a non-obvious project quirk — record it
- A new convention has been agreed (naming, file layout, framework idiom) — record it
- A reusable workflow emerged that's not yet a skill — record it for
/li-skill-new
When NOT to use
- One-off info that won't recur — wasted bytes, signal noise
- Code-level patterns better captured in code comments — comments belong in code
- Something that belongs in CLAUDE.md or design docs — those are higher-authority, write there instead
- Sensitive info (passwords, customer data, internal IDs) — do not persist it; the writer does not scan payloads
Inputs
- Required: the lesson body (inline prose)
- Optional
--scope <project|global> — project writes to the resolved project store (default). global refuses with "operator lessons sink not activated": no operator-global destination is active, and activating one is a separate operator decision
- Optional
--type <correction|pattern|quirk|skillify-candidate> — categorization (default: pattern)
- Optional
--source <text> — what triggered this (e.g. "operator correction at 16:42", "debug session for refund flow")
Retain skillify-candidate in existing lesson metadata and caller inputs. It is a stored
classification, not an instruction to invoke a removed command; no type migration is needed.
Workflow
- Validate scope.
project only. The helper resolves the store with lintel_lessons_file, names any second store it ignores, and creates a missing store from the scaffolding template (inside a repository only). --scope global refuses; nothing is written to ~/.lintel/lessons.jsonl, which stays a read-only legacy view.
- Content-safety assessment. Before writing even a body file, check the proposed
text against the no-secrets/customer-data duties and the actual applicable policy.
bin/li-lessons.py validates shape, scope and ownership; it does not scan the
lesson payload. A model-only assessment is not an executed scanner and leaves
automated content-safety evidence unverified. If policy requires a control,
require its actual authorized execution/evidence before writing: missing,
failed, errored or unverified mandatory evidence blocks. Do not invent a scanner
or infer enforcement from a hook file. If sensitive content is identified, stop
and request a safe rewrite without quoting the sensitive value.
2b. Update-phase (ADR-0006). Before writing, use the trusted source's
existing lookup, with literal task keywords:source "${LINTEL_SOURCE_ROOT:?select trusted source}/lib/memory.sh" || exit $?
lessons_find_related "${keywords:?supply the selected lesson keywords}" || exit $?
Retain lookup diagnostics; no related result is not evidence of a failed
write or permission to read a personal store. Classify the candidate as
add / update / supersede / no-op exactly as CAPTURE Step 2 does.
Apply the shared benefit and recurrence method: read
related full blocks, cite actual later application/benefit or repeat failure,
and label unobserved outcomes unknown. Propose clarification, merge or
supersession when evidence warrants it; keyword ranking is not an efficacy score.
- Format the body. The helper writes the
## L-NNN — <one-line summary> heading itself;
supply the body:**Rule:** <the durable rule>
**Why:** <source / what triggered it, with date>
**How to apply:** <bullets>
Include observed benefit, recurrence or unknown in that prose as relevant.
No extra schema fields, counters or automatic promotion are required.
- Write through the helper. It allocates the next ID (one more than the highest existing ID,
superseded and duplicated IDs included), takes the store lock and replaces the file only if it
is unchanged since it was read:
source "${LINTEL_SOURCE_ROOT:?select trusted source}/lib/memory.sh"
lessons_helper add --title "<one-line summary>" --body-file "$body_file" # add
lessons_helper update --id L-NNN --body-file "$body_file" # update
lessons_helper supersede --id L-OLD --title "<summary>" --body-file "$body_file" # supersede
A held lock or a store that changed meanwhile refuses with exit 9 and replaces nothing — retry.
Without Python 3.9+ the shim refuses visibly; surfacing and counts keep working.
- Audit. After a successful write the helper records one advisory line itself:
lessons lesson_recorded|lesson_updated|lesson_superseded with scope, id and
classification. Do not add a second manual audit_log call.
- Report.
Report format
Lesson recorded: L-042
Scope: project (.claude/memory/lessons.md)
Type: pattern
Source: operator correction — a verification command inspected the wrong target
Content-safety evidence: <actual control/result reference, or model-only assessment; automated scan unverified>
Body:
> Pass the selected repository explicitly to diagnostic helpers.
> Verify the reported target before accepting a result.
Future sessions reading the project lessons store will surface this at session start (per repo CLAUDE.md "Review at session start" rule).
Compliance integration
- Report only actual content-safety observations. Model-only assessment does not
establish scanning or satisfy an applicable mandatory control.
- A registered host control may provide separate evidence; its scope and result
must be observed. A warning or commit-time check is not proof of pre-write
payload enforcement by the lessons helper.
- The project lessons store is committed to the repo, so its content is visible to
all collaborators. Apply step 2's manual/model-only assessment and require actual
evidence for applicable mandatory controls; the writer performs no automatic
payload scan and unexecuted scanning remains unverified.
- No operator-global lessons sink is active, so nothing is written outside the project store.
Failure modes
- Lesson body too vague to be useful: WARN + ask whether to proceed. A vague lesson signals nothing actionable to future sessions.
- Duplicate lesson: prefer no-op or update regardless of age; report the existing ID.
- Sensitive content identified: BLOCK without repeating its value; request a safe rewrite.
- Required content-safety evidence missing, failed or unverified: BLOCK the write;
a model judgment or successful helper exit cannot substitute for that evidence.
- Store locked or changed during the write (exit 9): nothing was replaced; inspect and retry.
- Update or supersede of an absent (exit 1) or duplicated (exit 2) ID: refused; resolve the ID first.
- Project lessons file conflicts with
/code-freeze: the freeze is advisory; honor the operator's recorded scope and ask before writing.
Examples
Operator correction:
> /li-lessons-add "Pass the selected repository explicitly to diagnostic helpers." --type correction
✓ L-042 appended to .claude/memory/lessons.md. Visible to future sessions.
Reusable skill candidate:
> /li-lessons-add "Regenerate owned test fixtures after a schema change." --type skillify-candidate
✓ Lesson recorded. Run /li-skill-new --from-lesson L-043 with an authorized draft destination when ready.
Global scope (refused):
> /li-lessons-add "Check path identity rather than display spelling." --scope global --type quirk
✗ operator lessons sink not activated; nothing was written. Record it in the project store instead.
See also
/li-skill-new — turn a selected lesson into a skill draft (--from-lesson L-NNN)
/li-lessons-surface — keyword, index and exact-ID lookup
- The project lessons store (
lintel_lessons_file) — where lessons live; bin/li-lessons.py get --id L-NNN prints one exactly. ~/.lintel/lessons.jsonl is a read-only legacy view (lessons_legacy_operator), not ID-managed
- Project CLAUDE.md "Self-improvement loop" — the discipline this skill enables
/li-capture --retrospective — reflection that may propose several lessons
1---2name: li-lessons-add3description: Use after a correction, insight, or recurring pattern worth remembering to record it as a lesson the next session will read at startup. Reach for it whenever the operator corrects you or you discover something that should prevent the same mistake recurring.4metadata:5 source: https://skillmd.com/skills/jokerman89/li-lessons-add6---78> **Lintel on GitHub Copilot.** Generated from `skills/lessons-add/SKILL.md`; edit the canonical file, then run9> `li-copilot init`.10> - **Resource root:** `../../..` from this skill's base directory (the Lintel source with `bin/`,11> `lib/`, `skills/`). Write plans, state and evidence into the working repository's `.claude/`12> tree, never into the resource root.13> - **Skill-relative paths:** this skill's own `scripts/`, `references/` and `data/` folders (and a14> `<base>` that the workflow defines as its own directory) mean15> `../../../skills/lessons-add/` in the Lintel source, not this generated folder.16> `${LINTEL_SKILLS_DIR:-skills}` means the skills root, `../../../skills`. A `bin/li-run` step17> runs in the working repository, so use `$LINTEL_SKILLS_DIR/lessons-add/` there.18> - **Shell steps:** run Bash snippets with Bash (Git for Windows' `bash.exe` on Windows, never19> `System32\bash.exe`). Save a snippet to a temporary `.sh` file and run20> `bash "<resource root>/bin/li-run" <file>`; it prepares `LINTEL_SOURCE_ROOT`, `LINTEL_REPO_ROOT`21> and the profile context.22> - **Tools:** Read=`view`, Write=`create`, Edit=`edit`, Bash=`bash`/`powershell`, Grep=`grep`,23> Glob=`glob`, AskUserQuestion=`ask_user`, TodoWrite=the plan checklist, Task or a named role=`task`24> with that custom agent, WebFetch=`web_fetch`.25> - **Other Lintel workflows** are native skills: invoke `/li-<name>` rather than reading their26> files. Named roles such as `CodeReviewer` are custom agents.2728# Lessons add2930Captures something worth remembering across sessions: a correction from the operator, a discovered pattern, a workaround for a specific quirk. Lands as an ID-managed `L-NNN` entry in the project lessons store (`lintel_lessons_file`; `.claude/memory/lessons.md` on the v5 layout). No operator-global lessons sink is activated.3132Use the existing memory helpers so allocation, lookup, conditional writes and supersession33keep the same grammar across fresh sessions.3435## When to use3637- Operator just corrected the assistant's approach — record the pattern38- A debugging session revealed a non-obvious project quirk — record it39- A new convention has been agreed (naming, file layout, framework idiom) — record it40- A reusable workflow emerged that's not yet a skill — record it for `/li-skill-new`4142## When NOT to use4344- One-off info that won't recur — wasted bytes, signal noise45- Code-level patterns better captured in code comments — comments belong in code46- Something that belongs in CLAUDE.md or design docs — those are higher-authority, write there instead47- Sensitive info (passwords, customer data, internal IDs) — do not persist it; the writer does not scan payloads4849## Inputs5051- Required: the lesson body (inline prose)52- Optional `--scope <project|global>` — `project` writes to the resolved project store (default). `global` refuses with "operator lessons sink not activated": no operator-global destination is active, and activating one is a separate operator decision53- Optional `--type <correction|pattern|quirk|skillify-candidate>` — categorization (default: pattern)54- Optional `--source <text>` — what triggered this (e.g. "operator correction at 16:42", "debug session for refund flow")5556Retain `skillify-candidate` in existing lesson metadata and caller inputs. It is a stored57classification, not an instruction to invoke a removed command; no type migration is needed.5859## Workflow60611. **Validate scope.** `project` only. The helper resolves the store with `lintel_lessons_file`, names any second store it ignores, and creates a missing store from the scaffolding template (inside a repository only). `--scope global` refuses; nothing is written to `~/.lintel/lessons.jsonl`, which stays a read-only legacy view.622. **Content-safety assessment.** Before writing even a body file, check the proposed63 text against the no-secrets/customer-data duties and the actual applicable policy.64 `bin/li-lessons.py` validates shape, scope and ownership; it does not scan the65 lesson payload. A model-only assessment is not an executed scanner and leaves66 automated content-safety evidence **unverified**. If policy requires a control,67 require its actual authorized execution/evidence before writing: missing,68 failed, errored or unverified mandatory evidence blocks. Do not invent a scanner69 or infer enforcement from a hook file. If sensitive content is identified, stop70 and request a safe rewrite without quoting the sensitive value.712b. **Update-phase (ADR-0006).** Before writing, use the trusted source's72 existing lookup, with literal task keywords:73 ```bash74 source "${LINTEL_SOURCE_ROOT:?select trusted source}/lib/memory.sh" || exit $?75 lessons_find_related "${keywords:?supply the selected lesson keywords}" || exit $?76 ```77 Retain lookup diagnostics; no related result is not evidence of a failed78 write or permission to read a personal store. Classify the candidate as79 add / update / supersede / no-op exactly as CAPTURE Step 2 does.80 Apply the shared [benefit and recurrence method](../../../skills/lessons-add/references/benefit.md): read81 related full blocks, cite actual later application/benefit or repeat failure,82 and label unobserved outcomes **unknown**. Propose clarification, merge or83 supersession when evidence warrants it; keyword ranking is not an efficacy score.843. **Format the body.** The helper writes the `## L-NNN — <one-line summary>` heading itself;85 supply the body:86 ```markdown87 **Rule:** <the durable rule>88 **Why:** <source / what triggered it, with date>89 **How to apply:** <bullets>90 ```91 Include observed benefit, recurrence or unknown in that prose as relevant.92 No extra schema fields, counters or automatic promotion are required.934. **Write through the helper.** It allocates the next ID (one more than the highest existing ID,94 superseded and duplicated IDs included), takes the store lock and replaces the file only if it95 is unchanged since it was read:96 ```bash97 source "${LINTEL_SOURCE_ROOT:?select trusted source}/lib/memory.sh"98 lessons_helper add --title "<one-line summary>" --body-file "$body_file" # add99 lessons_helper update --id L-NNN --body-file "$body_file" # update100 lessons_helper supersede --id L-OLD --title "<summary>" --body-file "$body_file" # supersede101 ```102 A held lock or a store that changed meanwhile refuses with exit 9 and replaces nothing — retry.103 Without Python 3.9+ the shim refuses visibly; surfacing and counts keep working.1045. **Audit.** After a successful write the helper records one advisory line itself:105 `lessons lesson_recorded|lesson_updated|lesson_superseded` with `scope`, `id` and106 `classification`. Do not add a second manual `audit_log` call.1076. **Report.**108109## Report format110111```112Lesson recorded: L-042113114Scope: project (.claude/memory/lessons.md)115Type: pattern116Source: operator correction — a verification command inspected the wrong target117Content-safety evidence: <actual control/result reference, or model-only assessment; automated scan unverified>118119Body:120> Pass the selected repository explicitly to diagnostic helpers.121> Verify the reported target before accepting a result.122123Future sessions reading the project lessons store will surface this at session start (per repo CLAUDE.md "Review at session start" rule).124```125126## Compliance integration127128- Report only actual content-safety observations. Model-only assessment does not129 establish scanning or satisfy an applicable mandatory control.130- A registered host control may provide separate evidence; its scope and result131 must be observed. A warning or commit-time check is not proof of pre-write132 payload enforcement by the lessons helper.133- The project lessons store is committed to the repo, so its content is visible to134 all collaborators. Apply step 2's manual/model-only assessment and require actual135 evidence for applicable mandatory controls; the writer performs no automatic136 payload scan and unexecuted scanning remains unverified.137- No operator-global lessons sink is active, so nothing is written outside the project store.138139## Failure modes140141- **Lesson body too vague to be useful:** WARN + ask whether to proceed. A vague lesson signals nothing actionable to future sessions.142- **Duplicate lesson:** prefer no-op or update regardless of age; report the existing ID.143- **Sensitive content identified:** BLOCK without repeating its value; request a safe rewrite.144- **Required content-safety evidence missing, failed or unverified:** BLOCK the write;145 a model judgment or successful helper exit cannot substitute for that evidence.146- **Store locked or changed during the write (exit 9):** nothing was replaced; inspect and retry.147- **Update or supersede of an absent (exit 1) or duplicated (exit 2) ID:** refused; resolve the ID first.148- **Project lessons file conflicts with `/code-freeze`:** the freeze is advisory; honor the operator's recorded scope and ask before writing.149150## Examples151152**Operator correction:**153```154> /li-lessons-add "Pass the selected repository explicitly to diagnostic helpers." --type correction155✓ L-042 appended to .claude/memory/lessons.md. Visible to future sessions.156```157158**Reusable skill candidate:**159```160> /li-lessons-add "Regenerate owned test fixtures after a schema change." --type skillify-candidate161✓ Lesson recorded. Run /li-skill-new --from-lesson L-043 with an authorized draft destination when ready.162```163164**Global scope (refused):**165```166> /li-lessons-add "Check path identity rather than display spelling." --scope global --type quirk167✗ operator lessons sink not activated; nothing was written. Record it in the project store instead.168```169170## See also171172- `/li-skill-new` — turn a selected lesson into a skill draft (`--from-lesson L-NNN`)173- `/li-lessons-surface` — keyword, index and exact-ID lookup174- The project lessons store (`lintel_lessons_file`) — where lessons live; `bin/li-lessons.py get --id L-NNN` prints one exactly. `~/.lintel/lessons.jsonl` is a read-only legacy view (`lessons_legacy_operator`), not ID-managed175- Project CLAUDE.md "Self-improvement loop" — the discipline this skill enables176- `/li-capture --retrospective` — reflection that may propose several lessons