Annotate a merge request for reviewers
A reviewer reading an AI-authored diff spends most of their time reconstructing three things the author already knew: why this change exists, what behavior changed, and who calls this code. This skill writes those three things down, in plain language, at the level of the merge request - not as source-code comments.
Annotations come in three layers, with different rules:
| Layer | Coverage | Carries |
|---|---|---|
| Overview - one MR-level comment | always | the map of the whole change |
| File - one comment per changed file | always, except autogenerated files | what this file's change means |
| Inline - anchored to a diff line | only genuinely non-obvious spots, budgeted | why this particular code is like this |
File coverage is unconditional: a reviewer opening any file in the diff must find an explanation of it. The judgment call - what is worth explaining and what is obvious - applies within a file, to methods and individual hunks, never to whether the file gets covered at all.
Operating modes
| Mode | When | What it does |
|---|---|---|
annotate | First run on an MR | Builds the full annotation set, previews it, posts it after approval |
sync | After every push to the MR branch | Re-checks existing annotations against the new diff; updates, removes, or adds only what changed |
If annotations from this skill already exist on the MR (detect by marker, see §7), run sync, not annotate - re-running annotate duplicates comments.
1. Preflight
Establish, before writing anything:
- Platform and MR identity.
git remote -v→ gitlab.com/self-hosted GitLab, github.com, or Bitbucket. Then find the open MR for the current branch (glab mr view,gh pr view). If there is no MR yet, stop and say so - this skill annotates an existing MR; it does not create one. - Diff range. Always
git merge-base HEAD origin/<target-branch>→<base>..HEAD. Never diff against the bare target branch tip: unrelated commits that landed on target would show up as this MR's changes. - Language. Write annotations in the language the project's MRs already use (check existing MR/PR descriptions and comments). Default to the language the user is speaking to you in.
- Authority to post. Posting to an MR is visible to the whole team and notifies reviewers. Default to a dry-run preview in the conversation and post only after the user approves. Skip the preview only if the user has already said to post without asking.
Read references/platform-gitlab.md, references/platform-github.md, or references/platform-bitbucket.md for the exact commands - the comment APIs differ in ways that matter (file-level anchoring, resolvability, update semantics).
2. Build the change inventory
The two scripts live next to this file, in scripts/. Invoke them by absolute path, built from this skill's own directory - the working directory during a run is the user's repository, not the skill, so a bare scripts/... path fails. Below, $SKILL stands for the directory containing this SKILL.md (e.g. ~/.claude/skills/annotate-merge-request for a user-level install, or the plugin's skills/annotate-merge-request when loaded from a plugin).
python3 "$SKILL/scripts/diff_inventory.py" <base>..HEAD --json > /tmp/sdmr-inventory.json
Per changed file this gives: change kind (added/modified/deleted/renamed), requires_file_comment (false only for autogenerated/vendored files), a file_fingerprint, and the file's hunks with new-side line numbers (what inline comments must anchor to), nearest enclosing symbol, and triviality signals. For spec and test files it also emits test_cases - every case in the file with its status (unchanged / adapted / added / removed), computed by comparing case bodies between the two revisions rather than read off the diff. It is a heuristic map for your reading, not a substitute for it - read the actual diff for anything you are going to describe.
Each hunk's anchor is a suggestion (its first added line); added_lines lists every line in that hunk you could anchor to instead. Pick the line the explanation is actually about.
Hard constraint: an inline comment can only anchor to a line that appears in the diff. Neither GitLab nor GitHub lets you comment on untouched code far from a hunk. Anything you want to say about code the MR did not touch goes in the file or overview comment, never inline.
3. Layer 1 - cover every changed file
Every file the inventory marks requires_file_comment: true gets exactly one file-level comment. No exceptions, no budget, no judgment call about whether it is "interesting enough".
The only exemption is autogenerated and vendored output - lockfiles, dist/, snapshots, codegen, minified bundles, vendor/. The inventory flags these; if it misses one your project generates, exempt it too and tell the user which pattern to add.
What varies is shape and length, not existence:
- A file with real logic changes gets the full template (
references/annotation-format.md): role, why it changed, before → after, reached from. - A spec or test file gets a test-case list instead - every case it now contains, each with a status (
unchanged/adapted/added/removed) and, for the changed ones, a short description. The standard template is wrong for specs: nothing calls them, so the entry-point section is empty by construction. The inventory computes the statuses for you (test_casesper file);adaptedcases are the ones a reviewer most needs, so they come first and must say whether the call shape or the expectation changed. Full rules inreferences/annotation-format.md. - A mechanical file gets one line that lets the reviewer skip it with confidence:
Import paths only - follows the rename of PricingService; no behavior change. - A deleted file gets one line on why it is gone and what replaced it - often the single most useful annotation in an MR.
Anchor these as file-level comments (subject_type=file on GitHub, position_type=file on GitLab), not on a line. They attach to the file header, so they do not interleave with code and the reviewer meets one as they open each file. Where an instance does not support file-level anchoring, fall back to the file's first changed line - the platform references give the exact fallback.
Writing one-liners well is the whole skill here. Volume now scales with file count, so a mechanical file described in three paragraphs is a defect, not thoroughness.
4. Layer 2 - the overview comment
One comment at MR level, the entry point for the whole review, structured exactly as references/annotation-format.md specifies:
- Intent - what problem this MR solves, in two or three sentences, in plain language. No restating the diff.
- Before → after behavior - what an observer of the running system would notice. For a new component, say "new" rather than inventing a "before".
- Entry-point graph - how a reader reaches the changed code from a real entry point (HTTP route, CLI command, event handler, cron, exported API). Bounded at 3 levels; one line per changed area, not per file.
- Reading order - which file to open first, which are mechanical follow-through.
- Index of inline comments - links to each inline annotation.
The overview has its own volume limits (max 7 reading-order entries, max 5 behavior rows, no per-file enumeration - the file comments do that). They are in references/annotation-format.md; respect them, or the overview becomes the wall of text the file comments were meant to prevent.
Verifying the entry-point graph
Never guess a call graph. A fabricated caller list is worse than no annotation: it is confidently wrong and the reviewer will trust it. For each claimed edge, find the caller with an actual search (rg -n 'symbolName' across the repo, including tests and config), and follow it upward until you reach an entry point or 3 levels, whichever comes first. If a symbol's callers cannot be resolved - dynamic dispatch, DI container, reflection, a string-keyed registry - write entry point unresolved (<reason>) rather than a plausible-sounding chain.
5. Layer 3 - inline comments, only where the code is non-obvious
This is the one layer with a judgment call. Run the significance test from references/significance-test.md on every method and hunk. The short version:
Annotate when the reader could reasonably ask "why is this like this?" - non-obvious intent, a behavioral change that is not visible in the diff, a non-local consequence, a deliberate trade-off, an unusual algorithm, a workaround, a constraint from outside the file, or an interaction with another change in this same MR.
Skip when the code explains itself to a competent reader of this codebase: a 5-10 line helper that title-cases a string, a DEBOUNCE_MS = 300 constant, an obvious null check, a mechanical test update. The file comment already covers the file; an inline comment here would repeat it at lower value.
The size of the code is not the test - its inferential distance is. A 6-line helper inside a custom encoding scheme needs a comment; a 200-line generated snapshot file does not.
Budgets (defaults; the user may raise them explicitly):
- At most 3 inline comments per file, at most 12 per MR.
- These are ceilings, not quotas. A file whose story is fully told by its file comment gets zero inline comments, and that is the normal case.
- Exceeding a budget is a signal, not a license: if more than 12 spots in one MR are genuinely non-obvious, the MR is too large, or the explanation belongs in the overview where it can be told as one story. Say that to the user.
Each inline annotation uses the same sections as the file comment, scoped to that hunk, and stays short - 3 to 6 lines, read inside a cramped diff view.
6. Cross-references within the MR
When a change only makes sense together with another change in the same MR, link them. Cross-references usually belong in the entry-point graph, but also appear in intent ("needed because now passes X") and before/after ("the old path still exists, see "). File comments are the most natural place for them: This file's new contract is consumed by [[ref:order-controller]].
A comment URL does not exist until the comment is posted, so cross-linking takes two phases:
- Post every comment with a placeholder token (
[[ref:<slug>]]) where a link to another annotation belongs. - Collect the created comments' ids/URLs, then edit each body, replacing tokens with real links.
Plan the slugs before posting - every [[ref:...]] token must resolve in phase 2, and a leftover token in a posted comment is a visible defect. Phase 2 is not optional.
7. Post, with an identity marker
Every comment this skill creates ends with a marker line that is invisible in rendered markdown:
<!-- sdmr:v1 kind=overview -->
<!-- sdmr:v1 kind=file slug=<slug> anchor=<file> ffp=<file-fingerprint> -->
<!-- sdmr:v1 kind=inline slug=<slug> anchor=<file>@<new-line> fp=<hunk-fingerprint> -->
Use the file_fingerprint from the inventory for ffp= and the hunk fingerprint for fp=. The marker is what makes sync possible: it identifies the skill's own comments, what each was attached to, and the fingerprint of the code it described. Never post an annotation without one; never edit a human's comment.
Leave annotations unresolved. A resolved thread renders collapsed, so the reviewer would have to expand every annotation one by one - which hides exactly what the annotation exists to show. Post them open and let the reviewer resolve each one as they read it; that click is their own "read it" marker.
The cost of that choice: where the project requires all threads resolved before merging (GitLab's All threads must be resolved, GitHub's Require conversation resolution), the annotations must be resolved before the merge button unblocks. With a file comment per file that is now a real number of clicks, so tell the user when you detect such a setting, and offer to bulk-resolve at the end. Commands for both are in the platform reference files.
8. Sync after every push
New commits silently invalidate annotations: the code a comment describes may have moved, changed meaning, or disappeared - and new files arrive with no coverage at all. Re-run this skill in sync mode after each push to the MR branch.
python3 "$SKILL/scripts/sync_state.py" --inventory /tmp/sdmr-inventory.json --comments /tmp/sdmr-comments.json
--comments is repeatable and takes the platform's raw JSON as-is - on GitHub that is two calls (review comments and issue comments), so pass both files.
It classifies every existing annotation as ok (anchor and fingerprint unchanged - leave it alone), moved (same code, new line - re-anchor), stale (the code it described changed - re-read and rewrite), or orphaned (file or hunk is gone - delete). It also reports file coverage - which changed files still have no file-level comment, which are exempt - and uncovered hunks that are now candidates for an inline comment.
Then: fix only what it flagged, always rewrite the overview comment in place (it summarizes the whole MR, so any push can invalidate it), and re-run phase 2 of §6 so cross-reference links still point at live comments. A MISSING row in file coverage is not optional work - a new file with no comment is the one gap this skill exists to prevent. Follow references/sync-after-push.md for the force-push case, deleted-comment handling per platform, and how to avoid churning comments that did not actually change.
Mention to the user, once, that this needs to run after each push, and that references/sync-after-push.md has an optional pre-push git hook if they want it automatic.
9. Report
Tell the user:
- how many file comments were posted, and how many files were exempt as autogenerated;
- which spots got inline comments, and which candidates were deliberately skipped as obvious - that list is how they calibrate the significance test;
- any budget you hit, and what lost out;
- anything you could not verify, especially unresolved entry-point chains.
Reference files
references/annotation-format.md- exact structure of the overview, file, and inline comments, with worked examplesreferences/significance-test.md- annotate/skip rules for inline comments, and the autogenerated exemption for file commentsreferences/platform-gitlab.md-glab/REST commands, file and line positions, resolvabilityreferences/platform-github.md-gh apicommands,subject_type=file, line/side anchoring, outdated commentsreferences/platform-bitbucket.md- Bitbucket mapping (untested - treat as a starting point)references/sync-after-push.md- staleness classification, coverage gaps, force-push handling, optional git hookscripts/diff_inventory.py- parses a diff range into an annotatable inventory (JSON)scripts/sync_state.py- classifies existing annotations and reports file-coverage gaps