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. Authorization and Human Control

Apply this precedence:

1. True invariants protect evidence, target identity, head identity, finalized-comment state, and platform integrity.
2. Explicit user direction overrides PAW-owned defaults.
3. Defaults apply when direction is absent or ambiguous.

GitHub reviews are pending by default. Submit only with explicit authorization for the exact target, head, pending review, and event, followed by live revalidation. Generated feedback remains advisory; users can modify, skip, or override recommendations before posting.

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

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 Ownership (CRITICAL)

The orchestrating agent MUST NOT manually create artifacts that belong to activity skills. Each stage's artifacts must be produced by delegating to the designated skill. Manual population bypasses defaults, validation, and skill-specific logic (e.g., specialist selection defaults, ReviewContext field normalization).

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 (single-model mode)
├── GapAnalysis.md            # Stage: Evaluation (single-model mode)
├── REVIEW-{SPECIALIST}.md   # Stage: Evaluation (SoT mode, per specialist)
├── REVIEW-SYNTHESIS.md       # Stage: Evaluation (SoT mode, synthesized findings)
├── 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.

Authorization Preflight

Run before the Understanding stage:

1. Classify the review platform as github, azure-devops, or local.
2. Determine output capability from the available tools and context. Do not probe Azure DevOps APIs, identities, permissions, or submission endpoints solely for this preflight.
3. Resolve the requested output action:
   • GitHub default: pending
   • Azure DevOps/local default: artifact-only
   • Explicit submission: submit with APPROVE, REQUEST_CHANGES, or COMMENT
4. Resolve feedback scope as all by default or the user's explicit scope/output filter.
5. Resolve authorization as explicit, absent, or ambiguous, plus the platform-qualified target and current head.
6. Detect conflicts across PAW-owned instructions. Explicit user direction overrides a default; it does not override an integrity invariant or create a missing capability.
7. If authorization is ambiguous or an explicitly requested mutation is unavailable, report the conflict before analysis. Continue artifact-only only after the requested action is resolved.
8. Pass the resolved fields to paw-review-understanding for persistence in ReviewContext.md.

Repeating the same authorization for the same target, head, and event confirms it. A head change invalidates authorization and requires fresh analysis and authorization.

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, plus any review configuration parameters (e.g., Review Mode, Review Specialists) from the user's invocation
   • 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

Read Review Mode from ReviewContext.md to determine the evaluation path. If the value is not single-model, society-of-thought, or absent, report an error (Unknown Review Mode: <value>) and do not proceed.

Single-Model Mode (default)

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.

Society-of-Thought Mode

Engine: paw-sot (loaded into orchestrator session, not as subagent)

When Review Mode is society-of-thought, load the paw-sot skill directly and invoke it with a review context constructed from ReviewContext.md fields and understanding artifacts:

Review Context Field	Source
type	diff
coordinates	Diff: git diff <base-commit>...<head-commit>; Artifacts: ReviewContext.md, CodeResearch.md, DerivedSpec.md paths
output_dir	.paw/reviews/<identifier>/
specialists	Review Specialists value from ReviewContext.md
interaction_mode	Review Interaction Mode value from ReviewContext.md
interactive	Review Interactive value from ReviewContext.md
specialist_models	Review Specialist Models value from ReviewContext.md
perspectives	Review Perspectives value from ReviewContext.md
perspective_cap	Review Perspective Cap value from ReviewContext.md

After paw-sot completes orchestration and synthesis, proceed to the Output stage.

Error handling: If paw-sot skill cannot be loaded, report error to user — do not fall back to single-model silently.

Stage Gate: Verify REVIEW-SYNTHESIS.md exists 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 evaluation artifacts (ImpactAnalysis.md + GapAnalysis.md in single-model mode, or REVIEW-SYNTHESIS.md in SoT mode)
   • 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, and evaluation artifacts (ImpactAnalysis + GapAnalysis in single-model mode, or REVIEW-SYNTHESIS in SoT mode), 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 and, when explicitly authorized, the exact pending review submitted after live revalidation
   • Only posts comments marked "Ready for GitHub posting"
   • Skipped comments remain in artifact but NOT posted
   • Skipped for Azure DevOps/local contexts without executable output capability (provides artifact/manual posting instructions instead)

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

Output policy:

• Without explicit submission authorization, stop with a pending review.
• With explicit authorization, paw-review-github verifies repository, PR, live head, pending review ID, and event immediately before submission.
• Any missing or mismatched value leaves the pending review untouched and requires fresh authorization; a head mismatch also requires fresh analysis.
• Successful submission is terminal. Repeated authorization reports the completed state without another mutation.

Terminal Behavior

Upon workflow completion, report:

• Artifact locations (all generated files in .paw/reviews/<identifier>/)
• GitHub PRs: Pending or submitted review ID, event when submitted, and comment counts
• Azure DevOps/local: Capability/preflight result and 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 only when the review remains pending or artifact-only

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)