/pr-polish

Holistic quality elevation for a PR that already works.

Role

Staff engineer doing a retrospective pass. Not finding bugs — asking "would we build it the same way starting over?"

Objective

Elevate PR $ARGUMENTS (or current branch's PR) from "works" to "exemplary": clean architecture, solid tests, current docs.

Precondition Gate

Before starting, verify:

gh pr view $PR --json mergeable,statusCheckRollup,reviewDecision

Requirements:

• No merge conflicts
• CI green
• No unaddressed critical review feedback

If any fail: Tell user to run /pr-fix first. Do not proceed.

Workflow

1. Context

Read everything about this PR:

gh pr view $PR --json body,commits,files
gh pr diff $PR

Read linked issue(s). Read commit history. Understand the full arc of what was built and why.

2. Hindsight Review

Launch hindsight-reviewer agent via Task tool.

Key question: "Knowing what we know now — the final shape of the code, the edge cases discovered, the patterns that emerged — would you build it the same way?"

Feed it: full diff against main, PR description, linked issue.

Expect back: architectural observations, naming concerns, abstraction boundaries, missed simplifications.

3. Refactor

Invoke /refactor for findings that are addressable now:

• Naming improvements
• Shallow module consolidation
• Unnecessary abstraction removal
• Code path simplification

For architectural findings that require broader changes: create GitHub issues.

gh issue create --title "[Arch] Finding from PR #$PR hindsight review" --body "..."

3.5. Simplify

Invoke /simplify on the PR's changed files.

The code-simplifier agent reviews recently modified code for clarity, consistency, and maintainability — complementing the architectural lens of hindsight review with line-level refinement:

• Reduce unnecessary complexity and nesting
• Eliminate redundant abstractions
• Improve naming clarity
• Consolidate related logic
• Remove obvious comments

This catches things the refactor step doesn't: verbose patterns, inconsistent style, overly compact one-liners, nested ternaries.

4. Test Audit

Review test coverage for the PR's changed files. Look for:

• Missing edge cases
• Error path coverage
• Behavior tests (not implementation tests — per /testing-philosophy)
• Boundary conditions
• Integration gaps

Write missing tests. Each test should justify its existence — no coverage-padding.

5. Documentation

Invoke /update-docs for anything the PR affects:

• ADRs for architectural decisions made during implementation
• README updates for new features or changed behavior
• Architecture diagrams if module boundaries changed
• API docs if endpoints changed

6. Quality Gates

Invoke /check-quality and run project verification:

pnpm typecheck && pnpm lint && pnpm test

All gates must pass. Fix anything that doesn't.

7. Update PR Description with Before / After

Edit the PR body to include (or update) a Before / After section documenting the polish pass:

gh pr edit $PR --body "$(current body + before/after section)"

Text (MANDATORY): Describe the state before polish (e.g., "working but with shallow modules and missing edge-case tests") and after (e.g., "consolidated modules, 12 new edge-case tests, updated architecture docs").

Screenshots (when applicable): Capture before/after for any visible change — refactored UI output, improved error messages, updated docs pages. Use ![before](url) / ![after](url).

Skip screenshots only when all polish was purely internal (refactoring with no visible output change).

7.5 Diagram Audit

Check PR body for visual communication:

gh pr view $PR --json body | jq -r '.body'

• Does the PR body have a ## What Changed Mermaid diagram?
• If no, and the change involves logic/architecture/data flow: generate one using ~/.claude/skills/visualize/references/github-mermaid-patterns.md
• If yes: validate it accurately reflects the final state (diagrams drift during review)
• Add or update diagram in PR body: gh pr edit $PR --body "$(updated body)"

Omit only when the change is purely internal with no branching or relationships.

8. Refresh Glance Summaries (Conditional)

If this PR added, removed, or significantly restructured directories:

glance   # run from repo root — skips up-to-date directories automatically

Do NOT pass -force. Glance handles intelligent regeneration based on existing .glance.md files. Only affects directories that changed.

Commit any updated .glance.md files with the PR branch.

9. Codify (Optional)

If patterns or learnings emerged during this polish pass, invoke /distill to capture them as permanent knowledge (hooks, agents, skills, CLAUDE.md entries).

Skip if nothing novel surfaced.

Agent Teams Mode

For large PRs (>500 line diff), parallelize phases 3-5:

Teammate	Task
Refactorer	/refactor on hindsight findings
Simplifier	/simplify on changed files
Test writer	Test audit + write missing tests
Doc updater	/update-docs

Lead sequences: hindsight first (all teammates need its output), then parallel work, then quality gates.

Anti-Patterns

• Polishing a PR that doesn't work yet (use /pr-fix first)
• Architectural refactors in a polish pass (create issues instead)
• Adding tests for coverage percentage instead of confidence
• Documenting obvious mechanics instead of non-obvious decisions
• Skipping hindsight and jumping straight to refactoring

Output

Summary: hindsight findings, refactors applied, issues created, tests added, docs updated, quality gate results, learnings codified.