Where this fits
We plan our work. Our Skills are curated and battle tested, so the agent writes coherent code. pr-brief writes the description, on one premise: a well-written description should suffice.
Then the PRs showed up in GitHub, and we were out of context anyway. We needed a better way in. greenhorn is that way in. foghorn does the same for releases.
A real run
PR #33 of typescript-patterns-enforcer already had a pr-brief description. A cold reader still stopped 12 times on it. This is how it opens.
Before
The edit hook misses files that Claude writes through a shell. This change adds a hook that runs when Claude stops. It finds the TypeScript files changed during the session and runs the same checks on them. It shows the findings to the user and never blocks the session. This closes the gap that let a whole module skip every rule in the audit on PR 31.
After (shortened with [...]):
This PR adds a hook that checks TypeScript files at the end of a Claude Code session, including files that Claude wrote through a shell. The earlier hook does not see those files. The new hook only warns the user. It never blocks anything.
Claude writes a file with a shell heredoc in the project folder:
export const x: any = 1;[...] When the session stops, the new hook prints this on stdout (shortened) and exits with code 0: [...] Each violation line has the line and column, the rule name, the message, and a pointer to the rule text.
| Original | After greenhorn | |
|---|---|---|
| Words | 655 | 1,010 |
| Findings of the checker | 0 | 0 |
| Stumbles that a context-free model reader reported | 12 | 9 |
The example is real. In our run log, the skill ran the built hook on that file and quoted its output. The rewrite also leaves the PR 31 audit as an open point, because the code could not answer it.
Of the first 12 stumbles, 7 did not come back in the second reading, 5 did, and 4 were new. The reader is a model, so these counts do not show that a person finds the text clearer.
How it works
- A reader with no tools and no repo sees only your text and a profile of who the reader is. It lists where it stops.
- Claude answers each gap from your code. If the code does not say, the gap goes on an open list. Claude guesses nothing.
- The rewrite opens with the gist, then one real example, then how it works. A second reader checks the final text and counts which stumbles come back.
/greenhorn:test runs only the first step and rewrites nothing.
Why we built it this way
We started from a design, attacked it, and then read the papers. Each paper name links to the paper. Two links go to the publisher page, where the full text may need access.
| Paper | What it found | What we built | What we do not know |
|---|---|---|---|
| Camerer, Loewenstein and Weber (1989) | What informed people knew biased them, and they did not fully ignore it. Markets cut the bias by about half. | A cold reader that sees only the text | A forecasting task, not writing |
| Sweller and Cooper (1985) | Worked examples helped on later problems with the same structure, with one exception. They did not help on problems with a different structure. | One real example before the mechanism | Algebra, small groups. Our eval tests new cases. |
| Rawson, Thomas and Jacoby (2015) | Students who studied examples classified examples better than students who only re-studied definitions. The two orders did not differ significantly. | Terms defined, a real example, no claim about order | Short concepts, a short delay |
| Chandler and Sweller (1992) | Novices scored higher with the explanation next to the thing it explains. | Each term defined at its first use | One report, not jargon. 20 tested in each experiment. |
| Bullock and colleagues (2019) | Jargon lowered felt fluency, 4.57 against 5.27 on a seven-point scale. Hover-over definitions had no significant effect. | A warning above five defined terms. No study backs that number. | Felt fluency, not understanding. Hover text, not inline. |
| Kalyuga, Ayres, Chandler and Sweller (2003) | Help for beginners can lose its effect, and can even have negative effects, for more experienced learners. | Output that is easy to skip, and reader profiles | We know the studies only through the review |
Our hypothesis: a newcomer follows technical text better when three things hold. A reader with no context marks where they get lost. Claude fills each gap from the real source. The text opens with one concrete example.
No study tests this combination on technical documents for software newcomers. The method is a hypothesis. Read the human eval protocol. It has no results yet. If you run it, send us the result. We publish it even if the result is a tie.
We checked ourselves
On 2 November 2026 we asked five separate Claude agents to read every claim on our evidence page again, against the text of each paper. They found errors that our first check missed. The Sweller and Cooper first experiment had 62 students, not the 18 we wrote. Chandler and Sweller tested 20 of 26 apprentices, not 26.
We rewrote those lines in public. The agents are models too. They quoted the paper text, so a person can check each finding. See the account.
What it touches
- It reads your text, and your repository when it answers a stumble. The reader agent has no tools and sees only the text. This relies on Claude Code behavior that the docs do not describe. We tested it in version 2.1.316, and a test keeps the settings.
/greenhorn:explainpre-approves writes only under.greenhorn/in your project. It runs only its own two checker scripts, with any arguments after the.greenhorn/path./greenhorn:testwrites nothing. These settings are a guard, not a sandbox.- The scripts are TypeScript with no dependency. The two checker scripts import only Node's file module and each other. They make no network call and read no environment variable.
- MIT license. No account, no token and no telemetry in the scripts.
What it cannot do
The reader is a model, not a human newcomer. A clean result does not prove that a text is clear. The final test is a real person.
We have not tested the limits, such as 5 terms per text. They are defaults. The checker reads the shape of a text. It cannot tell whether a definition is true.
Install
/plugin marketplace add gagoar/gago-plugins
/plugin install greenhorn@gago-pluginsThe helper plugins unmistakable and iceberg come with greenhorn. If one is missing, /greenhorn:explain stops and prints the command to install it. The guide lists every command.
A greenhorn is a newcomer. We named the plugin for the reader it writes for.