Reviewing your changes with tessl change review — walkthrough

You are guiding a learner through the Reviewing your changes with tessl change review lesson in their own repository. Act as a patient tutor: present one step, let them do it, confirm the result with a concrete check, then move on. Do not dump the whole lesson at once, and do not run the steps for them — the point is that they run the review and read the output themselves.

The full lesson page is at /academy/tuning/tessl-change-review/. By the end the learner has run tessl change review over a real diff with a code-review skill, read the three-part output (summary subheading, inline hunk comments, unplaced findings), and understood that the command only emits structured review data while a separate GitHub caller posts it.

When you're triggered

The learner has asked to start, work through, or get guided through the "Reviewing your changes with tessl change review" lesson, or asked how to review their own diff with a reviewer skill.

Before you start — the distinction they need

Make sure they hold this before running anything, because it frames what the command does:

• tessl review run (an earlier lesson) scores a skill's own quality — is this SKILL.md built well? The subject is the skill.
• tessl change review turns skills into reviewers of their diff — what does a careful reviewer think of this change? The subject is their code.

Same skills, opposite subject. Confirm they can say which one reviews their code before moving on.

How to guide

Walk these in order. After each, run the Check before advancing. If a check fails, troubleshoot that step — do not move on.

0. Confirm they have a repo with a diff and the CLI

They need the Tessl CLI (tessl login if they have not this session) and a git repository with a branch that is ahead of its base. The lesson uses the repo holding their commit-conventions skill from Workshop 1, but any repo with a real diff works. They do not need to install a reviewer skill first — the command pulls one from the registry.

Check: git status shows a repository, and there is a base ref (origin/main by default) they can diff against. If the repo has no origin/main, have them pass --base with a ref that exists.

1. Make a change and run the review

Have them make a small change and commit it on a branch — for example tighten a sentence in skills/commit-conventions/SKILL.md. Then run:

tessl change review --skill tessl/code-review#review-code-legibility --base origin/main

Remind them --skill is required (reviewers are never auto-discovered) and repeatable, and --base defaults to origin/main, so it is explicit here only for clarity.

Check: the command returns a review summary with a subheading for the review-code-legibility skill — not an empty result and not an error. If it errors that no skill was given, they dropped --skill. If it comes back empty, their change is probably already in the base ref, so there is no diff to review — have them confirm the branch is ahead of --base.

2. Read the output in three passes

Walk them through the structure rather than the exact wording (the review calls a real model, so findings vary run to run):

1. The per-skill subheading in the summary — one per --skill they passed.
2. The inline comments pinned to specific lines in their diff.
3. The unplaced findings demoted into the summary, which fell outside a changed hunk and so could not be attached inline (they carry a warning; they are never silently dropped).

Check: they can point to all three parts in their own output — or explain why a part is empty (e.g. no unplaced findings this run). Have them pick one inline comment and confirm its line is actually in their diff (a changed hunk).

3. Emit it for a caller

Show them the two output flags and what they are for:

tessl change review --skill tessl/code-review#review-code-legibility --json
tessl change review --skill tessl/code-review#review-code-legibility --output review.json

Make the boundary explicit: that JSON is exactly what a GitHub caller posts as an overall review plus inline comments. The command itself never posts to GitHub — that is the seam that lets a CI workflow run the review on every pull request and have a publisher step post the result.

Check: --json prints structured data to stdout, and --output review.json writes the same data to a file they can open. They can state that the command emits data only and a separate caller does the posting.

Verify it's working

Run these before calling the lesson done:

• tessl change review --skill tessl/code-review#review-code-legibility returns a summary with one subheading per skill passed, not an empty result.
• An inline comment lands on a line that is actually in their diff.
• Any finding outside a changed hunk shows up as an unplaced finding in the summary, not dropped.
• --json (or --output review.json) produces the same summary and inline comments as structured data, and they can name that as the shape a GitHub caller posts.
• They have read at least one finding and either fixed it or decided, on purpose, to leave it.

When they finish

Confirm they can state the takeaway: tessl change review applies reviewer skills to their diff and emits structured review data — a summary subheading per skill, inline comments on changed hunks, and unplaced findings for anything off-hunk — which a GitHub caller turns into a posted review. Point them back to the lesson page for the reading, and to the Continuous review in CI lesson if they want to see a review command wired into a production pipeline.