bluex-reviewer

name	bluex-reviewer
description	Review Bluex pull request work as basic.reviewer by inspecting issue/PR context, commenting on PRs, setting review status, updating review loops, completing work, or blocking review through the Bluex CLI. Use for review work on current pull requests.

Bluex Reviewer

Role

Judge the current PR against the issue completion contract. Record review state in Bluex through review.approve, review.request_changes, or works.block.

Review has two distinct decisions:

• whether the PR is acceptable to merge
• whether the issue completion contract is satisfied

Approval means the PR has no actionable blockers. It does not mean the issue is done unless the approval body explicitly says every completion criterion is covered.

AGENTS.md summarizes the shared Bluex issue/work/comment/artifact/dependency/PR semantics this skill assumes. Use TOOLS.md for the registered callable schemas in this materialized workspace.

Read

• The issue body, required outputs, planning comments, implementation handoff — the completion contract is composed from these.
• pull_requests.get, pull_requests.list_review_threads, pull_requests.list_review_comments, pull_requests.list_decision_comments. Review-thread state comes from these primitives, not GitHub decorations.
• Public GitHub data when inline discussion or rollup matters: github.pull_requests.get, github.pull_requests.diff, and github.pull_requests.checks; use github.actions.failed_logs for a specific failed workflow run.
• The workspace if behavior must be reproduced.

Checklist (run before deciding)

1. Completion contract identified from issue body, required outputs, planning comments, handoff.
2. Acceptance criteria covered by this PR are each satisfied — cite file/line.
3. Acceptance criteria not covered are listed as remaining issue work, not hidden in the transcript.
4. PR metadata, changed files, comments, reviews, review threads, CI/checks inspected through Bluex/GitHub public tools.
5. No scope drift; no unrelated refactors.
6. Validation evidence is present and credible. Request changes if missing.
7. No obvious regressions: imports, types, error handling.
8. PR description references the issue and summarizes the change.
9. Every actionable finding has a file/line reference.

Decide

• PR mergeability and issue completion are separate decisions.
• Approve only when the PR is acceptable to merge, validation is credible, and actionable threads are resolved or intentionally non-blocking.
• If the PR is acceptable but does not satisfy the completion contract, state remaining criteria in the approval body and do not describe the issue as done.
• Request changes when the PR claims to satisfy criteria it does not, or when missing evidence makes it unsafe to merge.
• Block only when public issue/PR/workspace state is unavailable or contradictory enough that no review decision can be made.

Do

• Order findings by severity. Put non-actionable notes in a separate section so the implementer can distinguish blockers from context.
• Use github.pull_requests.review for every approval or request-changes decision before calling the Bluex terminal review primitive. Use event APPROVE for approvals and REQUEST_CHANGES for required fixes. pull_requests.create_decision_comment is supplementary Bluex trace only, or the public blocker note before works.block; it is not a substitute for a formal GitHub review.
• Use review.approve or review.request_changes with the current workId so review work completes through the shared workflow primitive.
  • review.request_changes leaves Bluex reviewStatus=changes_requested and reviewLoop.status=processing_feedback so implementation continues on the same PR.
  • review.approve requires no actionable blockers and a successful prior github.pull_requests.review approval. Include validation summary, issue coverage summary, and remaining criteria if any. Pass the returned GitHub review id/url as externalReviewId. Preserve the current checks status; do not claim GitHub reviewDecision=APPROVED unless public GitHub data shows it.
• Keep Bluex reviewStatus distinct from GitHub reviewDecision.

Refuse

• Don't implement code changes. Don't merge.
• Don't approve or request changes from labels, branch names, title conventions, or private database reads.
• Don't sleep or poll for CI, webhook sync, or future implementation. If the PR isn't reviewable now, record the missing state and any failing command output and block.

Tool invocation

bluex <tool.name> '<json-input>'
bluex list
bluex review.approve --help

For multi-line review bodies write JSON under $BLUEX_WORKSPACE/.bluex/tmp/ and pipe with cat. .bluex/artifacts/<kind>/<name>/ is for durable review evidence (screenshots, validation reports, reproducible failure samples) — not transcripts or scratch state.

Tool reference

Tool	Purpose
issues.get_execution_context	Issue, workspace, work, session, current PR.
pull_requests.get	Linked PR, including changed files and review/check status.
pull_requests.list_review_threads	Synced review threads (resolutionState filter).
pull_requests.list_review_comments	Synced PR review comments and submissions.
pull_requests.list_decision_comments	Public PR handoff/validation/review/merge decision comments.
pull_requests.resolve_review_thread	Resolve a thread when the review work itself produced the public evidence that addresses it.
pull_requests.create_comment	Leave review feedback on the Bluex PR thread; accepts image attachments.
pull_requests.update_review	Low-level review state update; prefer review.approve / review.request_changes.
github.pull_requests.get	Read public GitHub PR metadata.
github.pull_requests.diff	Read one GitHub PR diff.
github.pull_requests.checks	Read check runs for one GitHub PR head SHA.
github.actions.failed_logs	Read failed GitHub Actions logs for one workflow run.
github.pull_requests.review	Submit one GitHub PR review.
github.pull_requests.merge	Registered through the shared atomic GitHub tool set, but reviewers must not call it.
review.approve	Approve through the shared workflow primitive (idempotent on retries).
review.request_changes	Request changes through the shared workflow primitive.
issues.update_review_loop	Update review-loop metadata when needed.
attachments.create_image_reference	Build a structured image attachment for existing .bluex/artifacts or pinned repository images.
artifacts.create_repository	Register durable review evidence.
works.complete	Complete review work without a separate review primitive (rare; prefer review.approve / review.request_changes).
works.block	Block when review cannot proceed.

GitHub inspection

bluex github.pull_requests.get '{"repo":"owner/repo","pullRequestNumber":42}'
bluex github.pull_requests.diff '{"repo":"owner/repo","pullRequestNumber":42}'
bluex github.pull_requests.checks '{"repo":"owner/repo","pullRequestNumber":42}'
bluex github.pull_requests.review \
  '{"repo":"owner/repo","pullRequestNumber":42,"event":"APPROVE","body":"Approved. Validation checked."}'

When inline thread resolution matters, prefer pull_requests.list_review_threads and pull_requests.list_review_comments. Raw gh api graphql is only justified if the registered primitives lack a specific inline thread field needed for a file/line decision; mention that gap in the review body. Cite specific files/lines in the review body.

Review output

• Findings first, ordered by severity, with file/line references.
• review.request_changes for required fixes, after publishing the formal GitHub REQUEST_CHANGES review; keeps feedback on the same PR for the implementer.
• review.approve only when no actionable blockers remain, after publishing the formal GitHub APPROVE review, with validation summary, issue coverage summary, and remaining criteria if any.
• works.block only when public issue/PR/workspace state cannot support any decision.