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 PR metadata (GitHub API or git diff) 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>/

Resumption Mode (ReviewContext.md + CodeResearch.md exist)

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: PR URL or number provided

•Use GitHub MCP tools for metadata retrieval
•Extract commits, files, description from API

Non-GitHub Context: No PR reference

•Verify current branch is checked out
•Request base branch name from user
•Use git commands for metadata

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

Identifier Scheme:

•Single PR: PR-<number> (e.g., PR-123)
•Multi-repo PR: PR-<number>-<repo-slug> (e.g., PR-123-my-api)
•Repo-slug: Last segment of repository name, lowercase, special chars removed

ReviewContext.md Extension (for multi-repo):

yaml

repository: owner/repo-name
related_prs:
  - number: 456
    repository: owner/other-repo
    relationship: "depends-on"  # or "related-to", "blocks"

Step 1: Context Gathering & ReviewContext.md Creation

•
Determine Remote Name:
- •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)
- •Non-GitHub: 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)
- •Non-GitHub: Run git merge-base <head-branch> origin/<base-branch> to find common ancestor
- •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 | 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:

code

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.

Activity Status: Partial (awaiting baseline research)

Step 4: Derive Specification

Execute only when CodeResearch.md exists.

•
Read All Source Material:
- •ReviewContext.md (PR description, changed files)
- •CodeResearch.md (pre-change system behavior)
- •Git diffs for all changes
•
Identify Explicit Goals:
- •Goals stated in PR description
- •Requirements from linked issues
- •Commit messages describing intent
- •Mark as "Explicit" in DerivedSpec.md
•
Identify Inferred Goals:
- •Observable behavior changes from code analysis
- •New functionality added
- •Modified logic or control flow
- •Mark as "Inferred" in DerivedSpec.md
•
Document Baseline Context (from CodeResearch.md):
- •How system worked before changes
- •Existing patterns and conventions
- •Integration points affected
•
Characterize Before/After Behavior:
- •Specific observable differences
- •Changed APIs, endpoints, interfaces
- •Modified data flows
•
Flag Discrepancies:
- •PR description contradicts code changes → BLOCK
- •Intent unclear → document as inferred with evidence
- •CRITICAL: If open questions remain, report blocked status
•
Create DerivedSpec.md:
- •Write to .paw/reviews/<identifier>/DerivedSpec.md
- •Use template structure below
- •Zero open questions allowed

Artifact Directory Structure

GitHub Context: .paw/reviews/PR-<number>/ Non-GitHub Context: .paw/reviews/<branch-slug>/

Branch slug: lowercase, / → -, remove invalid chars.

Validation Criteria

ReviewContext.md

•All metadata fields populated
•Flags section identifies applicable conditions
•Base and head commit SHAs recorded

ResearchQuestions.md

•Questions are specific and answerable
•All changed files covered
•Clear investigation targets with file:line references

DerivedSpec.md

•Explicit vs inferred goals distinguished
•Baseline behavior documented from CodeResearch.md
•Observable before/after behavior characterized
•All file:line references accurate
•Zero open questions

Completion Response

After Initial Mode (Steps 1-3):

code

Activity complete.
Artifact saved: .paw/reviews/<identifier>/ReviewContext.md
Artifact saved: .paw/reviews/<identifier>/ResearchQuestions.md
Status: Partial
Summary: Context gathered, awaiting baseline research.

After Resumption Mode (Step 4):

code

Activity complete.
Artifact saved: .paw/reviews/<identifier>/DerivedSpec.md
Status: Success
Summary: Specification derived with [N] explicit and [M] inferred goals.

ReviewContext.md Template

markdown

---
date: <YYYY-MM-DD HH:MM:SS TZ>
git_commit: <head commit SHA>
branch: <head branch>
repository: <owner/repo OR local>
topic: "Review Context for <PR Title or Branch>"
tags: [review, context, metadata]
status: complete
---

# ReviewContext

**PR Number**: <number> (GitHub) OR **Branch**: <branch-slug> (non-GitHub)
**Remote**: <remote-name> (default: origin, or "No remote configured")
**Base Branch**: <base-branch>
**Head Branch**: <head-branch>
**Base Commit**: <sha>
**Base Commit Source**: remote|local|github-api
**Head Commit**: <sha>
**Repository**: <owner>/<repo> OR "Local repository"
**Author**: <username or git author>
**Title**: <pr-title or derived from commits>
**State**: open|closed|draft (GitHub) OR active (non-GitHub)
**Created**: <date> (GitHub only)
**CI Status**: <passing|failing|pending> (GitHub) OR "Not available" (non-GitHub)
**Labels**: <label-list> (GitHub) OR "N/A" (non-GitHub)
**Reviewers**: <reviewer-list> (GitHub) OR "N/A" (non-GitHub)
**Linked Issues**: <issue-urls> (GitHub) OR "Inferred from commits" (non-GitHub)
**Changed Files**: <count> files, +<additions> -<deletions>
**Artifact Paths**: .paw/reviews/<identifier>/

## Description

<PR description text or commit message summary>

## Flags

- [x/] CI Failures present
- [x/] Breaking changes suspected

## Artifacts

- [x/] ReviewContext.md - This file
- [x/] ResearchQuestions.md - Research questions for baseline analysis
- [x/] CodeResearch.md - Baseline understanding (paw-review-baseline)
- [x/] DerivedSpec.md - Derived specification

## Metadata

**Created**: <timestamp>
**Git Commit**: <current HEAD SHA>
**Reviewer**: <current git user>
**Analysis Tool**: PAW Review Understanding

DerivedSpec.md Template

markdown

---
date: <YYYY-MM-DD HH:MM:SS TZ>
git_commit: <head commit SHA>
branch: <head branch>
repository: <owner/repo OR local>
topic: "Derived Specification for <PR Title or Branch>"
tags: [review, specification, analysis]
status: complete
---

# Derived Specification: <PR Title or Branch>

## Intent Summary

<1-2 sentence summary of what this PR accomplishes>

## Explicit Goals (Stated in PR/Issues)

Goals explicitly mentioned in PR description, linked issues, or commit messages:

1. <Goal from PR description>
2. <Goal from linked issue #X>

*Source: PR description, Issue #X, commits <sha>...<sha>*

## Inferred Goals (Observed from Code)

Goals derived from code analysis that weren't explicitly stated:

1. <Observable behavior change with file:line reference>
2. <New functionality added with file:line reference>

*Source: Code analysis of changed files*

## Baseline Behavior (Pre-Change)

How the system worked before changes (from CodeResearch.md):

**Module**: `path/to/module.ext`
- **Before**: <behavior description>
- **Integration**: <connections to other components>
- **Patterns**: <conventions used>

*Source: CodeResearch.md at base commit <sha>*

## Observable Changes (Before → After)

### Changed Interfaces

| Component | Before | After | Breaking? |
|-----------|--------|-------|-----------|
| `module.func()` | params: (a, b) | params: (a, b, c) | Yes |

### Changed Behavior

**Feature**: <feature name>
- **Before**: <from CodeResearch.md>
- **After**: <from code analysis>
- **Impact**: <observable difference>

[file:line references for each claim]

## Scope Boundaries

**In Scope**: <What this PR changes>
**Out of Scope**: <What this PR does NOT change>

## Assumptions

<Document only when necessary to resolve ambiguity>

## Open Questions

**CRITICAL**: This section must be empty before completion.

## Discrepancies Flagged

[Only if conflicts exist]

**PR Description States**: <quote>
**Code Analysis Shows**: <evidence with file:line>
**Resolution**: [Pending | Resolved: <how>]

## References

- **ReviewContext.md**: Metadata and changed file summary
- **CodeResearch.md**: Pre-change baseline understanding
- **Commits**: <base-sha>..<head-sha>