Self-improvement loop

A team that never looks back at how it works keeps tripping on the same snags. Agents have it worse: each starts fresh, remembers nothing of the last run, and follows its instructions whether they help or not. A self-improvement loop closes that gap: report every problem, group the reports by cause, fix the causes that keep coming back, and check later whether each fix held.

Know feedback loops on a team's own process? Skip to In Terrarium.

In Terrarium

Every session lists its FrictionsOne thing that went wrong in a session or cost it needless effort, which its agent records in the session log with a possible fix and a severity.GLOSSARY.md, the problems it hit, in its session logOne agent session's own record of its work, kept in the Journal. The agent writes its goal, outcome and every Friction; the timings, tools and files it touched come from the transcript.GLOSSARY.md (Session logs). The frictions-to-fixes SkillA folder of instructions for one repeatable job, committed with the code, that a session runs when the job comes up.GLOSSARY.md, .agents/skills/frictions-to-fixes/SKILL.md, runs the loop on them, started on a schedule by a RoutineA timer, set outside the repo, that starts a session to run one Skill on a schedule. The Skill says what the run does; the Routine says only when.GLOSSARY.md.

Report and group. A subagent, a helper agent with its own context, reads the logs that ended since a short margin before the Ledger's last commit, through scripts/session/extract-frictions.ts, a script that gathers them as compact JSON. It files each Friction under an entry of the Friction LedgerThe Journal's list of Friction causes, one entry per root cause with every session that hit it and every PR meant to fix it, so a problem that keeps coming back is counted across weeks.GLOSSARY.md: one YAML file per root cause in layers/journal/content/current/frictions/, listing every session that hit it and every PR meant to fix it.

Fix. Each candidate is first checked against what is already fixed or tracked; .agents/skills/frictions-to-fixes/survey-brief.md holds those rules. The run picks a few, weighing how often and how badly each one hurt, and a subagent designs each fix and judges its risk. A fix that touches a Human-onlySaid of a file whose changes a person with write access must merge, whatever the Gate says. Agents may still edit it. The one exception is a minor or patch npm bump that Dependabot opens from the repo itself, that changes only package.json and the lockfile, and that stays within each package's major version (a 0.x minor counts as a major).GLOSSARY.md file, a guard or the hook wiring, or that turns on a choice a person should make, becomes an issue. Helper agents build the rest on branches that land as PRs that pass the GateThe fixed set of machine checks every change must pass before it merges. It runs locally and in CI, and the CI run decides.GLOSSARY.md (Merge gate). The Ledger's own updates land in a PR every run, fixes or none.

Check whether it held. Nobody writes down by hand whether a fix worked. The Ledger page derives each entry's state from the dates of its merged fixes and of its later occurrences, in layers/journal/app/utils/ledger.ts:

9/** A cluster with merged PRs shows one of these, derived from its `fixes` and
10 *  occurrences so nobody has to maintain it; one without, or one `accepted`
11 *  (the owner accepts the cause as a cost, issue #2148), shows its stored status. */
12export type FixState = 'fix landed' | 'likely fixed' | 'still recurring'
13export type LedgerState = FixState | 'open' | 'tracked' | 'on trial' | 'accepted'

A cause that comes back after its fix merged is a regression: the run files an issue naming the fix that failed and doesn't try again.

Remove. The prune-trial Skill, .agents/skills/prune-trial/SKILL.md, runs a Prune TrialAn instruction cut back to its goal and left that way for a while, so the problems later sessions report decide whether it comes back.GLOSSARY.md: it cuts one problem's instructions down to their goal, or rewrites one Skill or doc plainly, and lists the open trial in .agents/prune-trials.yml. Once the trial's window has passed, a later run reads the Frictions logged since the cut landed and judges each by its severity:

34- `major` or `blocker` damage that traces to the trial → restore the
35  **minimum**: the one goal-shaped line that would have prevented it, never the
36  wall that was there before.
37- `moderate` damage that traces to the trial → the prune holds; see below.
38- `nit`, `minor`, silence → the prune holds.

The run also compares each covered Friction's share of sessions before and after the cut, with .agents/skills/prune-trial/scripts/friction-rates.ts, since severity misses a cut that makes a small mistake more common. moderate damage, or a clear rise in a share, files an issue for a person to decide on instead of restoring text.

Frictions can't show a Skill that runs and quietly doesn't deliver, or one that should have run and never did. A second Skill, .agents/skills/audit-skills/SKILL.md, looks for both in the logs and records what it finds in the Skill InventoryThe Journal's record of every Skill in use, with what each one does for Terrarium and how much it matters.GLOSSARY.md, the Journal's list of Skills with how much each is needed; retiring a Skill it only proposes.

Where next

• LessonSession logs
• LessonClaude Code Skills
• LessonSubagents
• LessonScheduled tasks
• JournalFriction Ledger