One closed-loop iteration on an open PR — read CI checks + Claude / human review comments, triage against this repo's ADRs, apply valid suggestions, reply with reasoning on rejected ones, push fixes as Conventional Commits, and report status. Invoke as `/pr-iterate <PR#>`. Compose with `/loop /pr-iterate <PR#>` for continuous monitoring until green.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Critical
Do not install without reviewing
Runs ONE iteration of: snapshot → triage → act → poll. Designed to be re-fired by /loop for continuous monitoring, or invoked manually after a push to clean up bot feedback.
The goal is to get the PR to a state where:
When that state is reached, you stop. You never merge — that's the operator's call via the GitHub UI (branch protection still gates merging on green checks).
git push --force, git commit --no-verify, or modify branch protection./review-pr §5b). They are human-only: do not implement them, "fix" them, reply them away, or resolve their comment thread. Surface them verbatim at the top of your status report and leave them for the operator. (✅ SPECIFIED items need no action; ❌ MISSING items may be implemented — they're spec'd work.)feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert(scope): subject (subject ≤100 chars). The husky commit-msg hook will reject otherwise — that's the safety net.main land as signed merge commits (ADR-0044), so every PR commit reaches main with its own signature and shows up in the next release notes.# Worktree clean?
git diff --quiet && git diff --cached --quiet || { echo "uncommitted changes — abort"; exit 2; }
# Are we on the PR's branch?
PR_BRANCH=$(gh pr view "$PR" --json headRefName --jq .headRefName)
[[ "$(git branch --show-current)" == "$PR_BRANCH" ]] || { echo "wrong branch — abort"; exit 2; }
# Is local up to date with origin? (Avoid working on stale state.)
git fetch origin
LOCAL=$(git rev-parse HEAD)
REMOTE=$(git rev-parse "origin/$PR_BRANCH")
[[ "$LOCAL" == "$REMOTE" ]] || { echo "local behind / ahead of origin — pull first"; exit 2; }If any check fails, surface a clear one-line message and stop.
# Aggregate state in one place
gh pr view "$PR" \
--json title,statusCheckRollup,reviews,comments,headRefName,headRefOid,baseRefName,reviewDecision,mergeable,mergeStateStatus
# Per-check details + URLs to logs
gh pr checks "$PR"
# Inline review-thread comments (different endpoint than top-level .comments)
gh api "repos/{owner}/{repo}/pulls/$PR/comments" --paginateBucket what you find:
claude[bot], claude-review[bot] (and any other *[bot] accounts)[bot]/review-and-evaluate)Before triaging external bot comments, invoke /review-and-evaluate locally to get our own project-aware reading of the diff. The skill runs two parallel agents:
.agents/skills/review-pr/SKILL.md; two axes: 6 Axis-1 standards sub-agents (Security, API/CRUD, Pattern, Simplicity, Reuse/DRY, Test hygiene) produce a severity-bucketed finding list, and the Axis-2 Spec & Behavior sub-agent (Agent 7) produces the §5b behavior confirm-list. The confirm-list is a distinct output: ✅/❌ items triage normally below; ⚠️ UNSPECIFIED items bypass the verdict table entirely — hard rule 4 makes them human-only.CLAUDE.md, and docs/diary.md (the ADR record), then evaluates each finding for Apply / Skip / Discuss.The skill normally ends interactively ("Which items would you like me to apply?"). In the /pr-iterate context, bypass the question and consume the verdicts directly:
Verdict from /review-and-evaluate | What /pr-iterate does with it |
|---|---|
| Apply | Add to the iteration's Act list — fix it via one Conventional Commits commit. |
| Skip | Record it in the iteration report ("not applied — reason: …") and move on. |
| Discuss | Add to the escalation list. Don't apply; surface to operator at end of iteration. |
The local review is complementary to the bot review from claude-review. They look at the same diff with different lenses:
/review-and-evaluate: our own skill run, fresh per iteration, has full local file access + the live diary content.Treat them as two independent reviewers. If both flag the same issue → almost certainly worth applying. If they disagree → it's a Discuss/escalation candidate.
For each failing check:
# Find the run-id from the check URL or:
gh run list --workflow=<workflow-file> --branch="$PR_BRANCH" --limit 1 --json databaseId,conclusion
gh run view <run-id> --log-failed # cheapest — only the failing step's outputClassify the failure:
| Classification | Action |
|---|---|
| Build / install error (missing dep, lockfile drift) | Fix package.json or lockfile; commit fix(deps): ... |
| Typecheck error | Fix the type; commit fix(types): ... |
| Lint / format | Run the fixer; commit style: ... |
| Test failure — clear bug | Fix the bug; commit fix(<area>): ... |
| Test failure — test is wrong | Update the test, document in commit body; commit test(<area>): ... |
| Vercel deploy — env var / Corepack | Cross-reference the relevant carry-overs in docs/diary.md; usually a project-level config, not a code fix |
| Security / headers / CSP — spec violation | Read ADR-013, fix the route/middleware; commit fix(security): ... |
| I genuinely can't diagnose this from logs | Escalate. Don't guess at fixes. |
For each bot review comment:
Read the suggestion. Cross-reference with project policy:
CLAUDE.md and docs/diary.md (the live ADR record).For each human comment:
Answer it. Be direct, cite ADRs where relevant. Don't mark human threads resolved — only humans resolve human threads.
For applied fixes:
# One logical change per commit (merge-commit friendly, ADR-0044 — every commit
# lands on main and shows up in release notes).
git add <specific files, not -A>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject under 100 chars>
<body explaining why — reference the bot comment or check URL>
EOF
)"
git push # no --force, no --no-verifyTooling reminders:
commit-msg hook lints the message at write time. If it rejects, fix the message and retry — never --no-verify.git push to a feature branch is safe; never push to main from here.For replies on bot threads (inline review comments):
# Reply to an inline review-thread comment
gh api \
-X POST \
"repos/{owner}/{repo}/pulls/$PR/comments/$COMMENT_ID/replies" \
-f body="$REPLY_BODY"For replies on top-level PR comments:
gh pr comment "$PR" --body "$REPLY_BODY"Resolving threads (only for bot threads that are fully handled — code applied or policy cited):
# GraphQL — resolve a review thread
gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "..."}) { thread { isResolved } } }'(Get the threadId from the gh api listing of review threads.)
After pushing, CI takes 1–5 min. Two modes:
/pr-iterate <N>): stop here, report status. The operator re-invokes when ready./loop /pr-iterate <N>): the loop runner schedules the next iteration. Inside this iteration, return after step 3 + a brief status report. Don't sleep-poll inside one iteration.If running manually and the operator asked you to wait for the result, use:
# Wait until no checks remain pending — bounded
until ! gh pr checks "$PR" 2>&1 | grep -qE 'pending'; do sleep 30; done…but only if explicitly asked.
Stop iterating and report when ANY of:
End every iteration with a one-screen summary the operator can read at a glance:
PR #<N> — "<title>" — iteration <i>
Status:
Checks: <green>/<total> green · <failing> failing · <pending> pending
Bot threads: <open>/<total> open (claude: <X>)
Human threads: <unresolved>/<total>
/review-and-evaluate verdicts:
Apply: <X> · Skip: <Y> · Discuss: <Z>
This iteration:
Applied: <list of fixes with commit SHAs; mark source: bot|local|check>
Replied: <list of bot threads with one-line reasoning each>
Escalated: <items needing operator judgment — includes Discuss verdicts>
Next: <continue / stop — converged / stop — escalation>docs/diary.md 2026-05-18 + the v7 specinfra/terraform/modules/github-repo/main.tf.github/workflows/claude-code-review.ymlinfra/terraform/modules/github-repo/main.tfcommitlint.config.js + .releaserc.json + .husky/commit-msg/merge flow): CLAUDE.md "Use Conventional Commits" sectionSibling skills this one invokes:
/review-and-evaluate (.agents/skills/review-and-evaluate/SKILL.md) — the local review step inserted at iteration step 2./review-pr (.agents/skills/review-pr/SKILL.md) — used internally by /review-and-evaluate for the 6-sub-agent review.When citing an ADR in a reply, always include the number — future-me and future-collaborators will grep for it.
agranado2k/ai-report-platform
caeb0da
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.