/self-review

name: self-review
description: Self-review a changeset until merge-ready — a fresh-context reviewer checks it as a maintainer would, the author answers every finding, and a compact report for the PR proves the review happened.
disable-model-invocation: true
type: flow
license: MIT
metadata:
  version: "0.12"

Self-review

Make a changeset merge-ready before submission — no regressions, sound code, the project's conventions respected — and prove it was scrutinized: a fresh-context reviewer hunts for what would block the merge, the author answers every finding, and a compact report — scannable by a maintainer in seconds — records the outcome. The report is the review record only; the change's what/why belongs to the PR description (e.g. via /handover), never here.

Only for a changeset you authored. The fresh-context reviewer exists to escape authoring blindness, so someone else's PR has nothing to escape and belongs to `maintainer-review`.

Resolve the changeset

1. Resolve source and target. No input → current branch against the auto-detected target: the default branch of the `upstream` remote when one exists (fork workflow), else of `origin` — via `git ls-remote --symref <remote> HEAD`, never the often-absent local `refs/remotes/<remote>/HEAD`; that failing (e.g. offline), the sole existing candidate among `main`, `master`, `develop`/`development` (preferring `upstream`'s remote-tracking ref, then `origin`'s, then the local branch) — still ambiguous or none → ask. Explicit branches in the invocation win; a detached HEAD → ask which branch is under review. State the chosen target. 2. The reviewed state is the source as it stands — working tree when checked out, else tip. Uncommitted work is reviewed, not blocked, once the author sorts it: modified tracked files are part of the change or deliberate local-only tweaks (build config, data paths), the latter excluded from the diff (pathspec) and named in a procedural caveat — exclusion drops the whole path, so a tweak atop a changed file the author stashes first; untracked files likewise, and since the diff can't see them, those that belong the author `git add`s first — a forgotten one ships unreviewed later. The reports this skill writes need no sorting and are always excluded. Nothing beyond the tip reviewed → **pinned** to its SHA; otherwise **unpinned** — reviewed, but with no SHA for a maintainer to check the pushed head against, until stamped. Pinned is preferable, so suggest committing first when the work is ready for it — never insist, the stamp closes the gap later. 3. `git fetch` the target's remote (local-only target → nothing to fetch; a failed fetch → say so and ask rather than diff stale refs), then diff from the merge base `<base>` of target and source: `git diff <base>` for the working tree, `git diff <base> <source>` for a tip. No merge base → usually a shallow clone or wrong target: deepen (`git fetch --unshallow`) and retry, else ask — never fall back to diffing against the target itself, which presents its own commits as the author's. Empty diff → probably a wrong target (typical: a fork's default branch already holding the commits) — say so and ask for the true one; it needs no local ref, `git fetch <url> <branch>` works by URL. 4. Assemble the submission metadata as one block, hashed like the diff: the lines `subjects:`, `title:`, `body:`, `issues:` in that order, each followed by its value's lines verbatim — subjects from `git log --format=%s <base>..<source>`; from the target forge's open PR of source into target, its title, description and the issue ids it lists as linked (as the forge shows them, sorted, one per line); nothing under a label without a value (e.g. no PR yet) — every line LF-terminated, CRLF folded to LF, each value's trailing blank lines dropped.

Done when source branch, target, reviewed state (SHA, or working tree on SHA), the diff's hash (`git diff … | git hash-object --stdin`) and the metadata's are recorded and the diff is non-empty.

Project rules file

`.agents/docs/self-review-rules.md`, when the project carries one, adds project-specific rules or overrides to the review mandate and process (extra focus areas, round cap, full rounds only, report handling, a pinned review required — modified tracked files then block every round, fixes committed before the next) — never to the Boundaries below. Absent → skip silently. Either way, the report states whether it was found and applied.

Review

A report already present → Stamp (below) the latest first.

Load and follow [fresh-eyes-review](../fresh-eyes-review/SKILL.md) on the reviewed state — whole in a changeset's first round, narrowed per Rounds below in any later one — inputs all explicit, so it runs without its confirmation step — with:

• an intent statement — one or two sentences distilled from the task's ticket or requirements

when the planning home holds them, never the document itself (it carries the author rationale excluded below), else derived from the branch name and commit subjects; derivation yielding noise (`wip` commits, opaque names) → ask the author for a one-liner, proposing a draft. Either way, state the intent used — the author must see what the change is judged against;

• excluded paths: the planning home and the reports — author rationale and past dispositions must

never reach the reviewer. Planning files the changeset itself touches ship in the PR, so they are reviewed like any other change; the reports stay excluded always;

• the mandate framed as a maintainer's merge gate — would anything here block the merge? — and

extended by: the project's own governing docs (contributing, agent instructions, codestyle) run as a checklist, not as background reading, against every changed file, the unchanged code the change newly relies on, and the submission itself, whose metadata block (step 4) the prompt must carry