agentleFS
ashaychangwaniashaychangwani/imprint/.agents/skills/pr-review-convergence/SKILL.md

pr-review-convergence

Skill24 starsChanged 34 days agoMITView on GitHub

Prepare a code branch and pull/merge request for human review through safe rebasing, repository-specific validation, multiple independent subagent review rounds, evidence-based fixes, conventional commits, pushing, PR creation, and CI babysitting. Use when asked to prepare, polish, or finalize a PR/MR; obtain several reviews; iterate until clean; or make a branch ready for human review.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 10 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Read repository instructions such as AGENTS.md, CLAUDE.md, contributing guidance, and relevant local skills completely.

    line 14
  2. Distinctive:

    Never use destructive resets or force-push without explicit authorization.

    line 18
  3. Distinctive:

    Never bypass hooks. Stop if the diff contains credentials, recordings, personal data, or another public-repository violation.

    line 19
  4. Distinctive:

    Create a short plan covering rebase, validation, review rounds, commit, push, PR creation, and check monitoring.

    line 25
  5. Very specific:

    Run repository-prescribed checks before asking reviewers to inspect avoidable failures.

    line 44
  6. Distinctive:

    Run focused tests for changed behavior.

    line 54
  7. Distinctive:

    Use two or three read-only subagents in parallel with non-overlapping scopes.

    line 62
  8. Distinctive:

    After fixes, start a fresh convergence round.

    line 76
  9. Distinctive:

    Before pushing, fetch the source branch again.

    line 89
  10. Distinctive:

    Do not include sensitive local paths, recordings, trace payloads, credentials, or private data in commits or the PR body.

    line 104
  11. Distinctive:

    all required remote checks are green.

    line 120

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PR Review Convergence

Drive the branch to a genuinely reviewable state. Treat “open the PR” as an intermediate step; completion requires green checks and no unresolved actionable review findings.

1. Establish scope and guardrails

  1. Read repository instructions such as AGENTS.md, CLAUDE.md, contributing guidance, and relevant local skills completely.
  2. Inspect git status, the current branch, remotes, upstream, source branch, complete diff, and recent history. Preserve unrelated user changes.
  3. Never use destructive resets or force-push without explicit authorization. Never bypass hooks. Stop if the diff contains credentials, recordings, personal data, or another public-repository violation.
  4. Match mutations to the user's authority. A review-only request permits inspection and local validation, not commits, pushes, or PR creation. Only proceed through remote steps when the user explicitly asked to prepare, create, push, or update the PR/MR; otherwise stop after the review handoff.
  5. Create a short plan covering rebase, validation, review rounds, commit, push, PR creation, and check monitoring.

2. Rebase safely before review

Skip this section for review-only requests: inspect the branch against its declared source without stashing, rebasing, committing, or otherwise mutating the user's worktree.

Fetch the source branch, normally origin/main. If the worktree is dirty, stash tracked and untracked changes under a descriptive name, rebase, restore the stash, and verify every change returned. Resolve straightforward conflicts without discarding either side; ask only when resolution changes product intent.

Record the rebased commit so later source-branch movement can be detected.

3. Validate the implementation

Run repository-prescribed checks before asking reviewers to inspect avoidable failures. At minimum for Imprint:

bun run lint
bun run typecheck
bun test
git diff --check

Run focused tests for changed behavior. If the website changed, build it and visually inspect desktop and mobile layouts. Exercise important behavior live when safe and proportionate. Distinguish an unrelated flaky test from a real failure by reproducing it in isolation, then rerun the full gate; do not simply dismiss it.

4. Run independent review rounds

Use two or three read-only subagents in parallel with non-overlapping scopes. Give them the raw diff, files, tests, or artifacts and the review objective; do not seed them with expected findings.

Recommended first-round scopes:

  • correctness, security, privacy, and failure behavior;
  • concurrency, lifecycle, memory bounds, and test gaps;
  • public API, documentation, benchmark methodology, and provenance.

Personally verify every finding against code or a reproduction. Fix all valid issues in the main worktree, add regression tests, and rerun focused checks. Explain rejected findings with concrete evidence.

After fixes, start a fresh convergence round. Ask reviewers to inspect the current state rather than confirm a described fix. Iterate until every reviewer reports clean or only explicitly documented, non-blocking residual risks remain. Do not declare convergence while an actionable medium-or-higher issue is open.

5. Review and commit the final diff

Re-read the full diff and status. Ensure intended new files are included and temporary artifacts are absent. Stage only in-scope files, inspect both git diff --cached --stat and git diff --cached, then create a conventional commit whose message describes the branch’s primary user-facing outcome.

Before pushing, fetch the source branch again. If it moved, rebase the commit and rerun the relevant checks. This second fetch closes the race between the initial rebase and a long review cycle.

6. Push and open the PR/MR

Push the current branch with an upstream. Use a conventional PR title and a description containing:

  • a concise summary and rationale;
  • key design and safety bounds;
  • benchmark or live-validation evidence with an honest denominator;
  • tests run and known residual limitations;
  • reviewer attention areas.

Do not include sensitive local paths, recordings, trace payloads, credentials, or private data in commits or the PR body.

7. Babysit checks to green

Monitor all PR checks to completion. Inspect logs for every failure, reproduce it locally, fix it, rerun relevant checks, commit conventionally, rebase from the latest source branch as required by repository policy, push, and continue monitoring. Also inspect automated review comments and resolve valid findings.

Finish only when:

  • the worktree and commit contain exactly the intended change;
  • local required checks pass;
  • independent reviews have converged;
  • the PR exists with an accurate description;
  • all required remote checks are green; and
  • the final handoff states the PR URL, commit, checks, review outcome, and any residual risk a human reviewer should know.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.