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: lessons-add3layer: foundation4description: 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.5color: blue6tools: Read, Write, Edit, Bash7voice: internal8cli_support: [claude-code, codex, copilot]9metadata:10 source: https://skillmd.com/skills/jokerman89/lessons-add11---1213# Lessons add1415Captures 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.1617Use the existing memory helpers so allocation, lookup, conditional writes and supersession18keep the same grammar across fresh sessions.1920## When to use2122- Operator just corrected the assistant's approach — record the pattern23- A debugging session revealed a non-obvious project quirk — record it24- A new convention has been agreed (naming, file layout, framework idiom) — record it25- A reusable workflow emerged that's not yet a skill — record it for `/li:skill-new`2627## When NOT to use2829- One-off info that won't recur — wasted bytes, signal noise30- Code-level patterns better captured in code comments — comments belong in code31- Something that belongs in CLAUDE.md or design docs — those are higher-authority, write there instead32- Sensitive info (passwords, customer data, internal IDs) — do not persist it; the writer does not scan payloads3334## Inputs3536- Required: the lesson body (inline prose)37- 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 decision38- Optional `--type <correction|pattern|quirk|skillify-candidate>` — categorization (default: pattern)39- Optional `--source <text>` — what triggered this (e.g. "operator correction at 16:42", "debug session for refund flow")4041Retain `skillify-candidate` in existing lesson metadata and caller inputs. It is a stored42classification, not an instruction to invoke a removed command; no type migration is needed.4344## Workflow45461. **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.472. **Content-safety assessment.** Before writing even a body file, check the proposed48 text against the no-secrets/customer-data duties and the actual applicable policy.49 `bin/li-lessons.py` validates shape, scope and ownership; it does not scan the50 lesson payload. A model-only assessment is not an executed scanner and leaves51 automated content-safety evidence **unverified**. If policy requires a control,52 require its actual authorized execution/evidence before writing: missing,53 failed, errored or unverified mandatory evidence blocks. Do not invent a scanner54 or infer enforcement from a hook file. If sensitive content is identified, stop55 and request a safe rewrite without quoting the sensitive value.562b. **Update-phase (ADR-0006).** Before writing, use the trusted source's57 existing lookup, with literal task keywords:58 ```bash59 source "${LINTEL_SOURCE_ROOT:?select trusted source}/lib/memory.sh" || exit $?60 lessons_find_related "${keywords:?supply the selected lesson keywords}" || exit $?61 ```62 Retain lookup diagnostics; no related result is not evidence of a failed63 write or permission to read a personal store. Classify the candidate as64 add / update / supersede / no-op exactly as CAPTURE Step 2 does.65 Apply the shared [benefit and recurrence method](references/benefit.md): read66 related full blocks, cite actual later application/benefit or repeat failure,67 and label unobserved outcomes **unknown**. Propose clarification, merge or68 supersession when evidence warrants it; keyword ranking is not an efficacy score.693. **Format the body.** The helper writes the `## L-NNN — <one-line summary>` heading itself;70 supply the body:71 ```markdown72 **Rule:** <the durable rule>73 **Why:** <source / what triggered it, with date>74 **How to apply:** <bullets>75 ```76 Include observed benefit, recurrence or unknown in that prose as relevant.77 No extra schema fields, counters or automatic promotion are required.784. **Write through the helper.** It allocates the next ID (one more than the highest existing ID,79 superseded and duplicated IDs included), takes the store lock and replaces the file only if it80 is unchanged since it was read:81 ```bash82 source "${LINTEL_SOURCE_ROOT:?select trusted source}/lib/memory.sh"83 lessons_helper add --title "<one-line summary>" --body-file "$body_file" # add84 lessons_helper update --id L-NNN --body-file "$body_file" # update85 lessons_helper supersede --id L-OLD --title "<summary>" --body-file "$body_file" # supersede86 ```87 A held lock or a store that changed meanwhile refuses with exit 9 and replaces nothing — retry.88 Without Python 3.9+ the shim refuses visibly; surfacing and counts keep working.895. **Audit.** After a successful write the helper records one advisory line itself:90 `lessons lesson_recorded|lesson_updated|lesson_superseded` with `scope`, `id` and91 `classification`. Do not add a second manual `audit_log` call.926. **Report.**9394## Report format9596```97Lesson recorded: L-0429899Scope: project (.claude/memory/lessons.md)100Type: pattern101Source: operator correction — a verification command inspected the wrong target102Content-safety evidence: <actual control/result reference, or model-only assessment; automated scan unverified>103104Body:105> Pass the selected repository explicitly to diagnostic helpers.106> Verify the reported target before accepting a result.107108Future sessions reading the project lessons store will surface this at session start (per repo CLAUDE.md "Review at session start" rule).109```110111## Compliance integration112113- Report only actual content-safety observations. Model-only assessment does not114 establish scanning or satisfy an applicable mandatory control.115- A registered host control may provide separate evidence; its scope and result116 must be observed. A warning or commit-time check is not proof of pre-write117 payload enforcement by the lessons helper.118- The project lessons store is committed to the repo, so its content is visible to119 all collaborators. Apply step 2's manual/model-only assessment and require actual120 evidence for applicable mandatory controls; the writer performs no automatic121 payload scan and unexecuted scanning remains unverified.122- No operator-global lessons sink is active, so nothing is written outside the project store.123124## Failure modes125126- **Lesson body too vague to be useful:** WARN + ask whether to proceed. A vague lesson signals nothing actionable to future sessions.127- **Duplicate lesson:** prefer no-op or update regardless of age; report the existing ID.128- **Sensitive content identified:** BLOCK without repeating its value; request a safe rewrite.129- **Required content-safety evidence missing, failed or unverified:** BLOCK the write;130 a model judgment or successful helper exit cannot substitute for that evidence.131- **Store locked or changed during the write (exit 9):** nothing was replaced; inspect and retry.132- **Update or supersede of an absent (exit 1) or duplicated (exit 2) ID:** refused; resolve the ID first.133- **Project lessons file conflicts with `/code-freeze`:** the freeze is advisory; honor the operator's recorded scope and ask before writing.134135## Examples136137**Operator correction:**138```139> /li:lessons-add "Pass the selected repository explicitly to diagnostic helpers." --type correction140✓ L-042 appended to .claude/memory/lessons.md. Visible to future sessions.141```142143**Reusable skill candidate:**144```145> /li:lessons-add "Regenerate owned test fixtures after a schema change." --type skillify-candidate146✓ Lesson recorded. Run /li:skill-new --from-lesson L-043 with an authorized draft destination when ready.147```148149**Global scope (refused):**150```151> /li:lessons-add "Check path identity rather than display spelling." --scope global --type quirk152✗ operator lessons sink not activated; nothing was written. Record it in the project store instead.153```154155## See also156157- `/li:skill-new` — turn a selected lesson into a skill draft (`--from-lesson L-NNN`)158- `/li:lessons-surface` — keyword, index and exact-ID lookup159- 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-managed160- Project CLAUDE.md "Self-improvement loop" — the discipline this skill enables161- `/li:capture --retrospective` — reflection that may propose several lessons