| name | paw-review-github |
| description | Posts finalized review comments to GitHub, leaving the review pending by default or submitting it under explicit verified authorization. |
PAW Review GitHub Skill
Post finalized comments to a GitHub review. Pending is the default. Submission is a separate authorized mutation with fail-closed target and head verification.
Reference: Follow Core Review Principles and Authorization Preflight from paw-review-workflow.
Prerequisites
Read both artifacts from .paw/reviews/<identifier>/:
ReviewComments.md
- Status is
finalized
- Every comment has a
**Final**: marker
- At least one comment is
Ready for GitHub posting
ReviewContext.md
Review Platform: github- Repository, PR number, and head commit are present
Preflight Status: passed- Authorization fields are complete
If these conditions fail, report the exact blocker. Do not create or submit a review.
For Azure DevOps or local contexts, skip GitHub mutations and use the artifact-only flow.
Output Policy
| Condition | Action |
|---|
Authorization absent; action pending | Create or reuse a pending review, then stop |
Explicit authorization; action submit | Create or reuse the exact pending review, verify the authorization tuple, then submit |
| Authorization ambiguous or preflight blocked | Stop before mutation and report the conflict |
| Requested mutation unavailable | Preserve artifacts and report capability unavailable |
| Review already submitted | Report the terminal state; do not replay |
Allowed submission events are APPROVE, REQUEST_CHANGES, and COMMENT.
Process
1. Load Policy and Finalized Comments
Read the target, head, capability, requested action, authorization, event, and authorized pending-review value from ReviewContext.md.
Filter ReviewComments.md:
- Include comments marked
Ready for GitHub posting
- Exclude comments marked
Skipped
- Use updated comment/suggestion text when present
- Posted text contains the final description and suggestion only; keep rationale, assessments,
**Final**: markers, and PAW artifact names local
Resolve one candidate review ID:
- Use the ID recorded in ReviewComments.md when present.
- Otherwise, use a concrete
Authorized Pending Review ID from ReviewContext.md.
- Treat
bind-created-review as a sentinel, not a concrete recovery ID.
If both artifacts contain concrete IDs and they differ, block and report the mismatch. Do not create a duplicate.
2. Resolve Current GitHub State
Before any mutation, use GitHub read capabilities to resolve:
- Authenticated repository identity
- PR number and state
- Live head commit
- Existing review ID and state, when recorded
The repository and PR must match ReviewContext.md. A closed PR, missing target, or head mismatch blocks mutation.
If the head changed:
- Leave any pending review untouched for manual inspection.
- Record
Preflight Status: blocked: head changed and the observed head in ReviewContext.md.
- Report that fresh analysis and authorization are required.
3. Create or Reuse the Pending Review
If no candidate review ID is recorded:
- Create one pending review on the verified repository and PR; omit the submission event.
- Immediately record the returned review ID in ReviewComments.md with
Status: Posting in progress.
- If
Authorized Pending Review is bind-created-review, replace it in ReviewContext.md with the returned ID.
- Re-resolve the recorded ID and confirm it is still pending on the verified PR.
- Add each missing postable inline comment, recording its comment ID immediately after success.
If a candidate review ID is recorded:
- Re-resolve it from GitHub.
- Reuse it only when it belongs to the verified PR and is still pending.
- If
Authorized Pending Review is bind-created-review, replace it with the re-resolved pending review ID before evaluating submission.
- Record the re-resolved ID in ReviewComments.md before adding comments when the local record was absent or stale.
- If it is already submitted, update local status and follow the terminal no-op path.
- Any other state mismatch blocks further mutation and preserves the review.
For either path, compare the finalized comments with locally recorded and live pending-review comment IDs. Add only missing comments and record each returned comment ID before continuing.
Update ReviewComments.md after comment posting completes:
**Status**: Posted to GitHub pending review
**Pending Review ID**: <id>
**Comments Posted**: <posted> of <finalized>
Each posted comment records its GitHub comment ID. Skipped comments remain unposted in the artifact.
4. Apply the Submission Decision
If Requested Output Action is pending, stop with the pending review.
For submit, require:
Submission Authorization: explicit- Allowed submission event
- Authorized target matching the repository and PR
- Authorized head matching the current live head
- Authorized pending review ID matching the exact pending review
Immediately before submission, re-read live GitHub state and verify this tuple:
repository + PR + live head + pending review ID + event
Every value must be present and equal to the authorization recorded in ReviewContext.md. On absence, ambiguity, mismatch, permission failure, or changed state:
- Do not submit or recreate the review.
- Keep the pending review available for inspection.
- Record the blocked reason in ReviewContext.md and ReviewComments.md.
- Report the exact mismatch.
When the tuple matches, submit that review with the authorized event. Record the submitted review ID, event, head, and timestamp in both artifacts.
5. Enforce Terminal Idempotence
A submitted review is terminal for this workflow run:
- Repeated authorization before submission confirms the same mutation.
- Repeated authorization after submission returns the recorded submitted state without creating or submitting another review.
- A new head requires fresh analysis, a new pending review, and fresh authorization.
6. Multi-PR Reviews
Treat each PR as a separate authorization boundary:
- Use its own ReviewContext.md and ReviewComments.md.
- Create/reuse and optionally submit one review per PR.
- Never reuse authorization, head, review ID, or event across PRs.
- Continue other PRs after a per-PR failure, but report partial success and preserve each failed pending review.
7. Artifact-Only Contexts
When the platform is Azure DevOps or local, or executable GitHub capability is unavailable:
- Do not call GitHub mutation tools.
- Keep ReviewComments.md finalized.
- Add manual posting instructions with final comment text.
- Record the platform, capability, requested action, and preflight result.
An explicit unsupported submission request must have been reported before the Understanding stage. Do not silently convert it to artifact-only output.
Policy Classification
True invariants
- Post only finalized comments.
- Keep skipped comments and internal rationale out of external review text.
- Verify the exact target, live head, pending review ID, and event before submission.
- Fail closed without mutating the pending review when verification fails.
Defaults
- GitHub output remains pending.
- Azure DevOps and local output remain artifact-only without executable capability.
User-configurable policy
- Explicit direction may request GitHub submission and select an allowed event.
- Users may override critique recommendations by changing final comment status before this skill runs.
Validation
Completion
Report one of:
- Pending review ID and posted/skipped counts
- Submitted review ID, event, verified head, and posted/skipped counts
- Terminal no-op for an already submitted review
- Blocked verification/capability result with the preserved pending review ID
- Artifact-only/manual posting location
