/self-review

name: self-review
description: Self-review your changeset until merge-ready, with a fresh-context reviewer and a compact report for the PR.
disable-model-invocation: true
type: flow
license: MIT
metadata:
  version: "1.2"

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 (under autoaccept, the agent — Disposition walk) — 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 the open PR's title and description, plus the titles of the issues it links when the forge tooling offers them, distilled the same way; 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 th