Paw Review Workflow

---
name: paw-review-workflow
description: Orchestrates the PAW Review workflow, coordinating activity skills to analyze PRs and generate comprehensive review feedback.
---

# PAW Review Workflow Skill

This workflow skill orchestrates the complete PAW Review process, coordinating activity skills through subagent execution to analyze pull requests and generate comprehensive review feedback.

## Core Review Principles

These principles apply to ALL review stages. Activity skills reference these principles rather than duplicating them.

### 1. Evidence-Based Documentation

Every observation, finding, or claim MUST be supported by:
- Specific file:line references
- Concrete code patterns or test results
- Direct evidence from the codebase

**NEVER** include speculation, assumptions, or subjective preferences without evidence.

### 2. File:Line Reference Requirement

All code-related claims require specific file:line citations:
- `[src/module.ts:45](src/module.ts#L45)` for single lines
- `[src/module.ts:45-52](src/module.ts#L45-L52)` for ranges
- Multiple locations should be listed explicitly

### 3. No Fabrication Guardrail

**CRITICAL**: Do not fabricate, invent, or assume information:
- If information is unavailable, state "Not found" or "Unable to determine"
- Do not hallucinate file contents, function behaviors, or patterns
- When uncertain, document the uncertainty explicitly

### 4. Document, Don't Critique (Early Stages)

Understanding and baseline research stages document what exists—they do NOT:
- Evaluate quality or suggest improvements
- Identify issues or bugs
- Make recommendations
- Critique implementation decisions

Evaluation and critique happen in designated later stages only.

### 5. Human Control Principle

The review workflow assists human reviewers—it does NOT replace their judgment:
- Pending reviews are NEVER auto-submitted
- Final decisions on all comments rest with the human reviewer
- Generated feedback is advisory, not prescriptive
- Humans can modify, skip, or override any recommendation

### 6. Artifact Completeness

Each stage produces complete, well-structured artifacts:
- No placeholders or "TBD" markers
- No unresolved questions blocking downstream stages
- Each artifact is self-contained and traceable to sources

## Subagent Contract

Activity skills are executed via delegated agent sessions.

### Skill Loading (CRITICAL)

**Every subagent MUST load their skill FIRST before executing any work**:

{{#vscode}}
1. Call `paw_get_skill` with the skill name (e.g., `paw-review-understanding`)
2. Read and internalize the skill instructions
3. Only then begin executing the activity

**Delegation prompt must include**: "First load your skill using `paw_get_skill('paw-review-<skill-name>')`, then execute the activity."
{{/vscode}}
{{#cli}}
1. Load the skill by name (e.g., `paw-review-understanding`)
2. Read and internalize the skill instructions
3. Only then begin executing the activity

**Delegation prompt must include**: "First load the `paw-review-<skill-name>` skill, then execute the activity."
{{/cli}}

### Response Format

Upon completion, respond with artifact path and status (Success, Partial, or Blocked).

### Artifact Path Confirmation

Always confirm the exact path where artifacts were written. Downstream stages depend on this.

## Artifact Directory Structure

All review artifacts are stored in a consistent directory structure:

```
.paw/reviews/<identifier>/
├── ReviewContext.md          # Stage: Understanding (initial)
├── ResearchQuestions.md      # Stage: Understanding (initial)
├── CodeResearch.md           # Stage: Baseline Research
├── DerivedSpec.md            # Stage: Understanding (after research)
├── ImpactAnalysis.md         # Stage: Evaluation (impact)
├── GapAnalysis.md            # Stage: Evaluation (gaps)
├── CrossRepoAnalysis.md      # Stage: Correlation (multi-repo only)
└── ReviewComments.md         # Stage: Output (evolves: draft → assessed → finalized → posted)
```

**ReviewComments.md Evolution:**
1. **Draft**: Initial comments generated by feedback skill
2. **Assessed**: Assessment sections added by critic skill
3. **Finalized**: `**Final**:` markers added by feedback skill (critique response)
4. **Posted**: `**Posted**:` status added by github skill

### Identifier Derivation

- **Single GitHub PR**: `PR-<number>` (e.g., `PR-123`)
- **Multi-repo GitHub PRs**: `PR-<number>-<repo-slug>` per PR (e.g., `PR-123-my-api/`, `PR-456-my-frontend/`)
- **Local branch**: Slugified branch name (e.g., `feature-new-auth`)

**Repo-slug derivation**: Last path segment of repository name, lowercase, special chars removed.
Example: `acme-corp/my-api-service` → `my-api-service`

**Multi-repo detection**: Use when multiple workspace folders are open in VS Code OR multiple PRs provided.

## Workflow Orchestration

The workflow executes stages in sequence, with each stage producing artifacts consumed by downstream stages.

### Understanding Stage

**Skills**: `paw-review-understanding`, `paw-review-baseline`

**Sequence**:
1. Run `paw-review-understanding` activity
   - Input: PR number/URL or branch context
   - Output: `ReviewContext.md`, `ResearchQuestions.md`
   
2. Run `paw-review-baseline` activity
   - Input: ReviewContext.md, ResearchQuestions.md
   - Output: `CodeResearch.md`
   
3. Run `paw-review-understanding` activity (resume)
   - Input: ReviewContext.md, CodeResearch.md
   - Detects CodeResearch.md exists → skips to specification derivation
   - Output: `DerivedSpec.md`

**Stage Gate**: Verify ReviewContext.md, CodeResearch.md, DerivedSpec.md exist before proceeding.

### Evaluation Stage

**Skills**: `paw-review-impact`, `paw-review-gap`

**Sequence**:
1. Run `paw-review-impact` activity
   - Input: All understanding artifacts
   - Output: `ImpactAnalysis.md`
   
2. Run `paw-review-gap` activity
   - Input: All understanding + impact artifacts
   - Output: `GapAnalysis.md`

**Stage Gate**: Verify ImpactAnalysis.md, GapAnalysis.md exist before proceeding.

### Cross-Repository Correlation Stage (Multi-Repo Only)

**Skill**: `paw-review-correlation`

**Condition**: Only run when multiple PRs/repositories detected. Skip for single-repo reviews.

**Detection Criteria** (any of):
- Multiple PR artifact directories exist (e.g., `PR-123-repo-a/`, `PR-456-repo-b/`)
- Multiple workspace folders open (detected via multiple `.git` directories)
- ReviewContext.md contains `related_prs` entries

**Sequence**:
1. Run `paw-review-correlation` activity
   - Input: All per-repo ImpactAnalysis.md and GapAnalysis.md files
   - Output: `CrossRepoAnalysis.md` (in primary repo's artifact directory)

**Stage Gate**: Verify CrossRepoAnalysis.md exists before proceeding to Output stage.

**Skip Behavior**: For single-repo reviews, proceed directly to Output stage without running correlation.

### Output Stage

**Skills**: `paw-review-feedback`, `paw-review-critic`, `paw-review-github`

The Output stage uses an iterative feedback-critique pattern to refine comments before posting to GitHub.

**Sequence**:

1. **Run `paw-review-feedback` activity (Initial Pass)**
   - Input: All prior artifacts (ReviewContext, CodeResearch, DerivedSpec, ImpactAnalysis, GapAnalysis, optionally CrossRepoAnalysis)
   - Output: `ReviewComments.md` with draft comments (status: draft)
   - Does NOT post to GitHub in this pass
   
2. **Run `paw-review-critic` activity**
   - Input: ReviewComments.md + all prior artifacts
   - Output: Assessment sections added to `ReviewComments.md`
   - Generates Iteration Summary with Include/Modify/Skip recommendations

3. **Run `paw-review-feedback` activity (Critique Response)**
   - Input: ReviewComments.md (with assessments) + all prior artifacts
   - Detects Assessment sections → enters Critique Response Mode
   - Output: Updated comments with `**Final**:` markers (status: finalized)
   - Comments marked: "Ready for GitHub posting" or "Skipped per critique"

4. **Run `paw-review-github` activity (GitHub PRs only)**
   - Input: ReviewComments.md with finalized comments
   - Output: Pending review created on GitHub, ReviewComments.md updated with post status
   - Only posts comments marked "Ready for GitHub posting"
   - Skipped comments remain in artifact but NOT posted
   - **Skipped for non-GitHub contexts** (provides manual posting instructions instead)

**Stage Gate**: Verify all comments have `**Final**:` markers before GitHub posting.

**Human Control Point**: The pending review is created but NOT submitted. Human reviewer:
- Reviews generated comments in GitHub UI
- Can see full comment history in ReviewComments.md (original → assessment → updated)
- Can manually add skipped comments if they disagree with critique
- Modifies, adds, or removes comments as needed
- Submits review when satisfied

## Terminal Behavior

Upon workflow completion, report:
- Artifact locations (all generated files in `.paw/reviews/<identifier>/`)
- **GitHub PRs**: Pending review ID and comment counts (e.g., "Pending review created: Review ID 12345678, 6 comments posted, 2 skipped per critique")
- **Non-GitHub**: Manual posting instructions location
- **Multi-repo reviews**: Cross-repo findings summary (interface contracts analyzed, mismatches found, deployment order)
- Comment evolution summary: original comments generated, modified per critique, skipped per critique
- Next steps for the human reviewer (review comments in GitHub UI, edit as needed, submit when ready)

## Cross-Repository Support

If multiple repositories or PRs are detected:
1. Identify which repositories have changes
2. Determine the primary repository (where changes originate)
3. For each repository, run the Understanding and Evaluation stages independently
4. Run Cross-Repository Correlation stage to synthesize findings across repos
5. In the Output stage, incorporate cross-repo findings into review comments
6. Note cross-repo dependencies in comments using notation: `(See also: owner/other-repo#NNN)`