Help us improve
Share bugs, ideas, or general feedback.
From pre-push-review
Use before pushing a branch or creating a PR. Triggers on phrases like "ready to push", "review my changes", "pre-flight check", "is this ready to merge", "about to push", "review the branch", or after the user wraps up a feature branch and signals completion. Diffs against the base branch and reviews plan adherence, code quality, commit hygiene, and regression testing, producing a PASS/FAIL verdict with a prioritized remediation plan on FAIL. Skip for in-progress work or single-commit fixes the user explicitly wants pushed without review.
npx claudepluginhub marcelroozekrans/superpowers-extensions --plugin pre-push-reviewHow this skill is triggered — by the user, by Claude, or both
Slash command
/pre-push-review:pre-push-reviewThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<HARD-GATE>
Provides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
Share bugs, ideas, or general feedback.
Write tool to create the report file at the end of
Phase 6. Do not narrate the report content as a substitute. Saying
"the verdict is FAIL with the following findings" in conversation
without a tool call leaves no record for the user, no record for
audit-milestone, and no record for any later session.If the report file is missing at the verify step, Phase 6 did not complete — return to it and retry the tool call. Do not proceed.
This skill requires a git repository with at least one commit on a feature branch that differs from the base branch. No additional MCP servers are required for the core review.
Optional: If the project has a web UI and you want browser-based regression testing as part of the review, install the Microsoft Playwright MCP server (@playwright/mcp):
claude mcp add playwright -- npx @playwright/mcp@latest --caps=testing
This skill defines a structured, comprehensive branch review process to run before pushing code or creating a pull request. The core principle is:
"Never push without reviewing every change against the plan, the rules, and the tests."
The review covers four dimensions: verifying that planned work was completed (and nothing unplanned snuck in), checking code quality against established rules, ensuring commits are clean and free of secrets or artifacts, and confirming that tests still pass. The result is a clear PASS or FAIL verdict. On failure, a prioritized remediation plan is generated with specific steps to fix each issue.
This skill can be invoked standalone (/pre-push-review) or as part of a larger workflow (e.g., before finishing a development branch or before creating a PR).
When this skill is activated, begin with:
"Starting pre-push review. I'll review the branch diff across four dimensions: plan adherence, code quality, commit hygiene, and regression testing. I'll auto-detect the base branch and produce a PASS/FAIL verdict."
Invoke this skill in any of the following situations:
Use this checklist to track progress through the six phases:
The following Graphviz diagram illustrates the full pre-push review workflow:
digraph pre_push_review {
rankdir=TB;
node [shape=box, style=rounded, fontname="Helvetica"];
edge [fontname="Helvetica", fontsize=10];
setup [label="Phase 1:\nSetup & Context"];
detect_base [label="Auto-detect\nbase branch", shape=diamond];
ask_base [label="Ask user for\nbase branch"];
gather_diff [label="Gather diff,\nlog, changed files"];
find_plan [label="Find plan docs\n& project rules"];
has_plan [label="Plan doc\nexists?", shape=diamond];
plan_review [label="Phase 2:\nPlan Adherence"];
skip_plan [label="Skip plan review\n(note in report)"];
code_quality [label="Phase 3:\nCode Quality"];
commit_hygiene [label="Phase 4:\nCommit Hygiene"];
has_tests [label="Test suites\nfound?", shape=diamond];
run_tests [label="Phase 5:\nRun Tests"];
skip_tests [label="Skip tests\n(note in report)"];
has_ui [label="Web UI with\nURL available?", shape=diamond];
regression [label="Invoke\nregression-test skill"];
collect [label="Collect all\nfindings"];
verdict [label="Phase 6:\nVerdict"];
pass [label="PASS\nGreen light"];
fail [label="FAIL\nGenerate\nremediation plan"];
report [label="Generate\nreport"];
summary [label="Conversation\nsummary"];
setup -> detect_base;
detect_base -> gather_diff [label="Found"];
detect_base -> ask_base [label="Ambiguous"];
ask_base -> gather_diff;
gather_diff -> find_plan;
find_plan -> has_plan;
has_plan -> plan_review [label="Yes"];
has_plan -> skip_plan [label="No"];
plan_review -> code_quality;
skip_plan -> code_quality;
code_quality -> commit_hygiene;
commit_hygiene -> has_tests;
has_tests -> run_tests [label="Yes"];
has_tests -> skip_tests [label="No"];
run_tests -> has_ui;
skip_tests -> has_ui;
has_ui -> regression [label="Yes"];
has_ui -> collect [label="No"];
regression -> collect;
collect -> verdict;
verdict -> pass [label="No blockers\n< 3 warnings"];
verdict -> fail [label="Any blocker\nor 3+ warnings"];
pass -> report;
fail -> report;
report -> summary;
}
This phase establishes the review scope by identifying the base branch, gathering the diff, and locating relevant project documentation.
Determine the base branch using this priority order:
git rev-parse --abbrev-ref @{upstream} 2>/dev/null to check if the current branch tracks a remote branch. If so, extract the base branch name.main, master, or develop branches exist using git show-ref --verify refs/heads/<name>.Once the base branch is identified, run these commands:
git diff <base>...HEAD --stat — Changed files summary (file names and change counts)git diff <base>...HEAD — Full diff content for reviewgit diff <base>...HEAD --name-only — Plain list of changed file pathsgit log <base>..HEAD --oneline — Commit history on this branchgit log <base>..HEAD --format="%H %s" — Commit hashes and messages for hygiene checksSearch for relevant plan or design documents:
docs/plans/*.md — Read each to see if it relates to the current branch or featurefeat/user-auth, look for plans mentioning "user auth" or "authentication"CLAUDE.md in the project root — project-level rules and conventions.cursorrules, .windsurfrules, or similar convention filesRecord which plan document (if any) will be used for the plan adherence review.
If a plan document was found in Phase 1, compare the actual changes against what was planned. If no plan was found, skip this phase and note it in the report.
Read the plan document — Extract all planned tasks, features, and changes.
Map plan items to diff — For each planned item, check whether the diff contains corresponding changes:
Identify missing items — List any planned items that have no corresponding changes in the diff. These are gaps that need to be addressed before pushing.
Identify unplanned changes — List any significant changes in the diff that are not mentioned in the plan. Minor changes (formatting, import reordering) are acceptable; new features or behavioral changes are not.
Record findings with severity:
Review the full diff for code quality issues. Apply the rules defined in code-quality-rules.md.
Get the full diff — Use the diff gathered in Phase 1.
Categorize changed files — Separate files into: source code, test files, configuration, documentation, and other. Focus the quality review on source code files.
Apply each rule from the code quality rules document:
Focus on added and modified lines — Only review lines that were changed (lines starting with + in the diff, excluding +++ file headers). Do not flag issues in unchanged code.
Record each finding with: rule number, file path, line reference, description, and severity.
Review the commits and changed files for hygiene issues. Apply the rules defined in commit-hygiene-rules.md.
Check commit messages — Review each commit message from git log <base>..HEAD against the commit message quality rules.
Scan for secrets — Search the full diff for secret patterns defined in the commit hygiene rules. Pay special attention to:
.env filesCheck for unintended files — Review the changed files list for files that should not be in version control (node_modules, build artifacts, OS files, large binaries).
Check for merge conflict markers — Search the diff for <<<<<<<, =======, >>>>>>> patterns.
Check file sizes — For new files in the diff, check their sizes against the thresholds.
Record each finding with: rule number, file path, description, and severity.
Run existing test suites to verify the branch hasn't broken anything.
Detect test frameworks — Use the same detection logic as the regression-test skill: check for config files (jest.config.*, vitest.config.*, playwright.config.*, cypress.config.*, etc.) and package.json scripts.
Run test suites — Execute each detected test suite:
npm test, npm run test:e2e, etc.)npx jest, npx vitest run, etc.)Capture results — Record:
Optional: UI contract audit — If docs/plans/*-ui-contract.md exists for the current branch/phase AND the ui-workflow skill is available, invoke its ui-review sub-skill to audit the implementation against the contract. This supersedes bare regression-test for frontend branches with a contract. If the contract exists but ui-workflow is not installed, record a Warning ("ui-contract present but ui-workflow skill unavailable — install superpowers-extensions ui-workflow plugin to enable contract audit") and fall through to step 5. Do not silently skip the audit.
Optional: Browser-based regression testing — If the project has a web UI, no ui-contract exists, and the user confirms a URL is available, offer to invoke the regression-test skill for visual and functional browser testing. This is optional and requires user confirmation.
Record findings:
.skip or @Ignore (may indicate incomplete work)Collect all findings from Phases 2-5, determine the verdict, and generate the report.
| Condition | Verdict |
|---|---|
| Any Blocker finding in any phase | FAIL |
| Three or more Warning findings across all phases | FAIL |
| Fewer than 3 warnings and no blockers | PASS |
Save the report to:
docs/pre-push-review-YYYY-MM-DD-HHmm.md
| Metric | Value |
|---|---|
| Date | YYYY-MM-DD HH:mm |
| Branch | (current branch name) |
| Base Branch | (base branch name) |
| Commits Reviewed | (count) |
| Files Changed | (count) |
| Lines Added | (count) |
| Lines Removed | (count) |
| Verdict | PASS or FAIL |
When the verdict is FAIL, include a remediation plan:
After generating the report, provide a concise summary in the conversation:
These are mistakes that compromise the quality of a pre-push review. If you notice yourself doing any of these, stop and correct course:
Skipping the diff — Every review must be based on the actual git diff. Do not make assumptions about what changed based on file names alone.
Ignoring the plan — If a plan document exists, it must be compared against the diff. Do not skip plan adherence because "the code looks fine."
Glossing over security issues — Every pattern match for secrets or security vulnerabilities must be investigated. Do not dismiss regex matches as false positives without examining the actual content.
Not running tests — If test suites exist, they must be run. Do not skip tests because "they probably pass" or "we only changed CSS."
Soft-passing a failing review — If blockers are found or warnings exceed the threshold, the verdict is FAIL. Do not rationalize a PASS verdict to avoid delivering bad news.
Generating a report without reviewing — The report must reflect actual review findings. Never generate a placeholder or optimistic report without completing all phases.
These are excuses that sound reasonable but lead to incomplete reviews. The correct response to each is provided.
| Rationalization | Why It's Wrong | Correct Action |
|---|---|---|
| "It's just a small change, no need for a full review" | Small changes can contain secrets, break tests, or violate the plan | Run the full review process |
| "The tests passed in CI" | This review checks more than tests: plan adherence, code quality, commit hygiene | Complete all phases regardless of CI status |
| "I know this code is fine, I just wrote it" | Self-review bias is real; systematic checks catch what memory misses | Follow the process mechanically |
| "The plan is outdated, so skip plan adherence" | If the plan is outdated, that's a finding worth noting | Review against the plan; note discrepancies |
| "Those regex matches are just false positives" | Every match must be verified; real secrets look like false positives | Examine each match; only dismiss with evidence |
| "There are too many warnings, let's just note them" | Three or more warnings is a FAIL verdict; they indicate systematic issues | Apply the verdict rules strictly |
| "We can fix the commit messages later" | Commit messages are part of the permanent record; "later" rarely happens | Flag them now |
Use this table for a fast reminder of what each phase involves and which tools are needed.
| Phase | Key Actions | Tools Used |
|---|---|---|
| Phase 1: Setup & Context | Detect base branch, gather diff, find plans | git commands, Glob, Read |
| Phase 2: Plan Adherence | Compare diff against plan document | Read, Grep |
| Phase 3: Code Quality | Review diff for 7 quality rules | Grep, diff analysis |
| Phase 4: Commit Hygiene | Check commits, secrets, files, markers | git commands, Grep |
| Phase 5: Regression Testing | Run test suites, optionally browser testing | Bash (test runners), optionally Playwright MCP |
| Phase 6: Verdict & Report | Generate report, determine PASS/FAIL | Write (markdown report) |
This skill is designed to complement — not replace — the superpowers workflow skills. Here is how they fit together:
| Superpowers Skill | Relationship | Notes |
|---|---|---|
finishing-a-development-branch | Run pre-push-review first. This skill gates whether the branch is ready; finishing-a-development-branch decides how to integrate it (merge, PR, cleanup). | Pre-push-review produces the evidence that finishing-a-development-branch needs. |
verification-before-completion | This skill satisfies it. Verification-before-completion requires evidence before success claims. A PASS verdict from this skill is that evidence. | No need to run both — a completed pre-push-review covers verification. |
requesting-code-review | This skill supersedes it. Pre-push-review includes code quality review (Phase 3) plus plan adherence, commit hygiene, and regression testing. | If pre-push-review has been run, skip requesting-code-review to avoid redundant work. |
Recommended workflow chain:
Implementation complete
→ pre-push-review (this skill: structured quality gate)
→ finishing-a-development-branch (superpowers: merge/PR decision)
The following companion documents provide detailed criteria referenced throughout this skill: