@paw-workflow/cli 0.0.1

package/dist/skills/paw-review-understanding/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: paw-review-understanding
+description: Analyzes PR changes to create ReviewContext.md and DerivedSpec.md artifacts. Handles both initial analysis and resumption after baseline research.
+metadata:
+  version: "0.0.1"
+---
+
+# 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
+
+1. **Determine Remote Name**:
+   - Check ReviewContext.md for `Remote` field (if resuming)
+   - Default to `origin` if not specified
+
+2. **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
+
+3. **Resolve Base Commit** (Non-GitHub only):
+   - Prefer the remote tracking branch reference
+   - Record source (remote|local|github-api) in ReviewContext.md
+
+4. **Create ReviewContext.md**:
+   - Write to `.paw/reviews/<identifier>/ReviewContext.md`
+   - Use template structure below
+   - Include all metadata and flags
+
+## Step 2: Research Questions Generation
+
+1. **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?
+
+2. **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.
+```
+
+**Activity Status**: Partial (awaiting baseline research)
+
+## Step 4: Derive Specification
+
+Execute only when CodeResearch.md exists.
+
+1. **Read All Source Material**:
+   - ReviewContext.md (PR description, changed files)
+   - CodeResearch.md (pre-change system behavior)
+   - Git diffs for all changes
+
+2. **Identify Explicit Goals**:
+   - Goals stated in PR description
+   - Requirements from linked issues
+   - Commit messages describing intent
+   - Mark as "Explicit" in DerivedSpec.md
+
+3. **Identify Inferred Goals**:
+   - Observable behavior changes from code analysis
+   - New functionality added
+   - Modified logic or control flow
+   - Mark as "Inferred" in DerivedSpec.md
+
+4. **Document Baseline Context** (from CodeResearch.md):
+   - How system worked before changes
+   - Existing patterns and conventions
+   - Integration points affected
+
+5. **Characterize Before/After Behavior**:
+   - Specific observable differences
+   - Changed APIs, endpoints, interfaces
+   - Modified data flows
+
+6. **Flag Discrepancies**:
+   - PR description contradicts code changes → BLOCK
+   - Intent unclear → document as inferred with evidence
+   - **CRITICAL**: If open questions remain, report blocked status
+
+7. **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):
+```
+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):
+```
+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>
+```

package/dist/skills/paw-review-workflow/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: paw-review-workflow
+description: Orchestrates the PAW Review workflow, coordinating activity skills to analyze PRs and generate comprehensive review feedback.
+metadata:
+  version: "0.0.1"
+---
+
+# 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. Read the skill file at `skills/paw-review-<skill-name>/SKILL.md`
+2. Read and internalize the skill instructions
+3. Only then begin executing the activity
+
+**Delegation prompt must include**: "First read your skill from `skills/paw-review-<skill-name>/SKILL.md`, 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 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)`