Lintel on GitHub Copilot. Generated from skills/lessons-promote/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-promote/ 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-promote/ 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.
You are the lessons-promote skill. You run bin/li-lessons-promote; there is no separate Git
recipe in this skill.
When to use
- A lesson learned in current repo is genuinely general (not repo-specific)
- Multiple repos would benefit from the same correction
- Pattern is durable (not a passing fad)
When NOT to use
- Repo-specific lesson (file paths, project-specific glue) — keep local
- Speculative — should be a discovery from real correction
- Lesson hasn't proven itself in current repo (let it bake first)
Workflow
- Select the lesson by ID. The source is the project store (
lintel_lessons_file) or an
explicit --source <file>. List candidates with lessons_index from lib/memory.sh, then
choose one L-NNN; interactive use lists every lesson by ID, never only the first 30.
Apply the benefit and recurrence method:
explain observed application, outcome and generalizability. Unknown benefit or
unresolved repeat failures stay visible and can defer promotion; no automated
reference counter or success score exists.
- Generalize the lesson. Strip repo-specific paths, file names, project nouns and anything
sensitive. Write the generalized text with exactly one level-two heading; the bin rewrites that
heading to the destination's next ID.
- Choose the destination explicitly.
--lintel-dir <work tree> or LINTEL_DIR; a linked
worktree is fine. The file scaffolding/01-foundation/.claude/memory/lessons.md must exist
there. There is no default destination.
- Record a source label explicitly.
--source-label ([A-Za-z0-9._-]{1,64}) so a private
or customer repository name is never copied implicitly. Add --record-source-commit or
--operator only when the operator wants those recorded.
- Run the bin. Default mode conditionally writes only the target file, prints its diff and
the suggested commands, and leaves HEAD, branches and the index unchanged:
bash "${LINTEL_SOURCE_ROOT:?select trusted source}/bin/li-lessons-promote" \
--lintel-dir "$lintel_dir" --id L-NNN --generalized-file "$generalized" \
--source-label "$label"
To commit, add --commit --expect-branch <branch>: it commits only the target on that branch
after checking that nothing is staged and the target is clean, then verifies that the new
commit changed only the target. It never checks out, switches or creates a branch, pushes or
opens a pull request.
- Report the exit. 7 means already promoted (the existing ID is named, nothing written);
8 a commit precondition; 9 a conditional-write conflict; 10 a failed commit whose bytes were
restored; 11 a commit that was left in place because verification failed — follow the printed
remedy, never reset automatically. The operator pushes and opens a pull request when ready.
Provenance
The bin appends one comment to the promoted lesson:
<!-- lintel-promotion: source_label=<label>; source_id=L-NNN; source_commit=<sha|unrecorded>; promoted_on=<YYYY-MM-DD> -->
The promoted lesson is then retrievable in the destination with
bin/li-lessons.py get --id L-NNN --store <target>.
Output format
LESSONS-PROMOTE: L-NNN → <destination next ID>
Source: <label> <source id> (source_commit=<sha|unrecorded>)
Target: <destination>/scaffolding/01-foundation/.claude/memory/lessons.md
Sensitivity: operator-attested; no shared scanner ran on the generalized text.
<diff of the target>
Next (not run):
- git -C <destination> add -- scaffolding/01-foundation/.claude/memory/lessons.md
- git -C <destination> commit -m "docs(lessons): promote ..." -- scaffolding/01-foundation/.claude/memory/lessons.md
Edge cases
- Operator can't decide which lesson — list IDs and the actual benefit/recurrence
evidence, with unknowns explicit; let them choose or defer, never invent usage counts.
- Lesson contains customer data — STOP, refuse. Recommend repo-only retention.
- Multiple lessons could be promoted — do one at a time. Run skill again for next.
- Destination or label missing — the bin exits 2 before resolving anything; ask for them.
Why this matters
Session-harness compounds value when lessons travel across sessions and repos. Per-repo lessons stop at repo boundary. Promoted lessons reach every future engagement.
This is the mechanism that turns 1 operator's correction into team-wide capability.
1---2name: li-lessons-promote3description: Promote one ID-managed project lesson into an explicitly named Lintel work tree's scaffolding baseline, with recorded provenance and no implicit branch, commit or push.4metadata:5 source: https://skillmd.com/skills/jokerman89/li-lessons-promote6---78> **Lintel on GitHub Copilot.** Generated from `skills/lessons-promote/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-promote/` 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-promote/` 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.2728You are the lessons-promote skill. You run `bin/li-lessons-promote`; there is no separate Git29recipe in this skill.3031## When to use3233- A lesson learned in current repo is genuinely general (not repo-specific)34- Multiple repos would benefit from the same correction35- Pattern is durable (not a passing fad)3637## When NOT to use3839- Repo-specific lesson (file paths, project-specific glue) — keep local40- Speculative — should be a discovery from real correction41- Lesson hasn't proven itself in current repo (let it bake first)4243## Workflow44451. **Select the lesson by ID.** The source is the project store (`lintel_lessons_file`) or an46 explicit `--source <file>`. List candidates with `lessons_index` from `lib/memory.sh`, then47 choose one `L-NNN`; interactive use lists every lesson by ID, never only the first 30.48 Apply the [benefit and recurrence method](../../../skills/lessons-add/references/benefit.md):49 explain observed application, outcome and generalizability. Unknown benefit or50 unresolved repeat failures stay visible and can defer promotion; no automated51 reference counter or success score exists.522. **Generalize the lesson.** Strip repo-specific paths, file names, project nouns and anything53 sensitive. Write the generalized text with exactly one level-two heading; the bin rewrites that54 heading to the destination's next ID.553. **Choose the destination explicitly.** `--lintel-dir <work tree>` or `LINTEL_DIR`; a linked56 worktree is fine. The file `scaffolding/01-foundation/.claude/memory/lessons.md` must exist57 there. There is no default destination.584. **Record a source label explicitly.** `--source-label` (`[A-Za-z0-9._-]{1,64}`) so a private59 or customer repository name is never copied implicitly. Add `--record-source-commit` or60 `--operator` only when the operator wants those recorded.615. **Run the bin.** Default mode conditionally writes only the target file, prints its diff and62 the suggested commands, and leaves HEAD, branches and the index unchanged:63 ```bash64 bash "${LINTEL_SOURCE_ROOT:?select trusted source}/bin/li-lessons-promote" \65 --lintel-dir "$lintel_dir" --id L-NNN --generalized-file "$generalized" \66 --source-label "$label"67 ```68 To commit, add `--commit --expect-branch <branch>`: it commits only the target on that branch69 after checking that nothing is staged and the target is clean, then verifies that the new70 commit changed only the target. It never checks out, switches or creates a branch, pushes or71 opens a pull request.726. **Report the exit.** 7 means already promoted (the existing ID is named, nothing written);73 8 a commit precondition; 9 a conditional-write conflict; 10 a failed commit whose bytes were74 restored; 11 a commit that was left in place because verification failed — follow the printed75 remedy, never reset automatically. The operator pushes and opens a pull request when ready.7677## Provenance7879The bin appends one comment to the promoted lesson:8081```html82<!-- lintel-promotion: source_label=<label>; source_id=L-NNN; source_commit=<sha|unrecorded>; promoted_on=<YYYY-MM-DD> -->83```8485The promoted lesson is then retrievable in the destination with86`bin/li-lessons.py get --id L-NNN --store <target>`.8788## Output format8990```91LESSONS-PROMOTE: L-NNN → <destination next ID>9293Source: <label> <source id> (source_commit=<sha|unrecorded>)94Target: <destination>/scaffolding/01-foundation/.claude/memory/lessons.md95Sensitivity: operator-attested; no shared scanner ran on the generalized text.96<diff of the target>9798Next (not run):99- git -C <destination> add -- scaffolding/01-foundation/.claude/memory/lessons.md100- git -C <destination> commit -m "docs(lessons): promote ..." -- scaffolding/01-foundation/.claude/memory/lessons.md101```102103## Edge cases104105- **Operator can't decide which lesson** — list IDs and the actual benefit/recurrence106 evidence, with unknowns explicit; let them choose or defer, never invent usage counts.107- **Lesson contains customer data** — STOP, refuse. Recommend repo-only retention.108- **Multiple lessons could be promoted** — do one at a time. Run skill again for next.109- **Destination or label missing** — the bin exits 2 before resolving anything; ask for them.110111## Why this matters112113Session-harness compounds value when lessons travel across sessions and repos. Per-repo lessons stop at repo boundary. Promoted lessons reach every future engagement.114115This is the mechanism that turns 1 operator's correction into team-wide capability.