Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Review pull/merge requests with discipline: validate against original requirements, prevent scope creep, and route out-of-scope findings to issues on the detected platform.
Platform detection is automatic via leyline:git-platform. Use gh for GitHub, glab for GitLab. Check session context for git_platform:.
Core Principle
A PR review validates scope compliance, not code perfection.
The goal is to validate the implementation meets its stated requirements without introducing regressions. Improvements beyond the scope belong in future PRs.
When To Use
Before merging any feature branch
When reviewing PRs from teammates
To validate your own work before requesting review
To generate a backlog of improvements discovered during review
When NOT To Use
Preparing PRs - use pr-prep instead
Deep code
review - use pensive:unified-review
Preparing PRs - use pr-prep instead
Deep code
review - use pensive:unified-review
Scope Classification Framework
Every finding must be classified:
Category
Definition
Action
BLOCKING
Bug, security issue, or regression introduced by this change
Must fix before merge
IN-SCOPE
Issue directly related to stated requirements
Should address in this PR
SUGGESTION
Improvement within changed code, not required
Author decides
BACKLOG
Good idea but outside PR scope
Create GitHub issue
IGNORE
Nitpick, style preference, or not worth tracking
Skip entirely
Classification Examples
BLOCKING:
Null pointer exception in new code path
SQL injection in new endpoint
Breaking change to public API without migration
Test that was passing now fails
IN-SCOPE:
Missing error handling specified in requirements
Feature doesn't match spec behavior
Incomplete implementation of planned functionality
SUGGESTION:
Better variable name in changed function
Slightly more efficient algorithm
Additional edge case test
BACKLOG:
Refactoring opportunity in adjacent code
"While we're here" improvements
Technical debt in files touched but not changed
Features sparked by seeing the code
IGNORE:
Personal style preferences
Theoretical improvements with no practical impact
Premature optimization suggestions
Workflow
Phase 1: Establish Scope Baseline
Before looking at ANY code, understand what this PR is supposed to accomplish.
Note: Version validation (Phase 1.5) runs AFTER scope establishment but BEFORE code review. See modules/version-validation.md for details.
Search for scope artifacts in order:
Plan file: Most authoritative (check spec-kit locations first, then root)
# Spec-kit feature plans (preferred - structured implementation blueprints)
find specs -name "plan.md" -type f 2>/dev/null | head -1 | xargs cat 2>/dev/null | head -100
# Legacy/alternative locationsls docs/plans/ 2>/dev/null
# Root plan.md (may be Claude Plan Mode artifact from v2.0.51+)cat plan.md 2>/dev/null | head -100
Verification: Run the command with --help flag to verify availability.
See modules/version-validation.md for detailed validation procedures.
Quick reference:
Check if bypass requested (--skip-version-check, label, or PR marker)
Detect if version files changed in PR diff
If changed, run project-specific validations:
Claude marketplace: Check marketplace.json vs plugin.json versions
Python: Check pyproject.toml vs version
Node: Check package.json vs package-lock.json
Rust: Check Cargo.toml vs Cargo.lock
Validate CHANGELOG has entry for new version
Check README/docs for version references
Classify findings as BLOCKING (or WAIVED if bypassed)
All version mismatches are BLOCKING unless explicitly waived by maintainer.
Phase 3.5: PR Hygiene Checks
Before diving into code, run the PR hygiene checks from
modules/pr-hygiene.md:
Atomicity check: Does this PR contain one logical
change? Flag mixed commit types (feat, refactor, and fix),
formatting commits bundled with logic, or changes spanning
unrelated subsystems. Large PRs get 30% defect detection
vs 75% for focused ones.
Agent curation check: Does the code show signs of
iterative AI generation without a cleanup pass? Look for
redundant implementations, premature abstractions, incomplete
refactors, and scope drift.
Self-review signals: Are there unsquashed fixup commits,
debug statements, or commented-out code that suggest the
author did not read their own diff before sending?
Classify findings per modules/pr-hygiene.md severity tables.
Phase 4: Code Review with Scope Context
Use pensive:unified-review on the changed files. For comment quality assessment, see modules/comment-guidelines.md.
Critical: Evaluate each finding against the scope baseline:
**Verification:** Run the command with `--help` flag to verify availability.
Finding: "Function X lacks input validation"
Scope check: Is input validation mentioned in requirements?
- YES → IN-SCOPE
- NO, but it's a security issue → BLOCKING
- NO, and it's a nice-to-have → BACKLOG
Verification: Run the command with --help flag to verify availability.
Phase 4.5: Additive Bias Audit
Run Skill(imbue:justify) on the PR changes to detect
AI additive bias, test-logic tampering, and unnecessary
complexity.
Key checks:
Additive bias score: flag changes with high
add/delete ratio (>5:1) that lack justification
Iron Law compliance: verify test assertions were
not weakened to match broken implementations
Minimal intervention: confirm each changed file
was necessary and the change was the smallest fix
Classify justify findings using the scope framework:
Justify Signal
Likely Classification
Test logic tampered
BLOCKING
High additive bias, no justification
IN-SCOPE
Premature abstraction
SUGGESTION
Compatibility shim
BACKLOG
Include the additive bias score and Iron Law status in
the Phase 6 report.
Phase 4.6: Invariant Conflict Detection
Check whether the PR touches existing design invariants.
This is a judgment problem that models get wrong far too
often: surface conflicts for human review rather than
silently accepting or rejecting them.
Quick detection heuristic:
Do changed files cross module boundaries that
previously didn't interact?
Do changes introduce a new pattern alongside an
existing one (two ways to do the same thing)?
Do NOT resolve it. Add to the report as a special
category:
Category
Definition
Action
INVARIANT
Change conflicts with an existing design decision
Escalate to human with 3-option analysis
For each invariant conflict, present:
The invariant: Name the design decision and why
it was made (reference ADRs if available)
The conflict: What this PR does that clashes
Option A, Preserve: Don't merge this change;
the invariant pays dividends elsewhere
Option B, Layer: Merge as-is, accepting
inelegance; not every feature must be elegant
Option C, Revise: The invariant is wrong;
here's what a redesign would look like
Classification: INVARIANT findings are always
BLOCKING, not because the code is wrong, but because
the judgment call requires human input. Only the human
reviewer can decide which of the three options is right.
Why this matters: Bad invariant decisions compound.
A few wrong calls and the codebase becomes unsalvageable.
This is not a context problem solvable with better
documentation: it is a judgment problem that requires
human wisdom.
Phase 5: Backlog Triage
For each BACKLOG item, create an issue on the detected platform:
Verification: Run the command with --help flag to verify availability.
Ask user before creating: "I found N backlog items. Create issues? [y/n/select]"
Phase 6: Generate Report
Structure the report by classification. Every BLOCKING and
IN-SCOPE finding MUST include educational insights per
modules/educational-insights.md: Why (the principle),
Proof (link to best practice), and a Teachable Moment
(generalized lesson). SUGGESTION findings include Why and
optionally Proof. BACKLOG items need only a brief rationale.
## PR #X: Title### Scope Compliance**Requirements:** (from plan/spec)
1. [x] Requirement A - Implemented
2. [x] Requirement B - Implemented
3. [ ] Requirement C - **Missing**### Blocking (1)1. [B1] SQL injection via string concatenation
-**Location**: `db/queries.py:89` -**Anchor**: `cursor.execute("SELECT * FROM t WHERE id = " + uid)` -**Issue**: User input interpolated directly into SQL
-**Why**: String-interpolated SQL allows attackers to
execute arbitrary queries (CWE-89). This is the #1
web application vulnerability per OWASP Top 10.
- **Proof**: [OWASP SQL Injection](https://owasp.org/www-community/attacks/SQL_Injection)
- **Teachable Moment**: Always use parameterized queries
or an ORM. This applies everywhere user input reaches
a database, cache, or search engine query.
- **Fix**: Use parameterized query:
`cursor.execute("SELECT * FROM t WHERE id = ?", (uid,))`
### In-Scope (1)1. [S1] Missing validation for edge case
-**Location**: `api.py:45` -**Anchor**: `def handle_request(payload):` -**Issue**: Empty input not handled per requirement
-**Why**: Defensive validation at API boundaries
prevents cascading failures in downstream logic.
- **Proof**: [Postel's Law](https://en.wikipedia.org/wiki/Robustness_principle)
- **Teachable Moment**: Validate inputs at system
boundaries (API handlers, CLI args, file parsers)
but trust internal function contracts.
### Suggestions (1)1. [G1] Consider extracting helper function
-**Why**: The repeated pattern on lines 30-35 and
72-77 violates DRY. Extracting it reduces future
bug surface.
- Author's discretion
### Backlog → GitHub Issues (3)1. #142 - Refactor authentication module
2. #143 - Add caching layer
3. #144 - Update deprecated dependency
### Recommendation**APPROVE WITH CHANGES**
Address B1 and S1 before merge.
Local Output (--local)
When --local [path] is passed, write the Phase 6 report to a
local .md file instead of posting via API. Default path:
.pr-review/pr-<number>-review.md. The file includes the
review summary, test plan, and backlog items in a single
document. Issue creation and PR description updates are skipped.
Knowledge capture (Phase 7) still runs.
Phase 7: Knowledge Capture
After generating the report, evaluate findings for knowledge capture into the project's review chamber.
Trigger: Automatically for findings scoring ≥60 on evaluation criteria.
# Capture significant findings to review-chamber# Uses memory-palace:review-chamber evaluation framework
Verification: Run the command with --help flag to verify availability.
Candidates for capture:
BLOCKING findings with architectural context → decisions/
Recurring patterns seen in multiple PRs → patterns/
Quality standards and conventions → standards/
Post-mortem insights and learnings → lessons/
Output: Add to report:
### Knowledge Captured 📚
| Entry ID | Title | Room |
|----------|-------|------|
| abc123 | JWT over sessions | decisions/ |
| def456 | Token refresh pattern | patterns/ |
View: `/review-room list --palace <project>`
Verification: Run the command with --help flag to verify availability.
See modules/knowledge-capture.md for full workflow.
Quality Gates
A PR should be approved when:
All stated requirements are implemented
No BLOCKING issues remain
IN-SCOPE issues are resolved or acknowledged
BACKLOG items are tracked as GitHub issues
Tests cover new code paths
Tests would fail if the fix were reverted (the revert test)
No obvious agent-generated code left uncurated
Author can explain how each changed section works and how
it could fail (understanding check, not just "tests pass")
Anti-Patterns to Avoid
Don't: Scope Creep Review
"While you're here, you should also refactor X, add feature Y, and fix Z in adjacent files."
Do: Create backlog issues, keep PR focused.
Don't: Perfect is Enemy of Good
"This works but could be 5% more efficient with different approach."
Do: If it meets requirements and has no bugs, it's ready.
Don't: Blocking on Style
"I prefer tabs over spaces."
Do: Use linters for style, reserve review for logic.
Don't: Reviewing Unchanged Code
"The file you imported from has some issues..."
Do: That's a separate PR. Create an issue if important.
Don't: Tests That Prove Old Code Was Bad
"Here's a test showing the old behavior was wrong."
Do: Write tests that break if your fix is reverted.
Tests should protect against regressions in your code,
not document why the change was needed. See
modules/pr-hygiene.md Principle 4.
Don't: Bundling Unrelated Changes
"I also reformatted the file and fixed a typo in another module."
Do: One PR = one logical change. Formatting, refactors,
and unrelated fixes belong in separate PRs. See
modules/pr-hygiene.md Principle 2.
Don't: Merge Code You Cannot Explain
"It works and the tests pass."
A PR where the author cannot explain how each changed section
works and how it might fail is not ready to merge. This is
especially true for AI-assisted code: generation speed creates
the illusion of understanding.
Do: Before marking a PR ready, ask the reviewing agent to
question you about the changed code: how each part works, what
assumptions it makes, and what inputs would break it. Continue
until you can answer without hesitation. Only merge code you
own front-to-back.
This applies to self-reviews: run the same probe before
requesting external review. Do not submit a PR for review that
you yourself do not fully understand.
Verify Findings Are Grounded (pr-review:findings-verified)
Every finding must cite a real location and a verbatim anchor. Write
findings to .review/findings.json and confirm each citation resolves:
Drop or label UNVERIFIED any finding the verifier fails (exit 1); only
verified findings enter the report. See Skill(imbue:review-core) Step 5
and Skill(imbue:structured-output) for the schema.
Integration with Other Tools
/fix-pr: After review identifies issues, use this to address them
/pr: To prepare a PR before review
pensive:unified-review: For the actual code analysis
pensive:bug-review: For deeper bug hunting if needed
scribe:slop-detector: For documentation AND commit message quality analysis
scribe:doc-generator: For PR description writing guidelines (slop-free)
Slop Detection Integration
Documentation Review
For all changed .md files, invoke Skill(scribe:slop-detector):
If slop found in commits: Add to SUGGESTION category with remediation guidance.
PR Description Review
Apply scribe:slop-detector to PR body:
Tier 1 words in description → SUGGESTION to rephrase
Marketing phrases ("unlock potential") → Flag for removal
Exit Criteria
Scope baseline established
All changes reviewed against scope
Findings classified correctly
Backlog items tracked as issues
Clear recommendation provided
Every BLOCKING and IN-SCOPE finding carries a Location (file:line) and
verbatim Anchor; citation_verifier.py confirmed all citations
(exit 0) or unverified findings are dropped/labeled UNVERIFIED
