| name | slang-review-clarity-workflow |
| description | Run the full Slang clarity review workflow: generate high-level and fine-grained candidates, consolidate overlap, filter for PR-author scope, and optionally post one GitHub PR review. Use when asked to perform an end-to-end clarity-focused review. |
| argument-hint | <pr-number-or-diff-path> |
| allowed-tools | ["Bash","Read","Grep","Glob","Write","Edit"] |
Slang Clarity Review Workflow
Coordinate the full clarity-review process.
Do not integrate this with the ordinary REVIEW.md bug-review process unless the user
explicitly asks. This workflow has a different purpose: produce and post clarity-focused
review feedback.
Files
For PR <number>, use:
tmp/pr-diff.patch
tmp/pr-files.txt
tmp/pr-view.json
tmp/review-candidates/pr-<number>-clarity.md
tmp/review-candidates/pr-<number>-fine-grained-clarity.md
tmp/review-candidates/pr-<number>-clarity-workflow.md
The first two candidate files are raw generation outputs. The workflow file is the canonical
file after consolidation. After consolidation, update the canonical file in place. The
canonical file may also contain top-level ## PR Summary and ## Review Body sections before
candidate entries.
Workflow
-
Save the PR diff and file list under tmp/ using Windows-native gh.exe:
mkdir -p tmp/review-candidates
gh.exe pr diff <number> -R shader-slang/slang > tmp/pr-diff.patch
gh.exe pr view <number> -R shader-slang/slang --json files -q '.files[].path' > tmp/pr-files.txt
gh.exe pr view <number> -R shader-slang/slang --json title,body,files,additions,deletions > tmp/pr-view.json
-
Create a short PR summary. Compare what the PR title/description says with what the diff
appears to do. Note mismatches and the PR's apparent value proposition.
-
Run slang-review-clarity to produce high-level candidates.
-
Run slang-review-fine-grained-clarity to produce fine-grained candidates.
-
Before consolidation, do a generation coverage audit. Re-read tmp/pr-files.txt, the raw
candidate files, and the changed hunks. Confirm that every changed file, touched
declaration, and non-trivial changed code/comment region is either covered by a candidate or
is obviously clear, necessary, and correct. If there are gaps, rerun or extend the relevant
generation pass before filtering.
-
Run slang-review-consolidate-candidates to merge raw outputs into the canonical workflow
file and resolve duplicates, overlaps, and superseded comments.
-
Run slang-review-scope-filter on the canonical workflow file in place.
-
Run slang-review-resolve-judgment-calls on candidates that need a judgment call.
-
Create or update the canonical file's ## Review Body. Write it like a competent human
reviewer: summarize the state of the PR relative to its size and value, call out whether it
feels rough or close to merge-ready, and name the key areas the author should focus on.
Write the section content as a strict Markdown blockquote: after leading/trailing blank
lines, every line before the next top-level section or candidate entry must start with >,
blank lines must be written as >, and headings inside the review body must be quoted,
e.g. > ## Main Concerns. Do not use lazy continuation lines.
Unless the workflow is posting through a GitHub account that already identifies the agent,
the first line must identify the review as agent-authored. Use the form
<agent name>-authored <optional review type> review:, such as
GPT-4.1-authored clarity review: or Claude 3.7 Sonnet authored review:. The separator
before authored may be whitespace instead of -. The agent name may be any non-newline
text up to 50 Unicode scalar values.
-
Validate the canonical file before posting.
The posting script enforces the mechanical blocking checks:
- no duplicate candidate IDs;
- no postable candidate remains
Status: Proposed or another unfiltered status;
- every postable candidate has
Scope decision, Scope rationale, Overlap decision,
and Overlap rationale;
- every postable candidate has a
Location that names a line/range present in the GitHub
diff;
- every postable candidate has a non-empty strict-blockquote
Proposed comment:;
- the
## Review Body section, if present, uses strict blockquote formatting for every
content line;
- unless
--acting-as-bot-user will be used, the review body starts with the required
agent-authorship attribution.
The agent must also check the judgment-based posting policy:
- dropped, duplicate, superseded, and merged candidates are preserved later in the file for
auditability;
- candidates about code outside the diff are attached to the closest or most logical
commentable diff line, and their proposed comment clearly names the actual code or
contract they concern;
- proposed comments do not include candidate IDs, status, confidence, scope, notes, or
other process metadata.
-
If the user asked to post, run slang-review-post-github on the canonical workflow file.
If a harness cannot invoke repository-local skills by name, read and apply the corresponding
SKILL.md files under .claude/skills/ in the sequence above.
Raw generation may write separate files so the two review passes can run independently without
append races. Sequential workflows may instead pass the canonical file as an append target to
the review skills, but consolidation still needs to run before scope filtering.
Posting Defaults
Default posted review result is 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.
Never use APPROVE for this workflow.
Include Needs judgment call candidates by default. The workflow is expected to run mostly
without a human in the loop, so uncertain-but-credible comments should not disappear just
because they required extra focused analysis.
Never post individual PR thread comments for this workflow. Posting must create one proper
GitHub PR review with comments attached to diff lines/ranges.
Do not omit the agent-authorship label unless the workflow is running under GitHub credentials
that already identify a bot or agent account. In that case, pass --acting-as-bot-user to the
posting script.
Evaluation Scenarios
Use these scenarios when checking whether the workflow still behaves correctly:
- Generation-only: given a PR number, produce high-level and fine-grained raw candidate files
without posting.
- Generation coverage audit: given raw candidates that leave a changed non-trivial function or
file with no candidate and no explicit obvious-clarity rationale, the workflow must revisit
generation before consolidation.
- Duplicate consolidation: given overlapping high-level and fine-grained candidates, keep the
clearer comment and mark the duplicate or superseded candidate as dropped.
- Judgment-call resolution: given a candidate marked
Needs judgment call, follow the local
code context deeply enough to keep, revise, or drop it when possible.
- Scope filtering: given a pre-existing clarity issue not made worse by the PR, move it to the
dropped section with a short rationale.
- Posting validation: given a postable-looking candidate missing scope or overlap metadata,
the posting script must fail before making a GitHub API call.