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 [Trade-off] prefix (note: this mapping is active only when Review Interactive is true or smart; with false default, trade-offs are auto-resolved by paw-sot and appear as regular findings)
• 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

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 evaluation findings
• Severity: Must/Should/Could (from finding 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 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 <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

// Optional improvement example

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

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

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.