PAW Review Feedback Skill

Transform gap analysis 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)
ImpactAnalysis.md (system-wide impact assessment)
GapAnalysis.md (categorized findings with evidence)
CrossRepoAnalysis.md (optional—only for multi-repo reviews)

If any required artifact is missing, report blocked status—earlier stages must complete first.

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

Step 1.5: Incorporate Cross-Repository Correlation Findings (Multi-Repo Only)

Condition: Only if CrossRepoAnalysis.md exists in the artifact directory.

When CrossRepoAnalysis.md is present, add cross-repo gaps to the findings list:

Load Cross-Repo Gaps:

Read CrossRepoAnalysis.md → extract "Cross-Repository Gaps" section
For each gap, create a finding entry with:
- Severity from gap (Must/Should/Could)
- Evidence from gap's file:line references
- 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 GapAnalysis.md
Severity: Must/Should/Could (from GapAnalysis categorization)
Category: Correctness, Safety, Testing, Maintainability, Performance, etc.
Description: Clear, specific explanation of the issue
Suggestion: Code example or recommended approach
Rationale: (generated in next step)

Inline vs Thread Determination:

Use Inline for:

Issue specific to particular lines of code
Logic error in a function
Missing check at a specific location
Performance issue in a specific loop
Test gap for a specific method

Use Thread for:

Architectural concern across >3 files
Missing integration tests spanning components
Consistent pattern violation throughout the PR
Cross-cutting concerns (logging, error handling approach)
General discussion about design decisions

Step 3: Generate Rationale Sections

For EVERY comment, create comprehensive rationale with four components:

Evidence:

File:line references from GapAnalysis.md 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 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 <PR Number or Branch Slug>

**Context**: GitHub PR #X OR Non-GitHub branch feature/...
**Base Branch**: <base>
**Head Branch**: <head>
**Review Date**: <date>
**Reviewer**: <git user>
**Status**: ⏳ Pending critique

## Summary Comment

<Brief, positive opening acknowledging the work and effort>

<Overview of feedback scope and organization>

**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

<Clear explanation of the issue>

**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>
<Clarification needed on edge case handling>


**Key Requirements:**
- Summary must be positive and constructive
- 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:

Default Tone:

Professional and constructive
Inclusive language: "we", "let's", "this code" (not "you didn't")
Balanced: acknowledge good work, suggest improvements
Specific: cite exact locations and evidence

Tone Adjustment Parameters: | Parameter | Low | High | |-----------|-----|------| | Directness | More diplomatic | More direct | | Encouragement | Matter-of-fact | More encouraging | | Formality | More casual | More formal | | Conciseness | More explanatory | More concise |

Adjustment Process:

Accept tone parameters from reviewer
Regenerate comment TEXT ONLY (description + suggestion)
Preserve: File:line locations, rationale, evidence, categorization
Update ReviewComments.md with new text

Guardrails

No PAW Artifact References in Comments:

NEVER reference PAW artifacts (ReviewContext.md, CodeResearch.md, DerivedSpec.md, ImpactAnalysis.md, GapAnalysis.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:

ALL findings from GapAnalysis.md must be transformed into comments
No cherry-picking or filtering
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 GapAnalysis.md 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 comment is positive and constructive
[ ] 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.