Continuous Learning

---
name: continuous-learning
description: "Use when a mistake, correction, or surprise taught the workspace something that must stick — a retro or postmortem, the same agent error corrected twice, a resolved bug's root cause, scattered notes-to-self — and route that lesson to the durable surface that fires next time. NOT a forward choice with alternatives (that is `decision-records`)."
tags: [learning, retro, postmortem, feedback-loop, knowledge, meta]
recommends: [decision-records, author-skill, debug, harness, knowledge-ops]
origin: risco
---

# Continuous learning — the feedback loop of the harness

This is the engine that makes the system get better every time it is wrong. When something broke, got corrected, surprised you, or simply taught the workspace something, your job is to **catch that lesson and route it back into the durable apparatus so the same mistake cannot recur**.

One premise is load-bearing: **a lesson that lives only in chat is gone at the next compaction.** Verbal reflection only changes future behaviour when it is persisted to memory the agent actually reads next time (this is the Reflexion mechanism — self-reflection written to durable memory, not held in the conversation). In this harness, "memory" is a concrete set of surfaces: a `SKILL.md` body, `02-DOCS/wiki/harness/decisions.md`, `02-DOCS/wiki/harness/user-profile.md`, a root `CLAUDE.md` rule, or a `verify.sh` check. **Chat is not memory.** A lesson is "captured" only when it has landed in one of those.

Read `02-DOCS/wiki/harness/user-profile.md` for the accompaniment dial before you narrate. It governs narration only — the capture loop runs identically at every level.

## Boundaries

| Situation | Owner | Why |
|---|---|---|
| "We chose Postgres over Mongo, here's the why + the rejected options" | `../decision-records/SKILL.md` | forward choice with alternatives; a choice is not a lesson from a mistake |
| "The migration failed because Postgres rejects NULL on the PK — never assume that again" | `continuous-learning` | backward lesson from a mistake |
| "Find the bug causing the 500" | `../debug/SKILL.md` | in-the-moment diagnosis; you run after it resolves |
| "Now that debug found it, make sure we never ship that pattern again" | `continuous-learning` | post-resolution capture |
| "Write the SKILL.md and evals for pr-describe" | `../author-skill/SKILL.md` | skill craft — body, description, evals |
| "This lesson means the deploy skill needs a new guardrail" | `continuous-learning` decides the home → `../author-skill/SKILL.md` makes the edit | you route, it writes |
| "Consolidate these docs / sweep the inbox" | `../harness/SKILL.md` | generic 02-DOCS filing; your trigger is "we learned something the hard way" |
| "What do I know about X" | `../knowledge-ops/SKILL.md` | reference knowledge, as opposed to mistake-derived experiential knowledge |
| "Run this sweep every week" | `loop` / `schedule` harness CLI | you may recommend a cadence; you are not a scheduler |

## The capture loop

Five steps. Run them in order; do not stop before step 5.

1. **Harvest** — pull the lesson out of chat *now*, while it is still in context. *Why:* the next compaction deletes it for free.
2. **Root-cause, blameless** — name the *system* gap: a missing rule, a wrong assumption, an under-specified skill, an absent guardrail. Never "the agent is careless" or "the user keeps forgetting". *Why:* blame indicts a person and the loop stops running; blameless framing focuses on contributing causes and keeps the retro honest (Google SRE / Atlassian blameless postmortem practice).
3. **Route to a durable home** — pick the *cheapest surface that will fire next time* (table below). Prefer the **preventative** write that kills the whole class of failure over a one-off note that just records it. *Why:* good postmortems split mitigative-vs-preventative action items, and the preventative one is what stops recurrence.
4. **Write it** — land the entry in that surface in the lesson format below. If the home is a skill body, a description, or an eval, **delegate the edit to `author-skill`** — you decide the home, it does the craft.
5. **Verify it fires** — prove the lesson is live (see "Verify it fires next time"). *Why:* learning loops do not fail at the retro, they fail *after* it — at action-tracking and trend analysis (incident.io / Rootly 2025 SRE best-practice consensus). If you cannot point to where it fires, you have not captured it.

## Routing decision table

The single most important artifact in this skill. Pick the row, write to that exact home, hand off to that writer.

| Lesson type | Durable home (exact path) | Who writes it |
|---|---|---|
| About the user (prefers X, hates Y, works this way) | `02-DOCS/wiki/harness/user-profile.md` | this skill |
| A rule we keep breaking | root `CLAUDE.md` rule, or the relevant `SKILL.md` body | `author-skill` for the skill body; this skill for `CLAUDE.md` |
| A pattern to ban | a `verify.sh` banlist/check on the owning skill | `author-skill` |
| A missed-trigger insight (skill fired wrong / didn't fire) | a `should_not_trigger` (or `should_trigger`) eval case | `author-skill` |
| A surprising fact / how a provider actually behaves | wiki article via the harness ingest protocol | `harness` |
| A forward choice that surfaced mid-retro | punt to `decisions.md` | `decision-records` |
| A one-off, low-stakes note | `02-DOCS/wiki/harness/decisions.md` append, or a topic note | this skill |

Full catalogue with hand-off recipes and a worked end-to-end example is in `references/lesson-routing.md`. The body table is enough for routine cases; read the reference when the home or the hand-off is unobvious.

## The "2+ recurrences ⇒ structural fix" rule

First sighting of a lesson: a note is fine. **Second sighting of the same class: stop noting and build a guardrail** — a `CLAUDE.md` rule, a `verify.sh` check, or a `should_not_trigger` eval. A third note proves the second note did nothing.

*Why:* this is exactly where learning loops die. Teams nail the postmortem and then fumble trend analysis — the recurring class never gets a structural fix, so it keeps recurring. The recurrence is the signal that prose has failed; answer it with a check, not another apology.

## Lesson entry format

Copy-pasteable and **situation-tagged**, so it retrieves on the trigger that matters — not as a vague blob nobody can act on (experiential memory works when entries are actionable and situation-tagged, not when they are similarity soup):

```md
## <date> — <short lesson title>
- **Situation:** <when this fires / the trigger phrasing>
- **We believed:** <the wrong assumption>
- **Actually:** <what is true>
- **Durable home:** <path + surface that now holds it>
- **Fires next time via:** <rule / eval / verify.sh / index entry in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer)>
```

The last two lines are not optional. An entry with no durable home and no "fires next time" is a chat message with a date on it.

## Verify it fires next time

This is the rigor of this process skill, and it stands in for a `verify.sh` (this skill emits no checkable artifact of its own — see below). **Acceptance: you can point to a concrete place where the lesson now changes behaviour:**

- a rule the agent reads on its next pass (`CLAUDE.md` or a skill body), or
- an eval case (`should_not_trigger` / `should_trigger`) that would have caught the miss, or
- a `verify.sh` check on the owning skill that fails on the banned pattern, or
- a `02-DOCS/wiki/index.md` entry (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) pointing at the new wiki article.

If you cannot name one of those, the lesson is not captured — keep going. Prefer a surface a human can review (a rule, an eval, a profile line) over an opaque store: a single agent reflecting alone can talk itself into a local optimum, so the durable write should be legible enough for a human to sanity-check.

**This skill has no `scripts/verify.sh`.** Its output is a *routing decision plus a durable write into another surface*. The check that the lesson fires lives in *that target surface* — a `verify.sh` on the deploy skill, a `should_not_trigger` eval, a `CLAUDE.md` rule — not here. Its rigor is the capability eval, same as `decision-records`, `author-skill`, and `harness`.

## Periodic retro sweep

To harvest scattered corrections and notes-to-self on a cadence, do not reimplement a scheduler — recommend the `loop` / `schedule` harness CLI to run the sweep weekly. For pulling raw notes through `02-DOCS/inbox/` into the wiki, route the consolidation itself through `../harness/SKILL.md`; you only own the lessons that came from a mistake, not the general filing.

## Anti-patterns

| Anti-pattern | Why it fails | Do instead |
|---|---|---|
| Lesson captured only in chat | lost at the next compaction | write it to a durable surface from the table |
| "The agent/user is bad at X" | blame indicts a person; the loop stops running | name the *system* gap (missing rule, wrong assumption) |
| Note added but it never fires | prose nobody reads next time is not a capture | attach a rule / eval / check, then verify it fires |
| Re-noting the same class a 3rd time | the 2nd note already proved prose failed | build a guardrail on the 2nd sighting |
| Hand-editing the SKILL.md yourself | you do not own skill craft | hand the edit to `author-skill` |
| Capturing a forward choice here | that is a decision, not a lesson | route to `decision-records` |
| A vague vector-blob note | won't retrieve, can't be acted on | situation-tag it in the entry format |
| Starting to diagnose the bug | that is `debug`'s job | come here *after* it resolves, with the root cause |