New in Tessl Academy: Code Review Loops

A hands-on course on agentic code review: running your first review, writing a lens that encodes one of your team's own rules, routing lenses by path, and closing the loop on every pull request. Four lessons, about 25 minutes each. Read them on the site or have your agent walk you through them.

Reviewing code is the part of the job that scales worst. It needs someone who knows the codebase, has time, and is willing to read carefully. When agents are writing most of the changes, that person runs out long before the changes do.

Simon covered Tessl Code Review yesterday: what it is, why we built it against whole pull requests rather than diffs, and how re-review keeps track of what a previous round already settled. This post covers the next question, the one you hit about an hour after installing it: your reviewer doesn't know your team's rules yet, and the useful version of it does.

That's Code Review Loops.

1npx tessl install tessl-academy/code-review-loops
2tessl launch skill --agent tessl-agent -i 01-your-first-code-review

Zoom

What's in it

Four lessons, in order, each building on the repository state the last one left behind.

Your first code review has you scaffold a small TypeScript service and a branch with three deliberate faults in it, then run a review over that branch three different ways and read what comes back — the outcome, the severities, the JSON. It also settles the naming collision that catches nearly everyone: tessl review run scores a skill, and tessl code review reviews your code. Both commands exist, they sound alike, and picking the wrong one costs a confusing five minutes.

The lesson plants three faults; the reviewer finds two. That's deliberate — the miss is why lesson two exists.

Writing a review lens starts from that missing finding. A lens is a skill: a SKILL.md with a name, a description of when it applies, and a body of review instructions. The four defaults ship in the tessl/code-review plugin and their sources are public, so you can fork one and see how it's put together. You write a lens that encodes a convention only your team keeps, run it beside the defaults, then test it in both directions so it fires on the bad case and stays quiet on the good one. That second half is the part people skip — it's the difference between a lens and a noise generator.

Routing lenses by path moves the configuration off the command line into a YAML profile in the repository, with globs and exclusions so each lens only runs where its rule applies. A review that skipped your files isn't a review that approved them.

Review on every pull request is the capstone: token, caller workflow, Action pinned to a commit SHA, advisory mode first and a gate later. Then a second round with one fix and one reply, so you watch earlier findings resolve as addressed, explained, or declined rather than getting raised again.

Zoom

The bits you'd otherwise learn the hard way

• -skill replaces the profile's default lenses rather than adding to them. Pass two and you get two, not six.
• A review takes at most eight lenses, and their order is preserved.
• Tessl doesn't go looking for your profile file. A bare tessl code review in a repo containing .tessl-code-review.yml runs the built-in standard profile and ignores your file. Nothing starts judging your code differently just because a file appeared.
• In CI, review policy comes from the default branch, not the branch under review — a pull request can change any file in the repository, including the one that decides how that pull request gets reviewed.
• @tessl-code-review is text your workflow matches, not an account.

Lesson three needs a CLI newer than 0.96.0, since YAML profiles landed after that. Lessons one, two, and four work fine on older versions.

How the course got built

The Academy is built in a way that's slightly unusual, and the code review course is the clearest example of it so far.

There's no pipeline that compiles curriculum. Lessons are assembled by an agent running a skill, and those skills are what we maintain.

Content lives as versioned components: a concept explained in under 300 words, a hands-on exercise, a starting repository state, a scoring rubric. There are 65 of these across six types, reused across lessons and courses. A human writes the recipe deciding which components a lesson uses and in what order. An agent running compose-lesson turns that recipe into the lesson you read, and generate-lesson-skill turns the lesson into the installable walkthrough that tutors you through it. The only deterministic step is the last one, where a build renders finished markdown into HTML. The site itself is static and knows nothing; the judgement sits upstream in the skills.

Each composed lesson records the component versions it was built from. When the CLI changes underneath us, a maintenance sweep works out which lessons are affected instead of us guessing, and writes a machine-readable verdict per concept. A lesson only counts as verified when every concept in it has a current pass.

That verification has a limit worth stating: a pass means the concept matches the docs, not that anyone ran the command. A wrong doc produces a confidently passing wrong lesson. We check for CLI drift and nothing else yet, and the sweep only runs when a human starts it.

Every skill in the repository also has to clear tessl review run at 80% before it ships. We teach the command, so the tooling that builds the teaching gets reviewed by it — writing a course about review with review switched off would have been a bad look, and more usefully, it caught real problems in our own lens descriptions.

Try it

The course is at tessl.io/academy/code-review. Read it there, or install it and ask your agent to guide me through a first code review and work through it in your own repository.

If you get through it, tell us about your lens — what convention you encoded, and whether the reviewer caught it. That's the feedback that shapes where this goes next. Find us in Discord.