inspire-lesson
Lessons catalog: capture durable, write-once, version-stamped LESSONS that change how an inspire-* skill behaves in this project — each a single one-line instruction ("do X this way"), materialized into the skill so the agent internalizes it. One timestamp-named file per lesson (YYYYMMDD_<slug>) in inspire_kb/98_lessons/. A lesson is relevant HERE; whether it generalizes is decided upstream. Use to record a lesson after skill friction or a deliberate skill change, list / show them, or purge the archive. Not for product work — that is the tracker (inspire-task), nor for spike/prototype learnings.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- inspire-lesson
- description
- Lessons catalog: capture durable, write-once, version-stamped LESSONS that change how an inspire-* skill behaves in this project — each a single one-line instruction ("do X this way"), materialized into the skill so the agent internalizes it. One timestamp-named file per lesson (YYYYMMDD_<slug>) in inspire_kb/98_lessons/. A lesson is relevant HERE; whether it generalizes is decided upstream. Use to record a lesson after skill friction or a deliberate skill change, list / show them, or purge the archive. Not for product work — that is the tracker (inspire-task), nor for spike/prototype learnings.
02 资源文件 1
- 参考文档references/lessons-format.md7.2 KB
03 SKILL.md 正文
/inspire-lesson — Lessons catalog
Scope
The self-teaching layer —
inspire_kb/98_lessons: one Markdown file
per lesson, write-once (created once, never edited). A lesson is a durable,
transmissible instruction about how an inspire-* skill itself should behave —
not about the product. It can be learned or taught; the folder is a catalog of
lessons this project holds.
Two audiences read the catalog:
- This project, across releases — the catalog is what keeps the agents behaving as you taught them once a release moves the base underneath them. The flow that writes lessons into a skill, and re-derives them against a new base, is not built: an update leaves the catalog untouched, so applying a lesson to the skills is the operator's until it exists. Capturing still pays now — a lesson written today is one that flow will find.
- INSPIRE core, via the observer — an external pull-from-above reads the catalog across many forks and distills the patterns worth folding into the next release. The fork only ever writes lessons and is unaware of any central system.
Two properties keep the org-wide sweep cheap and safe:
- Timestamp-named — files are
YYYYMMDD_<slug>.md, so a sweep selects a date range by comparing the first 8 characters, without opening a file. - Write-once — a file below the sweep's date cursor can never have changed, so it is skipped forever; already-processed lessons are never re-worked.
Every lesson freezes the INSPIRE version it was captured on (from the root
.inspire.lock), so the observer can tell whether a newer release already learned it.
The on-disk contract — naming, the one-line body format, write-once rules, frontmatter
schema, enums, archive + purge semantics — lives in
references/lessons-format.md. Read it before note
or purge.
What a lesson is
- One line, atomic. The body is a single imperative — "When generating a NestJS controller, keep DTOs in a separate file." At most a positive/negative pair (do this / not that), plus an optional example as support only. The one-line limit enforces atomicity: you cannot pack two intents into one imperative without it obviously being two lessons. This keeps the catalog small and every lesson easy to reason about — and makes update-time reconciliation clean.
- Relevant here, not "upstream-worthy." You capture a lesson because it matters to you, in this project — never because you have judged it generalizable. Whether it generalizes is decided upstream, by the observer, from the pattern many forks' lessons form. Capture asks only "is this worth keeping?"
- Materialized, not consulted. The intent is that a lesson is written into the skill so the taught behavior becomes the behavior — the agent acts on it, it does not check a footnote and apply it if it happens to notice. The model is Terraform's desired state: the lessons are the source of truth a run declares, and the skill file is the result it reconciles to them.
When to capture a lesson
Record one when a session surfaces something you want the skill to keep doing (or stop doing):
- the operator corrects how a skill behaved, in a way that should stick;
- a deliberate local change to how an
inspire-*skill works; - a recurring friction — an
AskUserQuestionthat should have a default, a step that always needs rework, drift from what the skill anticipated; - a house convention or preference the skill should honor;
- a pattern the skill doesn't cover but should.
If the signal is local, actionable work ("someone here should fix this"), file a
skill-feedback ticket with inspire-task instead. A confirmed ticket that should change
how a skill behaves graduates into a lesson (see Relationship to the tracker).
A lesson is how a project overrides the runtime rung — it is the declared channel
for "the skill should behave differently here"
(_references/authority.md). Where the departure binds
the product rather than the skill, it is an ADR or an artifact, not a lesson; and where
what the project wants changed is something mechanical — a frontmatter schema, the
keyed-entry vocabulary, a lifecycle state, anything a validator or a parser reads — no
project artifact out-specifies it and a lesson is the only way in. It is the start
of the path rather than the whole of it: a lesson teaches the skills, and the
validators are not an extension point, so the change lands through the observer and a
release.
Invocation
/inspire-lesson note {title} [--skill X --category preference --supersedes id]/inspire-lesson list [--since YYYYMMDD --until YYYYMMDD --skill X --category Z](read-only)/inspire-lesson show {id}(read-only)/inspire-lesson purge [--months N | --before YYYYMMDD] [--confirm]
Subcommand: note {title} [--flags]
- Resolve
@handlefromgit config user.email(cached per session). - Resolve today's date from CLAUDE.md
currentDateordate +%Y-%m-%d. - Read
inspire_version+template_shafrom.inspire.lock(repo root). If the lock is absent (e.g. inside the template repo itself), fall back toplugin/.claude-plugin/plugin.json; else recordunknownand warn. - Build the filename
YYYYMMDD_<slug>.md, where<slug>is a kebab-case short form of the title (~40 chars). Several lessons may share a date — the slug keeps each name distinct; pick a more specific slug if one would collide.id= the filename stem. - Apply flags:
--skill(required — the skill the lesson teaches, orruntimefor cross-cutting / methodology),--category(defaultpreference),--supersedes(id of an earlier lesson this revises). - Draft the one-line instruction with the operator and confirm it. Keep it to a
single imperative; add the optional
Not:negative and a> Example:support line only if they genuinely help. Write the file once — frontmatter + the one-line body (seereferences/lessons-format.md). - Print the new id to stdout.
Write-once. After
note, never edit the file. To revise, write a new lesson with--supersedes {old-id}; the old one stays untouched.
Subcommand: list [--filter]
- Scan
inspire_kb/98_lessons/*.md(the live catalog;--archivedalso scans98_lessons/archive/). --since/--untilfilter on the filename date prefix (cheap — no frontmatter read).--skill/--category/--reporterfilter on frontmatter.- Print a compact table to stdout:
date | category | skill | version | instruction. - Read-only.
Subcommand: show {id}
Read the file and print frontmatter + body. Read-only.
Subcommand: purge [--months N | --before YYYYMMDD] [--confirm]
Local housekeeping — delete archived lessons (those the base has already learned,
under 98_lessons/archive/) older than a threshold (default --months 6), matched on
the filename date prefix. Dry-run by default: list exactly which files would be
removed and stop. Delete only when the operator passes --confirm (or approves in the
conversation). Purge is fully optional — the archive is durable provenance, and
deleted files remain recoverable from git history. Purge only ever removes whole files;
it never edits one, so the write-once contract holds. (Until the update flow exists,
archive/ is empty and purge is a no-op — archiving is populated by an update.)
Rules
Output language — the one exception. Lessons are authored in English, whatever the project's
output_languageis: their reader is the observer / the cross-org INSPIRE core team, not the product team. Everything else in_references/output-language.mdstill holds — machine-read tokens stay verbatim.
Writing contract. Lessons follow
_references/writing-style.mdin full. Because lessons are alwaysen, R1–R6 apply here whatever the fork'soutput_languageis. The mechanical checks follow the project's declared language, so in a non-enfork this contract lives entirely in your judgment. Atomicity is this layer's own local rule, Rule 3 below.
- Write-once. Never edit a lesson after
note. Revise by writing a new one with--supersedes; retire old ones only in bulk viapurgeon the archive. - One file per lesson, named
YYYYMMDD_<slug>.md;id= the stem. - One line, atomic. The body is a single imperative (+ optional
Not:/ example); split anything compound into separate lessons. inspire_version/template_shaare frozen at capture — the whole point is knowing which release a lesson was based on.- No
status, noupdated. Processing state lives centrally, keyed byidand the date prefix — not inside the fork. - A lesson is about a skill, not the product. Product work →
inspire-task. Spike / prototype learnings are a different thing (product insight) — not lessons. - Concurrent captures are safe — distinct filenames, no locking, no shared mutation.
Relationship to the tracker (inspire-task)
99_tracker skill-feedback tickets and 98_lessons nodes are two records for two
audiences, and which signal goes where is the routing stated once in
_references/lesson-capture.md § Ticket vs. lesson
— applied above under When to capture a lesson.
What this section owns is the graduation. A friction ticket the team has confirmed,
and that should durably change how a skill behaves, becomes a lesson: the ticket keeps
tracking the local fix, while the new lesson carries the instruction and links back
with a link to the ticket file ([TASK-{id}](../99_tracker/tickets/TASK-{id}.md)). Both records stay: the ticket is the local work, and the lesson is
what the skill learns from it — and, via the observer, what INSPIRE core may learn.
Related skills
- The offer protocol the other skills follow lives in
_references/lesson-capture.md— they offer/inspire-lesson note; the operator decides. /inspire-taskhandles the local, closeable side of the same feedback signal.
04 同仓库更多 Skills
update
Update this project's INSPIRE runtime to the installed plugin's version: report drift, re-materialize unchanged files, and refuse to clobber local edits. Use after /plugin update inspire reports a newer base.
migrate
Move this project's knowledge base from the layered layout (01_adr, 02_modules, 03_features, 04_domain, 05_screens and the surface roster) to the concept layout under inspire_kb/01_spec/, where every artifact has a typed extension, and convert its [[wikilinks]] to relative Markdown links. Run once, on purpose, after /inspire:update reports the layered layout or counts wikilinks. Rebuilds nothing that is already built.
init
Install the INSPIRE runtime into this repository: materialize the skills, validators, hooks and knowledge-base skeleton, register the hooks, and freeze the runtime version. Run once per project. Use when setting up INSPIRE in a new or existing repo.
inspire-workspace
Workspace-level validation: the global pre-PR review (orchestrating module + cross-module checks) and vault-structure validation. Use for the required pre-merge gate and top-level structure checks. ADR lifecycle lives in /inspire-adr; the task tracker in /inspire-task.
inspire-task
Task tracker: create / update / close / list / show tickets in inspire_kb/99_tracker/. A plain-file kanban (one Markdown file per ticket, no external tool) for tracking work, drift, and skill-feedback. Use to open, advance, close, or query tickets.
inspire-spike
Vertical spikes: register and harvest external functional-prototype repos. A spike is a narrow, deep, throwaway build in its OWN repo that answers 'can we build it as we think?'. Use to register such a repo (name/reference it, set up its learnings hygiene) and to capture its learnings into the vault as a gap analysis against the current project.