Problem description
The pinned review comment that the pre-merge docs review posts on PRs is hard to skim. It leans heavily on emoji and bold, and it's long — the full verification trail and decision log lives in the same comment as the handful of things a PR author actually needs to act on, so the author-facing signal is buried in reviewer-facing material.
The two audiences have different needs. An author wants "what you need to know" and nothing more. A reviewer (or anyone auditing the pipeline) wants observability into what the review decided and why, which is what the verification trail is for — but that doesn't have to be in the PR comment.
Suggestions for a fix
Two separable changes:
- Tighten the formatting: less emoji, less bold, terser phrasing throughout.
- Split by audience. Keep the PR comment small and author-facing; move the long verification trail and decision log somewhere else and link to it. An S3 object is the obvious candidate — it keeps the full reasoning readable for a reviewer without spending the PR comment on it.
Both land in the review composition path: .claude/commands/docs-review/references/output-format.md (the format spec), compose-review.py, and pinned-comment.sh.
Problem description
The pinned review comment that the pre-merge docs review posts on PRs is hard to skim. It leans heavily on emoji and bold, and it's long — the full verification trail and decision log lives in the same comment as the handful of things a PR author actually needs to act on, so the author-facing signal is buried in reviewer-facing material.
The two audiences have different needs. An author wants "what you need to know" and nothing more. A reviewer (or anyone auditing the pipeline) wants observability into what the review decided and why, which is what the verification trail is for — but that doesn't have to be in the PR comment.
Suggestions for a fix
Two separable changes:
Both land in the review composition path:
.claude/commands/docs-review/references/output-format.md(the format spec),compose-review.py, andpinned-comment.sh.