slang-review-post-github

name	slang-review-post-github
description	Post filtered Slang clarity review candidates as one proper GitHub PR review. Use after candidate consolidation and scope filtering. Uses the bundled stdlib Python script to validate candidate formatting, map comments to PR diff lines, and submit a GitHub review through gh.
argument-hint	<candidate-markdown> <pr-number>
allowed-tools	["Bash","Read","Grep","Glob"]

Slang GitHub Clarity Review Posting

Post final clarity-review candidates as a standard GitHub PR review, not as individual PR thread comments.

Use the bundled script:

python .claude/skills/slang-review-post-github/scripts/post_github_review.py \
  --repo shader-slang/slang \
  --pr <number> \
  --candidates tmp/review-candidates/pr-<number>-clarity-workflow.md

The script uses only the Python standard library and shells out to GitHub CLI. In this repository on Windows or WSL, use gh.exe; the script follows that default and also accepts --gh <path> or GH_CLI=<path>.

Run with --dry-run first if the user has not explicitly asked to post.

Required Candidate State

Run slang-review-consolidate-candidates and slang-review-scope-filter before posting. Run slang-review-resolve-judgment-calls before posting when the file contains candidates marked Needs judgment call.

Each postable candidate must have:

• Status: Keep, Status: Revise, or Status: Needs judgment call.
• Scope decision: Direct or Scope decision: Contextual, plus a non-empty Scope rationale.
• Overlap decision: Keep or Overlap decision: Needs judgment call, plus a non-empty Overlap rationale.
• Location: path:line or Location: path:start-end, referring to PR-version lines that are present in the GitHub diff.
• A Proposed comment: blockquote.

Candidates with Status: Drop are ignored. Candidates with missing, ambiguous, or unfiltered status must cause posting to fail before any GitHub review is created.

If no --body or --body-file is provided, the script uses a ## Review Body section from the candidate file when present. The section content must be a strict blockquote: after trimming leading and trailing blank lines, every line before the next top-level section or candidate section must start with >. Use > for blank lines, and write any Markdown headings as quoted lines such as > ## Details. Do not use lazy continuation lines.

Example:

## Review Body
> Codex-authored clarity review: This PR needs more work before it is easy to review.
>
> ## Main Concerns
>
> - The central invariant is not stated.
> - The test comments do not explain the intended behavior.

## Kept

Agent Authorship Label

By default, make the primary GitHub review body clearly state that the review was generated by an agent. The agent must write that attribution directly into the review body. The posting script validates this instead of adding attribution text itself.

The review body must start with:

<agent name>-authored <optional review type> review:

The separator before authored may be whitespace instead of -. If there is no review type, use a single space between authored and review. The agent name may be any non-newline text up to 50 Unicode scalar values.

Examples:

GPT-4.1-authored clarity review:
Claude 3.7 Sonnet authored review:
OpenAI/GPT-4.1 (reviewer)-authored clarity review:

Use --acting-as-bot-user only when the initial user prompt or environment makes it clear that GitHub will attribute the review to a bot or agent account. That option disables the in-body attribution requirement.

Review Result

Default to COMMENT. This repository's automated-review policy treats bot-authored reviews as non-blocking advisory reviews, and may reject or dismiss automated REQUEST_CHANGES reviews.

Use REQUEST_CHANGES only when the initial user prompt explicitly asks for a blocking clarity review, local project policy for the account being used permits automated blocking reviews, and the workflow is not using --acting-as-bot-user.

Do not use APPROVE for this workflow.

By default, include Needs judgment call candidates in the review. Exclude them only if the user explicitly asks. The intended workflow is automated, so preserving a credible uncertain comment is better than silently dropping it.

Posted Comment Text

Post only the proposed review comment text, with no candidate ID, status, confidence, scope, notes, source context, or other metadata.

Do not use GitHub links or code blocks in the comment body as a substitute for proper review line comments. The script must attach each comment to the relevant diff line/range through the GitHub review API.

If a candidate concerns code or a contract outside the diff, its Location should identify the closest or most logical commentable diff line. The proposed comment should make the actual target clear; the posting script only validates that GitHub can attach the comment to the given line.

Failure Policy

The script should fail loudly and take no action if it cannot parse the candidate file, cannot validate a postable candidate's location against the PR diff, cannot determine the PR head commit, or cannot find or execute an appropriate GitHub CLI executable.

Script Tests

After editing the posting script, run:

python .claude/skills/slang-review-post-github/scripts/test_post_github_review.py