Transforms evaluation findings into structured review comments with comprehensive rationale. Handles both initial draft generation and critique response iteration.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Transforms evaluation findings into structured review comments with comprehensive rationale. Handles both initial draft generation and critique response iteration.
PAW Review Feedback Skill
Transform evaluation findings into structured review comments with comprehensive rationale sections that cite evidence, baseline patterns, impact, and best practices.
Reference: Follow Core Review Principles from paw-review-workflow skill.
Prerequisites
Verify these artifacts exist in .paw/reviews/<identifier>/:
ReviewContext.md (PR metadata and parameters)
CodeResearch.md (baseline codebase understanding)
DerivedSpec.md (what the PR is trying to achieve)
Evaluation artifacts — mode-gated (read Review Mode from ReviewContext.md):
If single-model or absent: require ImpactAnalysis.md + GapAnalysis.md
If society-of-thought: require REVIEW-SYNTHESIS.md
If present artifacts don't match configured mode, report inconsistency
CrossRepoAnalysis.md (optional—only for multi-repo reviews)
If any required artifact is missing, report blocked status—earlier stages must complete first.
SoT mode input mapping: When REVIEW-SYNTHESIS.md is the evaluation source, map findings to the comment pipeline as follows:
Severity: must-fix → Must, should-fix → Should, consider → Could
Trade-offs from "Trade-offs Requiring Decision" section → Should-tier with prefix (note: this mapping is active only when is or ; with default, trade-offs are auto-resolved by paw-sot and appear as regular findings)
[Trade-off]
Review Interactive
true
smart
false
Observations section → excluded from comment generation (contextual-tier, not actionable)
File:line references from specialist citations map to comment File+lines fields. If a synthesis finding lacks specific file:line references, generate a thread-level comment instead of inline
Impact evidence is embedded in synthesis findings (no separate ImpactAnalysis.md)
Multi-repo detection: Check if CrossRepoAnalysis.md exists. If present, incorporate cross-repo gaps into comment generation.
Core Responsibilities
Batch related findings into coherent comments (One Issue, One Comment principle)
Transform findings into clear, actionable review comments
Generate comprehensive rationale sections citing evidence, baseline patterns, impact, and best practices
Create ReviewComments.md with all comments, rationale, and metadata
Critique Response Mode: Update comments based on critic assessment, marking each with **Final**: status
Enable tone adjustment while preserving evidence and IDs
Note: GitHub posting is handled by the paw-review-github skill after critique iteration completes.
Process Steps
Step 1: Batch Related Findings (One Issue, One Comment)
Group findings that share the same root cause:
Batching Criteria:
Same underlying issue manifesting in multiple locations
Related error handling gaps across a module
Consistent pattern violations throughout changed files
Missing tests for related functionality
Batching Approach:
Create single comment referencing multiple file:line locations, OR
Create linked comments (note relationship in comment text)
Avoid scattering feedback for one logical issue across multiple disconnected comments
Examples:
Multiple null checks missing in same class → One comment listing all locations
Architectural concern spanning 3 files → One thread comment discussing the pattern
Missing tests for several related methods → One comment about test coverage gap
Cross-reference notation from the gap's related PR
Cross-Repo Finding Format:
**Type**: Must (from CrossRepoAnalysis.md)
**Category**: Cross-Repository Coordination
**Files**: [repo-b/src/api/client.ts:8](repo-b/src/api/client.ts#L8)
**Issue**: Missing consumer update for `lastLogin` field
**Evidence**:
- Added in repo-a: [repo-a/src/types/user.ts:22](repo-a/src/types/user.ts#L22)
- Missing in repo-b: [repo-b/src/api/client.ts](repo-b/src/api/client.ts)
**Cross-Reference**: (Cross-repo: see repo-a#123 for interface change)
Routing Cross-Repo Comments:
Post cross-repo findings to the PR that needs to make the change
Include cross-reference notation: (Cross-repo: see owner/other-repo#NNN for [context])
Note deployment order in comment if relevant from CrossRepoAnalysis.md
Step 2: Build Comment Objects
For each finding or batched group of findings, create structured comment:
Required Fields:
Type: inline (line-specific) or thread (file/concept-level)
File(s) and line range(s): Specific locations from evaluation findings
For EVERY comment, create comprehensive rationale with four components:
Evidence:
File:line references from evaluation findings
Specific code snippets showing the issue
Concrete examples of the problem
Baseline Pattern:
Reference existing code in the codebase to show how similar situations are handled
Cite established conventions and patterns from the codebase
Show consistency/inconsistency with existing code
Important: Do NOT reference CodeResearch.md or other PAW artifacts in comments—cite actual file:line locations instead
Impact:
Explain what could go wrong (for Must items: specific failure modes)
Describe user/system impact of not addressing
Note performance, security, or maintainability implications
Reference impact findings from analysis where applicable
Important: Do NOT reference ImpactAnalysis.md, REVIEW-SYNTHESIS.md, or other PAW artifacts in comments—describe impacts directly
Best Practice Citation:
Reference industry best practices from review-research-notes.md (if available)
Cite language/framework conventions
Link to relevant documentation or style guides
Note security/safety standards
Example Rationale:
**Rationale:**-**Evidence**: `auth.ts:45` shows user input passed directly to SQL query without validation
-**Baseline Pattern**: Similar code in `database.ts:120-130` uses parameterized queries
-**Impact**: SQL injection vulnerability allowing unauthorized data access or modification
-**Best Practice**: OWASP Top 10 - Always use parameterized queries for user input
Step 4: Create ReviewComments.md
Generate comprehensive markdown document:
---
date: <timestamp>
git_commit: <sha>
branch: <branch>
repository: <repo>
topic: "Review Comments for <PR/Branch>"
tags: [review, comments, feedback]
status: draft
---
# Review Comments for <PRNumberorBranchSlug>**Context**: GitHub PR #X OR Non-GitHub branch feature/...
**Base Branch**: <base>**Head Branch**: <head>**Review Date**: <date>**Reviewer**: <gituser>**Status**: ⏳ Pending critique
## Summary Comment
<Brief, positive opening acknowledging the work and effort><Overviewoffeedbackscopeandorganization>**Findings**: X Must-address items, Y Should-address items, Z optional suggestions
---
## Inline Comments
### File: `path/to/file.ts` | Lines: 45-50
**Type**: Must
**Category**: Safety
<Clearexplanationoftheissue>**Suggestion:**
```typescript
// Proposed fix or approach with code example
Rationale:
Evidence: file.ts:45 shows unchecked null access
Baseline Pattern: Similar code in file.ts:100 uses null checks before accessing properties
Impact: Potential null pointer exception causing crash in production
Best Practice: Defensive programming - validate inputs before use
File: path/to/another.ts | Lines: 88
Type: Could
Category: Performance
Suggestion:
// Optional improvement example
Rationale:
Evidence: another.ts:88 shows inefficient pattern
Baseline Pattern: More efficient approach used in optimized.ts:42
Impact: Minor performance improvement in non-critical path
Best Practice: Optimization best practice reference
Thread Comments
File: path/to/module/ (Overall Architecture)
Type: Should
Category: Maintainability
Rationale:
...
Questions for Author
<Question about intent or design decision - reference specific file:line>
**Key Requirements:**
- Default to a positive, constructive summary; honor explicit tone direction that remains professional and evidence-based
- Every comment has rationale with all four components
- File:line references for all evidence
- Code examples for non-trivial suggestions
## Critique Response Mode
When ReviewComments.md already contains Assessment sections (from `paw-review-critic`), enter Critique Response Mode to incorporate feedback and finalize comments.
### Detection
- Check if comments have `**Assessment:**` sections
- If assessments exist, this is a second pass to incorporate critique
- Skip to Critique Response Mode steps below
### Process
For each comment with an assessment:
1. **Preserve Original**: Keep the original comment text intact
2. **Include Critique**: The Assessment section remains as-is
3. **Add Updated Version**: Based on the recommendation:
- **Include as-is**: Add `**Final**: ✓ Ready for GitHub posting`
- **Modify**: Add `**Updated Comment:**` section with revised text addressing critique feedback, then `**Final**: ✓ Ready for GitHub posting`
- **Skip**: Add `**Final**: Skipped per critique - [reason]` (comment remains in artifact but won't post to GitHub)
### Updated Comment Structure
```markdown
### File: `auth.ts` | Lines: 45-50
**Type**: Must
**Category**: Safety
[Original comment text - preserved exactly]
**Suggestion:**
[Original suggestion code]
**Rationale:**
[Original rationale]
**Assessment:**
- **Usefulness**: Medium - [critique justification]
- **Accuracy**: [validation]
- **Alternative Perspective**: [alternatives considered]
- **Trade-offs**: [trade-off analysis]
- **Recommendation**: Modify to soften tone
**Updated Comment:**
[Revised comment text incorporating critique feedback]
**Updated Suggestion:**
[Revised suggestion if needed]
**Final**: ✓ Ready for GitHub posting
Skip Handling
For comments with Recommendation: Skip:
Do NOT remove the comment from ReviewComments.md
Add **Final**: Skipped per critique - [reason from assessment]
These comments provide documentation but won't be posted to GitHub
Reviewer can override by changing Final to "✓ Ready for GitHub posting"
Critique Response Completion
After processing all comments with assessments:
Update ReviewComments.md status from draft to finalized
All comments must have **Final**: markers
Report count of comments: Include as-is, Modified, Skipped
Tone Adjustment
Support tone adjustments while preserving evidence and IDs:
NEVER reference PAW artifacts (ReviewContext.md, CodeResearch.md, DerivedSpec.md, ImpactAnalysis.md, GapAnalysis.md, REVIEW-SYNTHESIS.md, etc.) in comments
These files are NOT committed to the branch and are NOT accessible to the PR submitter
Instead: Cite actual codebase files with file:line references
PAW artifacts are for YOUR internal use and for the reviewer's understanding only
Rationale Required:
EVERY comment must have complete rationale section
All four components (Evidence, Baseline Pattern, Impact, Best Practice) required
No suggestions without justification
Evidence-Based:
All recommendations informed by existing codebase patterns
File:line references for all claims
Code examples from actual codebase when citing patterns
Human Control:
Reviewer can modify any comment before GitHub posting
Reviewer can override Skip recommendations
Final decisions rest with human reviewer
Comprehensive Coverage:
By default, transform all findings from evaluation artifacts into comments
Honor explicit scope or output filters recorded in ReviewContext.md
Do not infer filtering from contributor relationship or unstated context
Positive observations included in summary
Questions documented in dedicated section
One Issue, One Comment:
Related findings batched into single coherent comment
Clear linking when related comments must be separate
Avoid fragmenting feedback for same root cause
Validation Checklist
Initial Pass (Draft Generation)
Before completing initial pass, verify:
All in-scope evaluation findings transformed into comments
Related issues batched appropriately (not scattered)
Every comment has complete rationale (Evidence, Baseline Pattern, Impact, Best Practice)
Code examples included for non-trivial suggestions
Inline vs thread distinction applied correctly
Summary follows the persisted professional tone direction; otherwise it is positive and constructive by default
ReviewComments.md complete with all sections and metadata
ReviewComments.md status is draft
No PAW artifact references in comment text
Critique Response Pass (Finalization)
Before completing critique response, verify:
All comments with Assessment sections processed
**Final**: marker added to every comment
**Updated Comment:** added where Recommendation was Modify
Skip reasons documented for all skipped comments
ReviewComments.md status updated to finalized
Comment counts accurate: Include as-is, Modified, Skipped
Completion Response
Initial Pass (Draft):
Activity complete.
Artifact saved: .paw/reviews/<identifier>/ReviewComments.md
Status: Draft - awaiting critique
Summary:
- Total comments generated: N
- Must: X, Should: Y, Could: Z
- Awaiting paw-review-critic assessment
Critique Response (Finalized):
Activity complete.
Artifact saved: .paw/reviews/<identifier>/ReviewComments.md
Status: Finalized - ready for GitHub posting
Summary:
- Comments ready for posting: X
- Comments modified per critique: Y
- Comments skipped per critique: Z
Next: Run paw-review-github to post finalized comments to GitHub pending review.
