---
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:

```bash
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:

```md
## 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:

```text
<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:

```text
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:

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