Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Analyzes PR changes to create ReviewContext.md and DerivedSpec.md artifacts. Handles both initial analysis and resumption after baseline research.
Understanding Activity Skill
Analyze pull request changes to create comprehensive understanding artifacts. This activity handles both initial context gathering and specification derivation after baseline research.
Reference: Follow Core Review Principles from paw-review-workflow skill.
Responsibilities
Gather review metadata from available platform tools or git and document changed files
Generate research prompt for baseline codebase analysis
Derive specification from PR description, code analysis, and baseline understanding
Create ReviewContext.md as authoritative parameter source
Validate all artifacts meet quality standards
Non-Responsibilities
Quality evaluation or gap identification (Evaluation stage skills)
Review comment generation (Output stage skills)
Git operations for checkout/restore (handled by paw-review-baseline)
Workflow orchestration and stage transitions (handled by workflow skill)
Execution Modes
This skill operates in two modes based on artifact state:
Initial Mode (No ReviewContext.md)
Execute Steps 1-3: Context gathering, research prompt generation, signal for baseline research.
Detection: ReviewContext.md not found at .paw/reviews/<identifier>/
Execute Step 4 only: Derive specification from baseline research.
Detection: Both ReviewContext.md AND CodeResearch.md exist at artifact path.
Context Detection
Determine context type before proceeding:
GitHub Context: GitHub PR URL or number provided
Use GitHub MCP tools for metadata retrieval
Extract commits, files, description from API
Azure DevOps Context: Azure DevOps PR URL or coordinates provided
Use supplied metadata or available platform tools
If executable review output is unavailable, retain artifact-only capability; do not probe APIs or permissions to manufacture capability
Local Context: No hosted PR reference
Verify current branch is checked out
Request base branch name from user
Use git commands for metadata
Before this activity begins, the orchestrator must resolve authorization preflight. If the preflight is blocked or required fields are missing, report the conflict before creating review artifacts.
Multi-Repository Mode
Detection: Any of these conditions triggers multi-repo mode:
Multiple PR URLs/numbers in input (e.g., PR-123 PR-456)
Multiple workspace folders open (detected via multiple .git directories)
PR links reference different repositories
Per-PR Processing:
Create separate artifact directories for each PR
Run Steps 1-4 independently for each repository
Cross-reference related PRs in each ReviewContext.md
Check ReviewContext.md for Remote field (if resuming)
Default to origin if not specified
Fetch PR Metadata:
GitHub: Use GitHub tools to retrieve PR details (number, title, author, state, description, labels, reviewers, CI status, changed files)
Azure DevOps: Use supplied metadata or available platform tools; use git for commit and diff data when hosted metadata capability is unavailable
Local: Use git to determine commits and changed files between base and head
Resolve Base Commit:
GitHub: Use base.sha from PR metadata (GitHub returns the merge-base)
Azure DevOps/Local: Run git merge-base <head-branch> origin/<base-branch> when platform metadata does not provide the merge-base
CRITICAL: The base commit must be the merge-base (common ancestor), NOT the current tip of the base branch. Using the tip causes files added to main after branching to appear as "deletions."
Record in ReviewContext.md: Base Commit: <sha> and Base Commit Source: github-api | platform-metadata | merge-base
Create ReviewContext.md:
Write to .paw/reviews/<identifier>/ReviewContext.md
Use template structure below
Include all metadata and flags
Step 2: Research Questions Generation
Identify Research Needs for each changed file:
How did the module function before changes?
What were integration points and dependencies?
What patterns and conventions were used?
What test coverage was present?
Create ResearchQuestions.md:
Write to .paw/reviews/<identifier>/ResearchQuestions.md
YAML frontmatter with metadata
Research questions organized by changed file/module
Clear investigation targets with file:line references
Step 3: Signal for Research
Report completion of initial phase:
Research Questions Ready
Created ResearchQuestions.md with questions about pre-change behavior.
Files to investigate at base commit <sha>:
- [list files]
Waiting for CodeResearch.md from baseline research.
