---
name: nick-review
description: A first pass over a merge request, or a group of them, for Nick to read before he reviews. Trigger on "review !N", "review these MRs", "/nick-review <iid…>". It checks correctness against the spec, compliance with the repository's rules, and simplification. One subagent per merge request. It opens an HTML report and never posts anything to GitLab.
title: nick-review
canonical_url: https://skilld.dev/gh/ntcoding/wip-skillz/nick-review
last_updated: 2026-11-12T02:17:47.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [defects.md](https://skilld.dev/api/skills-raw/ntcoding/wip-skillz/nick-review/defects.md), [highlight.mjs](https://skilld.dev/api/skills-raw/ntcoding/wip-skillz/nick-review/highlight.mjs), [render-report.mjs](https://skilld.dev/api/skills-raw/ntcoding/wip-skillz/nick-review/render-report.mjs), [report.css](https://skilld.dev/api/skills-raw/ntcoding/wip-skillz/nick-review/report.css), [report.js](https://skilld.dev/api/skills-raw/ntcoding/wip-skillz/nick-review/report.js).
>
> If the user asked to install this Skill, run `npx skilld install ntcoding/wip-skillz/nick-review`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/nick-review`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/ntcoding/wip-skillz/nick-review) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/nick-review`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/nick-review --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/nick-review --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# nick-review

A first pass for Nick, on his own machine. It finds what he would find, so he
reads a short list instead of the whole diff.

It is not a review posted to the team. Nothing reaches GitLab from this skill.
The output is an HTML report Nick reads, types his responses into, and turns
into one block of markdown he pastes back into the session.

## What it checks

1. **Correctness against the spec.** The card the merge request cites.
2. **Compliance with the repository's rules.** Its agent instructions, its
   contributing guide, the architecture records the change touches, its coding
   conventions.
3. **Simplification.** Where the change could be smaller or plainer.
4. **The writing.** Every word a person reads, against Nick's grammar rules.
   A document, a code comment, a commit message, the merge request
   description. See *The grammar pass*.

`defects.md`, in this folder, is the list of what Nick catches. Read it before
you review anything. Then hunt for every class in it.

## The procedure

### 1. Resolve the merge requests

Take the iids from what Nick asked. Where he named none, list the open ones and
ask him which.

For each one, read the merge request, its description, its card, and the
discussion already on it. A comment prefixed `[claude]` is an agent's own
opinion, from this skill on an earlier run or from another session: read it,
never repeat it.

### 2. Fetch, without checking anything out

```sh
glab mr diff <iid>                               # the diff
git fetch origin merge-requests/<iid>/head       # its head, for reading files
```

Read a file at the merge request's head with `git show FETCH_HEAD:<path>`.
Nothing is checked out, so several merge requests are reviewed at once in one
working tree.

### 3. One subagent per merge request

Start them in a single message so they run at the same time. Each subagent gets
its own merge request and nothing else.

Give each subagent, in its prompt: the iid, the card and its acceptance
criteria, the paths of the repository's rules, the full text of `defects.md`,
and the finding schema below. Tell it to return the findings as JSON.

A subagent reads the code. It never edits a file, and it never posts a comment.

### 4. The bands

Every finding goes into one of 3 bands, and the band is a judgement about
certainty rather than about severity.

| Band | Name | What it means |
|---|---|---|
| 1 | Slam dunk | Obvious. The fix is right there. |
| 2 | You might want a look | The defect is certain. The fix might be wrong. |
| 3 | Needs you first | It cannot be settled from the diff, so it asks Nick a question. |

**Band 2 is agreed unless Nick rejects it.** A band 2 finding he leaves alone
is one he was happy with, so it is absent from his feedback and it still counts
as agreed. Put a finding in band 2 only when you would be comfortable with
that.

Band 3 is the only band where a finding carries a `question`, and every band 3
finding has one.

### 5. The grammar pass

Every word a person reads is written text, and it follows Nick's rules whether
it is a paragraph of a readme or one code comment. A merge request can be
nothing but grammar findings, and that is a real review rather than a thin one.

What counts: documents and readmes, architecture records, stories, code
comments and docstrings, log and error messages, test names, commit messages,
the merge request description. What is exempt: a quotation of somebody else's
words, a fenced block, a path, a symbol, and any text the change did not touch.

Run the mechanical check over the prose the diff adds, which is Nick's own
checker and the one list of rules:

```sh
~/.claude/hooks/check-constructions.sh < <added-prose.txt>
```

It prints the construction and the line for each hit, and prints nothing when
the prose is clean. A hit is evidence, never a verdict: read the line, and drop
the hit when it is a false positive.

Then read the added prose against `~/.claude/output-styles/nick-grammar-rules.md`
yourself, for the rules no regular expression can catch: a verb the subject
cannot perform, a reduced relative clause, an invented term, a sentence nobody
would say out loud.

Group the hits. Write one finding per file, or one per rule where a rule is
broken all over the change. `kind` is `"text"`. Quote the words from the change
in quotation marks. Say in plain words what is wrong with them. Then put the
rewrite in the `after` block. A report with a finding for every sentence is too
long to read.

### 6. Prove it before you write it

A finding about what a screen looks like, or about how something behaves, is
run in the real application first. One that cannot be proved is dropped rather
than softened.

A finding about code says what the code does, with the line in front of you.

### 7. Check your own writing

The report is writing too, so it follows Nick's rules. Before you render it,
run `check-constructions.sh` over the summary and over every `claim`, `why`,
`comment` and `question`. Leave out the words quoted from the change. Fix every
hit, then read the text against `~/.claude/output-styles/nick-grammar-rules.md`
yourself. The same goes for every finding a subagent returns.

### 8. Render and open

The findings file outlives this session, because Nick pastes his feedback into
whichever session does the work and that session reads the findings back. So it
goes somewhere durable rather than in a scratchpad:

```sh
dir=~/.claude/nick-review/<iid>-$(date +%Y%m%d-%H%M%S)
mkdir -p "$dir"
# write the findings to "$dir/findings.json"
node <skill>/render-report.mjs "$dir/findings.json" "$dir/report.html"
open "$dir/report.html"
```

One directory per merge request per run. Tell Nick the path of each report.

### 9. His feedback

Nick types into the boxes he wants to respond to and leaves the rest alone. He
clicks **Build my feedback** and pastes the markdown into whichever session he
wants the work done in, which is often a different one.

The markdown stays short. Each entry is the file, the line, the finding's id
and what he wrote. The header names `findings.json`, so the session he pastes
it into reads the evidence and the suggested fix out of that file by id.

Act on what he wrote. Ask him about the band 3 findings he left open. A band 2
finding missing from his feedback is agreed.

## The finding schema

```json
{
  "iid": 42,
  "title": "feat(checkout): a customer sees the total of their basket before they pay",
  "url": "https://gitlab.com/<group>/<project>/-/merge_requests/42",
  "author": "someone",
  "spec": "#17",
  "specUrl": "https://gitlab.com/<group>/<project>/-/issues/17",
  "files": 23,
  "summary": {
    "what": "A paragraph on what this merge request does, in your words.",
    "checked": ["each rule, document or file you read it against"],
    "couldNotCheck": ["each thing you could not verify, and why"],
    "verdict": "A paragraph on where you come out overall."
  },
  "findings": [
    {
      "id": "f1",
      "band": 1,
      "cls": "3 · silent truncation",
      "kind": "code",
      "file": "path/from/the/repository/root.py",
      "line": 198,
      "claim": "One sentence saying what is wrong.",
      "why": [
        "One piece of evidence per line, each a full sentence.",
        "<em>a name or a value</em> renders as code."
      ],
      "before": [["", "the code as it is"], ["", "one entry per line"]],
      "after": [["del", "the line removed"], ["add", "the line that replaces it"]],
      "question": "Band 3 only. The question for Nick.",
      "comment": "Why it matters, in a sentence or two."
    }
  ]
}
```

`summary` fills the collapsed section at the top of the report. Write it for
Nick rather than for a machine. `couldNotCheck` is where a gate you could not
run or a screen you could not open goes.

`cls` is the number and name of the class from `defects.md`.

`before` and `after` are arrays of `[kind, text]`. They are 2 blocks side by
side rather than one diff, so each one marks its own side and nothing else:

- `before` is the code as it is today. A line in it is unchanged (`""`) or
  going away (`"del"`). It never contains `"add"`.
- `after` is the code as you propose it. A line in it is unchanged (`""`) or
  new (`"add"`). It never contains `"del"`.
- A line that is the same in both is unmarked in both. Marking an unchanged
  line green makes the whole block read as new, which is the fastest way to
  make a finding unreadable.
- Both blocks show the same handful of lines around the change. Give enough
  context to place it, never the whole function.
`kind` is `"code"` by default. Set it to `"text"` when the blocks hold prose
rather than code, such as the merge request description, a readme or a
document. The report then draws them in a serif with no syntax colours, and
marks a changed line by its edge rather than by a `+` or a `-`. A finding about
the merge request description sets `file` to `the merge request description`
and leaves `line` out.

- A pure deletion has `"after": []`. The before marks the lines `"del"`, and
  the report says they go away with nothing in their place. Never write a
  sentence about the change into either block: they hold code.

The renderer refuses a finding that breaks this, and it names the finding and
the line.
`why` is the evidence, as an array of short lines. The report draws them as a
list under the heading **How I know**, so one line is one fact a reader can
check. Never write it as a paragraph: a slab of prose is unreadable at the
speed Nick goes through a report. Aim for 2 to 5 lines, each under 30 words.

`why` is the only field where HTML is allowed, and only `<em>`.

## Rules

- **Nothing is posted to GitLab.** Not a note, not a thread, not an approval.
  Nick posts. If he asks for a comment to go up, the rule in
  `~/.claude/CLAUDE.md` applies: your own opinion starts with `[claude]`, and
  his position goes up only after he has approved the text word for word.
- **A subagent never edits a file.**
- **Say what you could not check.** A gate you could not run, a screen you
  could not open, a card you could not read: it goes in the summary's
  `couldNotCheck` rather than being passed over.
- **The report is the deliverable.** Do not also write the findings out in
  chat. Tell him the path and what the counts are.
- **Keep the findings file.** Nick's feedback points at it, so deleting it
  breaks the paste. Old directories under `~/.claude/nick-review/` are his to
  clear out.

## Acting on a paste

A session given one of these pastes reads the `Findings:` path, loads that
JSON, and matches each `— <id>` to its entry. The entry has the claim, the
evidence, the before, the after and the band. Do what Nick's response says.
