Draft: this page sits outside the guide's focus.
House rulesLesson
Prune Trials
Instructions for agents grow with every incident and almost never shrink: adding a line feels safe, and removing one feels risky. A trial removes an instruction on purpose, then lets the problems that later work runs into decide whether it was needed.
Know instruction trials already? Skip to In Terrarium.
Outside the box · General
The concept
Reading a rule can't tell you what it still prevents. It may guard against a mistake nobody makes any more, or one a later check already catches. The only way to find out is to take it away and watch.
A fair trial needs four things. A record of what was cut and why, kept where the judge will find it. A signal that reports damage, such as the problems people or agents log as they work. A test for damage, written when the cut is made, while you still remember what the text was for. And a window during which nobody puts the text back, or no verdict is possible.
When the verdict finds damage, put back the least that would have prevented it: one line stating the goal, not the old paragraph. When a rule has failed again and again as prose, the cut has shown something else too: the behaviour may need a check that runs, not more words.
In Terrarium
A is the work of the prune-trial Skill, .agents/skills/prune-trial/SKILL.md, which a scheduled run starts; a trial that cuts an ADR runs only when a user starts it. Each run first judges the open trials whose window has passed, then opens at most one new trial: it picks one problem, cuts every instruction about it down to the goal behind them, and ships the cut as one PR. A run may also, or instead, rewrite one Skill or doc in plain words; that rewrite is a trial too.
The open trials live in a ledger, .agents/prune-trials.yml. Each entry ships in the same commit as its cut, so that commit records what was removed. The file's header describes an entry:
11# trials:
12# - problem: what the pruned prose was trying to prevent
13# territory: # the next trial must not overlap these
14# paths:
15# - path/or/file/touched
16# keywords:
17# - keyword or phrase
18# opened: 2026-08-23
19# proven: false # only when §4's Sonnet probe could not run
20# check: how you would tell this broke — written now, while you still
21# remember what the prose was for. Prose, not a command; say what
22# distinguishes real damage from a session simply using the pruned
23# topic's tools correctly.
territory is the area the trial owns. The ADR-0027 summary loads when a session touches the ledger, a Skill or a doc, and it says: if an open trial covers text you would change, don't restore or reword it; log a and work around it.
Before shipping, the run commits the cut and asks a subagent on Sonnet, the model most sessions here run on, what it would do in a real situation the cut text used to cover, reading only that commit. If the answer is wrong, the run rewrites the goal and asks again, or drops the cut. proven: false marks a trial whose run had no subagent to ask.
The window starts when the cut lands on main, not on the opened: date. .agents/skills/prune-trial/scripts/find-trial-window.ts finds the landing commit with git log -S and prints the earliest time each trial may be judged, so nobody works the date out by hand. If it finds no landing, the trial is not judged. Once the window has passed, the judging run applies the entry's check and reads the Frictions logged since the landing. A major or blocker Friction caused by the cut puts back one goal-shaped line, or the whole cut text when the trial cut an ADR; anything less, and the cut stays. Either way the entry is deleted, and git keeps its history.
The ledger is part of the : pnpm validate:content runs scripts/gate/validate-prune-trials.ts, which fails when the file doesn't parse or a trial's territory lists a non-string item.
Why it's built this way
Prune Trials: ADR-0027 (docs/adr/0027-prune-trials.md).
What to watch for
- Silence can hide damage. A trial with no Frictions has not proven the cut harmless, so when you notice a cut caused you a problem, log it even if you recovered (ADR-0027, docs/adr/0027-prune-trials.md).
- A keyword hit is not damage. A Friction that mentions the pruned topic may come from a session using it correctly. Read each one in full before counting it.
- Not everything can be trialled. What a trial may never cut is listed in ADR-0027's Scope.
Try it in your project
Pick the longest passage in your agent instructions that exists because of past incidents. Cut it to one line that states its goal, and write down, beside the cut, what damage would look like and the date it lands. Leave it alone for a few weeks while your agents report the problems they hit, then decide from those reports, not from rereading the old text.
Where next
Walkthroughs through this Lesson
- WalkthroughA friction becomes a fix
- WalkthroughThe Routines
Last updated · Latest source on GitHub ↗