vale-ai-tells: Skill for Claude Code

Review a drafted pull request description

Review a drafted pull request description against the branch it would publish, then return a verdict. You're the independent check. You didn't write this description and you didn't watch the work happen, so read what it claims rather than what its author meant to claim.

The repository

$ARGUMENTS

Treat that path as the repository under review. An empty value means the current working directory. Bind it once and use it throughout:

REPO="${ARGUMENTS:-$(pwd)}"

Gather the inputs

Run these before judging anything:

• cat "$REPO/PR_AGENTDESC.md" for the draft
• sed -n '/^base:/p' "$REPO/PR_AGENTDESC.md" for the base branch the rest of these need
• git -C "$REPO" log --reverse --pretty=format:'--- %h%n%B' <base>..HEAD for the commits that would land
• git -C "$REPO" diff --name-status <base>...HEAD for the paths
• git -C "$REPO" diff <base>...HEAD for the diff itself
• cat "$REPO/.github/pull_request_template.md" for what each section is asking

A missing or empty draft, or a branch with nothing to land, is itself a finding. Report it and stop.

What's already settled

The writer runs a mechanical validator until it reports nothing before handing you anything, and the caller runs it again afterwards, so leave its rules alone. It has already settled:

• the frontmatter shape, and the title's length and Conventional Commits form
• section presence, section order, and sections left empty
• surviving template comments, unclosed fences, and links pointing nowhere
• whether every path the draft puts in backticks exists

Repeating any of that wastes the round trip.

Read the diff instead. Your job starts where looking at the file stops.

What to check

Work these four groups. Every finding names the exact offending text and the fix.

Truthfulness

The description covers this branch and no other.

• Flag any claim the diff doesn't support. A description naming a behavior, a flag, or a guarantee absent from the diff is wrong, whatever else it gets right.
• Flag counts of any kind: files, lines, tests, commits, percentages. A count goes stale the moment other work merges, and it pads a description rather than informing it.
• Flag results nobody verified. The Verification section names commands, so check that the commands suit the change. A Go change verified only by a Markdown linter reports nothing about itself.
• Flag a Risk section that says nothing risks anything when the diff touches behavior, and flag invented risk when the diff touches documentation alone.