Lessons

Lessons

Lessons are the layer above observations. Every turn slipstream captures a compact observation; over time the same shape keeps recurring (same file touched after the same kind of search, same misstep before the same correction, same lookup pattern before the same insight). Once a topic crosses a recurrence threshold, slipstream collapses those observations into a single durable lesson with citations back to the original observations, and surfaces it through the sp_lessons tool. The intent is that each project teaches you something about itself, and you do not have to write it down.

Lessons live in the project's observation store, are local-only, and are produced without an external LLM call. They are rebuilt on demand and stay stable across sessions.

Example lessons

These are illustrative, drawn from real recurring patterns the engine has surfaced in slipstream's own development:

• Prefer Edit over Write when changing existing files. Whole-file rewrites lose tracked state and trip the file-was-modified guard; Edit keeps the diff small and the round trip cheap.
• Three-layer search beats grep for memory lookup. Start with sp_search_memory (semantic), narrow with sp_timeline (when), drill in with sp_observations (raw). Going straight to grep misses the relevant past turn.
• Map watcher catches stale references after refactors. When a rename ships, the in-memory map drifts until the next sp_map build; --watch-map shortens that window to a debounce interval, so sp_symbol does not return a no-symbol after a rename.
• Token forecast protects long sessions from accidental compaction. Watching the live percentage is reactive; the forecast tells you how many steps remain before the warn line, so you choose when to compact rather than getting cut off.
• Drift flags reveal silently broken assumptions across sessions. When a file's exported surface changes shape between the last digest and the current map, the drift check flags it before the agent acts on a stale mental model.

How to contribute lessons

Lessons are produced by the engine, not authored by hand, so the way to contribute is to file a recurring pattern you have seen against the slipstream repo with a short description and at least two example observation ids. If it is a general pattern worth surfacing for every user, it lands as a built-in collapser rule in the next release.

---

SarmaLinux . sarmalinux.com . Repository