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:

1. Read CrossRepoAnalysis.md → extract "Cross-Repository Gaps" section
2. 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

1. <Question about intent or design decision - reference specific file:line>

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

Adjustment Process:

1. Accept tone parameters from reviewer
2. Regenerate comment TEXT ONLY (description + suggestion)
3. Preserve: File:line locations, rationale, evidence, categorization
4. 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.