Make a changeset merge-ready before submission — no regressions, sound code, the project's\nconventions respected — and prove it was scrutinized: a fresh-context reviewer hunts for what\nwould block the merge, the author answers every finding, and a compact report — scannable by a\nmaintainer in seconds — records the outcome. The report is the review record only; the change's\nwhat/why belongs to the PR description (e.g. via /handover), never here.
\nOnly for a changeset you authored. The fresh-context reviewer exists to escape authoring\nblindness, so someone else's PR has nothing to escape and belongs to maintainer-review.
upstream remote when one exists (fork workflow), else of origin —\nvia git ls-remote --symref <remote> HEAD, never the often-absent local\nrefs/remotes/<remote>/HEAD; that failing (e.g. offline), the sole existing candidate among\nmain, master, develop/development (preferring upstream's remote-tracking ref, then\norigin's, then the local branch) — still ambiguous or none → ask. Explicit branches in the\ninvocation win; a detached HEAD → ask which branch is under review. State the chosen target.git adds first — a forgotten one\nships unreviewed later. The report this skill writes needs no sorting and is always excluded.\nNothing beyond the tip reviewed → pinned to its SHA; otherwise unpinned — reviewed,\nbut with no SHA for a maintainer to check the pushed head against, until stamped. Pinned is\npreferable, so suggest committing first when the work is ready for it — never insist, the\nstamp closes the gap later.git fetch the target's remote (local-only target → nothing to fetch; a failed fetch → say\nso and ask rather than diff stale refs), then diff from the merge base <base> of target and\nsource: git diff <base> for the working tree, git diff <base> <source> for a tip. No merge\nbase → usually a shallow clone or wrong target: deepen (git fetch --unshallow) and retry,\nelse ask — never fall back to diffing against the target itself, which presents its own\ncommits as the author's. Empty diff → probably a wrong target (typical: a fork's default\nbranch already holding the commits) — say so and ask for the true one; it needs no local\nref, git fetch <url> <branch> works by URL.Done when source branch, target, reviewed state (SHA, or working tree on SHA) and the diff's\nhash (git diff … | git hash-object --stdin) are recorded and the diff is non-empty.
.agents/docs/self-review-rules.md, when the project carries one, adds project-specific rules or\noverrides to the review mandate and process (extra focus areas, round cap, report handling, a pinned\nreview required — modified tracked files then block every round, fixes committed before the next) —\nnever to the Boundaries below. Absent → skip silently. Either way, the report states whether it was\nfound and applied.
A report already present → Stamp (below) first.
\nLoad and follow fresh-eyes-review on the reviewed state —\ninputs all explicit, so it runs without its confirmation step — with:
\nwip commits, opaque names) → ask the author for a one-liner, proposing a draft.\nEither way, state the intent used — the author must see what the change is judged against;Done when the reviewer has returned its findings — possibly none — its provenance, and its\ncoverage.
\nBefore the first finding, check which planning documents the task has (ticket, requirements,\nplan) and read any that exist: recommendations must weigh the full story. These documents still\nnever reach the reviewer, which sees only the distilled intent (Review above).
\nOne finding at a time, recommending a disposition with a one-line why — the author decides, and\ndiscussing the finding is offered as visibly as the dispositions themselves, never left an implicit\nescape hatch. Anything the author says that isn't a disposition is discussion, not a decision:\nanswer the question, check the code, revise the recommendation, do what they ask with the finding —\nthen the walk returns to that same finding, still open. Three dispositions close one:
\nNever drop or soften a finding: every one appears in the report with its disposition. Anything fixed\n→ a fresh round runs on the new state — fixes are new unreviewed code; committing between rounds\nstays the author's move (propose a commit message in the repo's style), demanded only where project\nrules require a pinned review. Rounds stop when one yields nothing fixed — clean, or every new\nfinding dismissed or deferred — or at the cap of 3 rounds per invocation, there to bound cost; the\nauthor can stop earlier at any point, or explicitly ask for rounds beyond the cap. Every fix no\nlater round covered leaves a \"fixes not re-reviewed\" caveat in the report. Dispositions carry\nforward across rounds: a re-raised finding matching a dismissed or deferred one keeps that\ndisposition and is not re-walked; one matching a fixed finding means the fix didn't hold — reopen it\nand walk it again. The report lists each finding once, with its latest disposition.
\nDone when every finding is dispositioned and a stop condition has ended the rounds.
\n<slug>.SELF-REVIEW.md in the task's planning home, per the project's planning-directory\nconvention (e.g. .agents/plans/<slug>/); reuse the slug of the task's existing artifacts\n(ticket, requirements, plan) — none → derive it from context (branch name, the changes); no\nplanning home resolvable → default to .agents/plans/<slug>/, stating the choice rather than\nasking. Re-runs and later rounds update the file in place — read it first and carry its rounds\nand dispositions forward, under the carry-forward rule — one file per task, never versioned\ncopies: its destination is a single upload. It is for pasting into the PR description or a\ncomment, not for committing, unless the project rules file says otherwise — either way committing\nis the author's move, never the agent's.
Two parts — maintainers drown in AI-generated review walls, so the visible part stays minimal.\nVisible, each line its own paragraph (blank lines between, no blockquote): the heading, Outcome,\noutcome-weakening caveats, Reviewed, By, verification evidence (e.g. testing performed).\nEverything else collapses into <details>, in order: Intent, Project rules, Diff,\nprocedural caveats, the rounds; the blank line after </summary> is required — without it the\nmarkdown inside won't render. Placement, unless project rules explicitly override: a caveat is\nvisible iff it weakens what Outcome claims (fixes not re-reviewed, incomplete coverage naming\nthe unreviewed files, a same-context fallback), procedural confirmations (e.g. files confirmed\nlocal-only) collapse; any other line is visible iff it records verification performed or qualifies\nthe outcome — proof-of-process collapses.
Compact above all: one line per finding, fusing location and concrete failure; the full prose stays\nin the session. The Reviewed line always carries the latest round's state (working tree on <SHA>, marked unpinned, when not a commit; once stamped, the new SHA with stamped from <that state>) and diffstat; Diff its full hash, for the Stamp; history lives in the round headings,\neach naming the state it reviewed. Provenance exactly as the environment reports it, unknown when\nit doesn't — never guessed or recalled; the reviewer's model, when it differs from the session's,\nappended to the By line as review by <model>; skill version from this file's frontmatter,\ndate = today.
# Self-review — my-feature → main\n\n**Outcome** 4 findings — 2 fixed, 1 deferred, 1 dismissed — final round clean\n\n**Reviewed** `def5678` (`my-feature` vs `main`, merge-base diff — 12 files, +340 −120)\n\n**By** <harness>, <model> — self-review v<version>, <date>\n\n<details>\n<summary>Review details (2 rounds)</summary>\n\n**Intent** <the intent statement the review ran against>\n\n**Project rules** `.agents/docs/self-review-rules.md` not present\n\n**Diff** `9f2c1e0b7d3a4c5e6f718293a4b5c6d7e8f90123`\n\n## Round 1 — `abc1234`, 4 findings\n\n1. `src/foo.c:142` — null deref when the timer expires mid-update → **fixed**\n2. `db/updates/xyz.sql:3` — DELETE misses linked_id rows, orphans on re-run → **fixed**\n3. `src/bar.c:210` — retry loop has no backoff, hammers the API during an outage → **deferred**:\n predates this change, author files it as a follow-up ticket\n4. `src/foo.c:97` — guard duplicates the check 4 lines up → **dismissed**: mirrors the pattern in\n this file, checked sound at :61 and :88; refactor out of scope\n\n## Round 2 — `def5678`, clean\n\n</details>\nDone when the report holds the outcome line, intent, changeset refs with diffstat, diff hash,\nprovenance with skill version and date, rules-file status, and every round with its reviewed state\nand dispositioned findings — each on its mandated side of the split.
\nStep 3's hash equal to the report's Diff → content unchanged (after committing the reviewed\nwork, an amend, a rebase leaving the diff byte-identical): no round; Reviewed line set to the\ncurrent state — a tip → stamped from <previous state> replacing unpinned — then Wrap up.\nDifferent → say so, Review onward. Done when the report carries the current state or Review has\nstarted.
Print: the report's project-relative path, with the instruction to paste its content into the PR\ndescription or a comment; a warning not to commit the report — a later git add . drags it into\nthe PR — unless the project rules file says otherwise; a reminder to run the project's usual\nchecks (build, lint, tests) before pushing — this skill never runs them; and that the pushed head\nmust match the reported SHA: unpinned → commit, then re-invoke to stamp; any later commit → the\nsame re-invocation, a stamp when the content held, else a re-run. Done when all four are printed.
git fetch; no commit, push, or PR operation — publishing is the author's.