--- name: pr-readiness-review description: "Performs a comprehensive pre-PR readiness review covering tests, code quality, security, and commit conventions. Use at the end of implementation before submitting a pull request." --- # PR Readiness Review Workflow Use this at the end of implementation to prepare for PR submission. Example request: > I've completed the implementation. Please perform a comprehensive PR readiness > review. ## Contents - [Contents](#contents) - [How to use this skill](#how-to-use-this-skill) - [Prerequisites](#prerequisites) - [Related skills](#related-skills) - [1. Run Final Validation](#1-run-final-validation) - [2. Verify Testing Quality](#2-verify-testing-quality) - [3. Review Code Quality](#3-review-code-quality) - [4. Verify Against Git Documentation](#4-verify-against-git-documentation) - [5. Check Commit Quality](#5-check-commit-quality) - [6. Review Documentation](#6-review-documentation) - [7. Verify Branch Placement](#7-verify-branch-placement) - [8. Generate PR Summary](#8-generate-pr-summary) ## How to use this skill Attach this file to your Copilot Chat context, then invoke it after implementation is complete and before opening a pull request. This workflow is a final quality gate and reporting template. ## Prerequisites Before starting, you **MUST** load the following skill(s) in their entirety: - [YARD Documentation](../yard-documentation/SKILL.md) — authoritative source for YARD formatting rules and writing standards; ## Related skills - [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md) — baseline rules that all unit tests must comply with, including testing only via public interfaces; these standards take precedence over any older guidance - [Development Workflow](../development-workflow/SKILL.md) — primary implementation process prior to readiness checks - [Command Test Conventions](../command-test-conventions/SKILL.md) — unit/integration test conventions for command classes - [Command YARD Documentation](../command-yard-documentation/SKILL.md) — verify command documentation completeness and consistency - [Facade Test Conventions](../facade-test-conventions/SKILL.md) — unit/integration test conventions for `Git::Repository::*` facade methods - [Facade YARD Documentation](../facade-yard-documentation/SKILL.md) — verify facade module/method documentation completeness and consistency - [Reviewing Skills](../reviewing-skills/SKILL.md) — audit skill quality, discoverability, reference structure, and cross-skill links when skill files change ## 1. Run Final Validation Execute and report results for: - `bundle exec rake default` - all tests and linters must pass - Check test output for any Ruby warnings ## 2. Verify Testing Quality **Unit Tests (Critical):** - [ ] **100% coverage of all changed code** - every branch, edge case, error condition - [ ] All external dependencies properly mocked (execution_context, git commands) - [ ] Each test verifies one specific behavior - [ ] Comprehensive coverage: success paths, failures, edge cases, error handling - [ ] Test only through public interfaces (see RSpec Unit Testing Standards Rule 6) **Integration Tests (Essential Only):** - [ ] **Minimal and purposeful** - only test what unit tests cannot verify - [ ] Each test validates one specific git interaction pattern - [ ] Tests verify mocked assumptions match real git behavior - [ ] No redundancy - don't duplicate what unit tests already cover - [ ] Follow CONTRIBUTING.md guidelines: test gem's interaction with git, not git itself **Command Tests (if any `Git::Commands::*` specs are included):** - [ ] Apply the [Command Test Conventions](../command-test-conventions/SKILL.md) skill to every new or modified unit and integration spec file for command classes. Resolve all findings before proceeding. ## 3. Review Code Quality - [ ] YARD documentation complete for all public methods/classes - [ ] Include `@api public` or `@api private` tags appropriately - [ ] Usage examples in YARD docs show common patterns - [ ] **Command YARD Docs (if any `Git::Commands::*` source files are included):** Apply the [Command YARD Documentation](../command-yard-documentation/SKILL.md) skill to every new or modified command source file. Resolve all findings before proceeding. - [ ] No breaking changes (or properly marked with `!` in commits) - [ ] Cross-platform compatible on all supported OSes; any platform-specific logic is properly guarded and tested - [ ] No security issues (command injection, path traversal, etc.) - [ ] Uses Arguments DSL for building git commands ## 4. Verify Against Git Documentation - [ ] Determine the repository's minimum supported Git version from project metadata - [ ] Read version-matched upstream documentation for the implemented command - [ ] Inspect version-matched upstream source when docs are ambiguous about exact option forms - [ ] Use local `git -h` output only as a supplemental check for the installed Git - [ ] Confirm all documented options are considered - [ ] All edge cases from git documentation are tested - [ ] Error handling matches git's actual behavior - [ ] Exit codes handled correctly (especially partial failures) ## 5. Check Commit Quality - [ ] All commits follow Conventional Commits format: `type: description` - [ ] Description is lowercase, no ending period, under 100 chars - [ ] Valid types: feat, fix, docs, test, refactor, chore, perf, build, ci, style, revert - [ ] Breaking changes marked with `!` and include `BREAKING CHANGE:` footer - [ ] Each commit is atomic and has a clear purpose ## 6. Review Documentation - [ ] If a new pattern was introduced, the skill that documents that pattern is updated in the same PR (`.github/skills/`) - [ ] README.md updated if public API changed - [ ] Examples are clear and demonstrate common use cases - [ ] All `@param`, `@return`, `@raise` tags are accurate - [ ] **Skill docs (if any `.github/skills/**` files are included):** Apply the [Reviewing Skills](../reviewing-skills/SKILL.md) skill to every new or modified skill. Verify TOC anchors, relative links, cross-skill deep links, referenced files, and any stated inheritance/override relationships. ## 7. Verify Branch Placement Before creating the PR, confirm the branch situation: - [ ] Changes are on a feature branch (not `main`, `5.x`, or `4.x`), named `/` - [ ] Branch targets the correct base: `main` for features/breaking changes; `5.x` or `4.x` for backports of fixes already on `main` that pass the rescue-compatibility test in [Branch & PR Strategy](../../copilot-instructions.md#branch--pr-strategy), and for security fixes and backward-compatible changes that apply only to that series **If changes are on the wrong branch:** Create a new branch from the appropriate base (`origin/main`, `origin/5.x`, or `origin/4.x`) and relocate the existing work using the most appropriate Git approach — cherry-pick (specific commits), rebase (linear history), or recommit (uncommitted changes) — based on the situation. ## 8. Generate PR Summary Provide a comprehensive report with: **Implementation Summary:** - What was implemented and why - Key design decisions made - Any trade-offs or limitations **Test Coverage:** - Unit tests: X examples covering Y scenarios - Integration tests: Z examples validating specific git interactions - Coverage: 100% of changed lines (or explain gaps) - Edge cases tested: [list critical ones] **Quality Verification:** - ✅ Items that passed all checks - ⚠️ Items that need attention (if any) - Reference to relevant documentation verified **Suggested PR Materials:** - PR Title: `type: clear description of change` - PR Description draft including: - Summary of changes - Why this change is needed - Test coverage details - Breaking changes (if any) - Checklist from .github/pull_request_template.md **PR Body Editing Safety:** - The terminal tool mangles multi-line markdown (backticks, asterisks, newlines) in any shell command, including heredocs. Always write the PR body using the **`create_file` tool** (the VS Code Copilot agent tool that writes file content directly, bypassing the terminal entirely), then reference the file: - `gh pr create --body-file ` when opening - `gh pr edit --body-file ` when updating - **Never** use inline `--body "..."` or `cat > file << 'EOF'` heredocs for PR bodies - After any body update, verify the stored text with: - `gh pr view --json body --jq '.body'` - If the body is garbled, rewrite the file with `create_file` and re-run `gh pr edit` **Next Steps:** - Any remaining items to address before PR submission - Confirmation that all checklist items are complete - Make sure to create a feature branch for the PR -- never push directly to main