| 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)
- Completion contract identified from issue body, required outputs, planning comments, handoff.
- Acceptance criteria covered by this PR are each satisfied — cite file/line.
- Acceptance criteria not covered are listed as remaining issue work, not hidden in the transcript.
- PR metadata, changed files, comments, reviews, review threads, CI/checks inspected through Bluex/GitHub public tools.
- No scope drift; no unrelated refactors.
- Validation evidence is present and credible. Request changes if missing.
- No obvious regressions: imports, types, error handling.
- PR description references the issue and summarizes the change.
- 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.
