Paw Review Workflow

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:

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."

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 paw_get_context returns isMultiRootWorkspace: true 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/)
• paw_get_context returned isMultiRootWorkspace: true
• 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)