@paw-workflow/cli 0.0.1

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

@@ -0,0 +1,268 @@
+---
+name: paw-review-baseline
+description: Analyzes the codebase at the PR's base commit to establish baseline understanding for review comparison.
+metadata:
+  version: "0.0.1"
+---
+
+# Baseline Research Activity Skill
+
+Analyze the codebase **at the base commit** (before PR changes) to document how the system worked, what patterns existed, and what context informs understanding of the changes.
+
+> **Reference**: Follow Core Review Principles from `paw-review-workflow` skill.
+
+## CRITICAL: Baseline Only
+
+**Your only job is to document the pre-change codebase as it existed.**
+
+- DO NOT analyze the PR changes or compare before/after
+- DO NOT suggest improvements or identify issues
+- DO NOT critique the implementation
+- ONLY describe what existed before: behavior, patterns, conventions, integration points
+
+## Responsibilities
+
+- Checkout base commit safely (with state restoration)
+- Research how affected modules functioned before changes
+- Document integration points and dependencies
+- Identify patterns and conventions in affected areas
+- Create CodeResearch.md with baseline understanding
+
+## Non-Responsibilities
+
+- PR change analysis or before/after comparison (understanding skill)
+- Quality evaluation or recommendations (evaluation skills)
+- Workflow orchestration (handled by workflow skill)
+
+## Prerequisites
+
+- ReviewContext.md must exist with base commit SHA
+- ResearchQuestions.md should exist with research questions
+
+## Multi-Repository Mode
+
+When reviewing PRs across multiple repositories:
+
+### Detection
+
+Multi-repo mode activates when:
+- Multiple PR URLs/numbers provided in input
+- Multiple workspace folders open (detected via multiple `.git` directories)
+- ReviewContext.md contains `related_prs` entries
+
+### Per-Repository Processing
+
+Process each repository's base commit independently:
+
+1. **Iterate Repositories**: For each PR in the review set:
+   - Read its ReviewContext.md from `.paw/reviews/PR-<number>-<repo-slug>/`
+   - Extract base commit SHA and repository path
+   
+2. **Checkout and Research**: For each repository:
+   - Navigate to repository root
+   - Checkout base commit
+   - Conduct baseline research
+   - Create CodeResearch.md in that PR's artifact directory
+   - Restore original state before moving to next repository
+
+3. **State Restoration**: Between repositories:
+   - Restore each repository to its original branch/HEAD
+   - Verify clean working state before proceeding
+
+### Cross-Repository Pattern Identification
+
+When analyzing multiple repositories, also document:
+
+- **Shared Conventions**: Common patterns used across repos (naming, error handling, API styles)
+- **Interface Contracts**: How repositories communicate (API schemas, shared types, event formats)
+- **Dependency Relationships**: Which repo depends on which (import paths, package dependencies)
+
+Add a "Cross-Repository Patterns" section to each CodeResearch.md noting patterns that appear across the repository set.
+
+### Error Handling
+
+If one repository fails:
+- Document the failure in that PR's artifact directory
+- Continue with remaining repositories
+- Report partial completion status
+
+## Execution Steps
+
+### Step 1: Sync Remote State
+
+**Desired End State**: The base commit SHA (from ReviewContext.md) is locally available.
+
+1. Extract from ReviewContext.md: remote name, base branch, base commit SHA
+2. Ensure the repository has the latest remote state for the base branch
+3. Verify the base commit is reachable locally
+4. If the commit cannot be reached, report the blocker with context
+
+### Step 2: Checkout Base Commit
+
+**Desired End State**: Working directory is at the base commit, with ability to restore original state.
+
+1. Record current branch/HEAD for later restoration
+2. Checkout the base commit
+3. Confirm the working directory reflects the pre-change state
+
+**CRITICAL**: All subsequent research must analyze code at this commit.
+
+### Step 3: Read Research Questions
+
+1. Read `ResearchQuestions.md`
+2. Note list of changed files from ReviewContext.md
+3. Identify modules/areas needing baseline documentation
+
+### Step 4: Analyze Pre-Change Codebase
+
+Focus on areas identified in research prompt:
+
+**Behavioral Documentation**:
+- How modules functioned before changes
+- Entry points, data flows, contracts
+- Error handling approaches
+
+**Integration Mapping**:
+- Components depending on changed modules
+- External dependencies
+- API contracts and interfaces
+
+**Pattern Recognition**:
+- Coding conventions in affected areas
+- Testing patterns for similar components
+- Documentation patterns
+
+**Test Coverage Baseline**:
+- Existing tests for affected areas
+- Test patterns and utilities used
+
+### Step 5: Create CodeResearch.md
+
+Write to `.paw/reviews/<identifier>/CodeResearch.md`:
+- YAML frontmatter with metadata
+- Answer questions from research prompt
+- Document behavioral understanding
+- Include file:line references (at base commit)
+- Use template structure below
+
+### Step 6: Update ReviewContext.md
+
+Add CodeResearch.md to Artifacts section to signal completion.
+
+### Step 7: Restore Original State
+
+**Desired End State**: Working directory returned to original branch, clean state confirmed.
+
+## Validation Criteria
+
+Before completing:
+- [ ] Base commit verified reachable
+- [ ] Research conducted at base commit (not current HEAD)
+- [ ] Research questions answered
+- [ ] Behavioral understanding documented (not implementation details)
+- [ ] Patterns and conventions identified
+- [ ] File:line references included
+- [ ] CodeResearch.md saved with valid frontmatter
+- [ ] ReviewContext.md updated
+- [ ] Original state restored
+
+## Completion Response
+
+```
+Activity complete.
+Artifact saved: .paw/reviews/<identifier>/CodeResearch.md
+Status: Success
+Summary: Baseline documented at commit <sha> - [N] modules analyzed, [M] patterns identified.
+
+Original branch restored: <original-branch>
+```
+
+---
+
+## CodeResearch.md Template
+
+```markdown
+---
+date: <YYYY-MM-DD HH:MM:SS TZ>
+git_commit: <base commit SHA>
+branch: <base branch>
+repository: <repository name>
+topic: "Baseline Analysis for <PR Title or Branch>"
+tags: [review, baseline, pre-change]
+status: complete
+last_updated: <YYYY-MM-DD>
+---
+
+# Baseline Research: <PR Title or Branch>
+
+**Date**: <timestamp>
+**Base Commit**: <sha>
+**Base Branch**: <base-branch>
+**Repository**: <repository>
+
+**Context**: Documents how the system worked **before** PR changes to inform specification derivation and impact evaluation.
+
+## Research Questions
+
+<Questions from ResearchQuestions.md>
+
+## Summary
+
+<High-level overview of pre-change system state>
+
+## Baseline Behavior
+
+### <Module/Area 1>
+
+**How it worked before changes:**
+- Description of behavior (`file.ext:line`)
+- Key functions and responsibilities
+- Data flow and transformations
+- Error handling approach
+
+**Integration points:**
+- Components that depended on this (`file.ext:line`)
+- External dependencies
+- API contracts and interfaces
+
+### <Module/Area 2>
+
+...
+
+## Patterns & Conventions
+
+**Established patterns observed:**
+- Naming conventions
+- Code organization patterns
+- Error handling patterns
+- Testing patterns
+
+**File references:**
+- `path/to/file.py:123` - Example of pattern X
+- `another/file.ts:45-67` - Example of pattern Y
+
+## Test Coverage Baseline
+
+**Existing tests for affected areas:**
+- `test/path/file.test.ts` - What was tested
+- Coverage level (if measurable)
+- Test patterns and conventions
+
+## Performance Context
+
+<If relevant to changes>
+- Hot paths identified
+- Performance characteristics
+- Resource usage patterns
+
+## Documentation Context
+
+**Relevant documentation:**
+- README sections
+- API documentation
+- Inline comments and explanations
+
+## Open Questions
+
+<Areas that need clarification or couldn't be fully documented>
+```

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

@@ -0,0 +1,307 @@
+---
+name: paw-review-correlation
+description: Synthesizes findings across multiple PRs to identify cross-repository dependencies, interface mismatches, and coordination gaps.
+metadata:
+  version: "0.0.1"
+---
+
+# Cross-Repository Correlation Analysis Skill
+
+Synthesize findings across multiple PRs to identify cross-repository dependencies, interface mismatches, and coordination gaps that wouldn't be visible when analyzing PRs in isolation.
+
+> **Reference**: Follow Core Review Principles from `paw-review-workflow` skill.
+
+## Applicability
+
+This skill is **only invoked for multi-repository reviews**. Skip this activity when:
+- Single PR is being reviewed
+- All PRs are from the same repository
+- No `related_prs` entries in ReviewContext.md
+- Single workspace folder open with single PR
+
+## Prerequisites
+
+Verify these artifacts exist for **each** PR in the review set:
+
+For each `PR-<number>-<repo-slug>/` directory in `.paw/reviews/`:
+- `ReviewContext.md` (includes `related_prs` entries)
+- `CodeResearch.md` (baseline understanding per repo)
+- `DerivedSpec.md` (intent per PR)
+- `ImpactAnalysis.md` (includes Cross-Repository Dependencies section)
+- `GapAnalysis.md` (includes Cross-Repository Consistency findings)
+
+If any artifact is missing, report blocked status—earlier stages must complete first.
+
+## Core Responsibilities
+
+- Identify shared interfaces between repositories (types, APIs, events, messages)
+- Detect interface contract mismatches (producer changed, consumer not updated)
+- Flag missing coordinated changes
+- Document deployment/migration ordering requirements
+- Surface cross-cutting concerns (auth, logging conventions consistency)
+- Generate comprehensive `CrossRepoAnalysis.md` artifact
+
+## Non-Responsibilities
+
+- Generating review comments (handled by paw-review-feedback)
+- Individual PR analysis (handled by impact/gap skills)
+- Workflow orchestration (handled by workflow skill)
+
+## Process Steps
+
+### Step 1: Load All Per-Repo Artifacts
+
+For each PR artifact directory:
+1. Read `ImpactAnalysis.md` → extract Cross-Repository Dependencies section
+2. Read `GapAnalysis.md` → extract Cross-Repository Consistency findings
+3. Read `ReviewContext.md` → extract `related_prs` relationships
+4. Read `DerivedSpec.md` → understand each PR's intent
+
+### Step 2: Build Cross-Repo Dependency Graph
+
+Construct a dependency graph showing:
+
+**Repository Roles:**
+- **Exporter**: Repository that defines/exports interfaces (APIs, types, events)
+- **Consumer**: Repository that imports/uses those interfaces
+
+**Dependency Types:**
+- `type-export`: Shared TypeScript/flow types
+- `api-endpoint`: REST/GraphQL endpoints
+- `event-schema`: Message/event formats
+- `package-export`: npm/pip package public interfaces
+- `config-schema`: Shared configuration formats
+
+**Output:**
+```
+Dependency Graph:
+  repo-a (API Server)
+    → exports: UserProfile type, /api/users endpoint
+  repo-b (Frontend)
+    → imports: UserProfile type from repo-a
+    → calls: /api/users endpoint from repo-a
+```
+
+### Step 3: Identify Interface Contracts
+
+For each identified dependency:
+
+**Extract Contract Details:**
+- Interface name and type (type, endpoint, event, etc.)
+- Defined in: file:line reference in exporter repo
+- Consumed in: file:line reference(s) in consumer repo(s)
+- Current state: Document what the interface looks like in each repo
+
+**Interface Categories:**
+- **Shared Types**: Type definitions, interfaces, schemas
+- **API Endpoints**: Request/response shapes, URL paths
+- **Event Schemas**: Message formats, event payloads
+- **Package Exports**: Public API from shared packages
+
+### Step 4: Detect Interface Mismatches
+
+For each interface contract, check:
+
+**Mismatch Types:**
+- **Shape Mismatch**: Fields added/removed/renamed that consumer doesn't handle
+- **Type Incompatibility**: Changed types that break consumer usage
+- **Missing Update**: Producer changed interface but consumer not updated
+- **Version Drift**: Different versions of shared dependency
+
+**Severity Assignment:**
+- **Must**: Breaking change that will cause runtime errors
+- **Should**: Change that may cause unexpected behavior
+- **Could**: Inconsistency that adds technical debt
+
+### Step 5: Analyze Deployment Dependencies
+
+Determine deployment ordering:
+
+**Analysis Questions:**
+1. Which repo must deploy first for changes to work?
+2. Are there database migrations that must run before code deployment?
+3. Are feature flags needed to coordinate the rollout?
+4. Can repos deploy independently or must they deploy together?
+
+**Deployment Patterns:**
+- **Sequential**: repo-a must deploy before repo-b
+- **Coordinated**: Both must deploy within same window
+- **Independent**: Can deploy in any order
+- **Feature-flagged**: Deploy both, enable via flag
+
+### Step 6: Generate CrossRepoAnalysis.md
+
+Create comprehensive analysis artifact in the **primary** repository's artifact directory.
+
+Primary repository determination:
+- Repository with the "upstream" changes (exporter)
+- If unclear, use the first PR's repository
+
+## CrossRepoAnalysis.md Template
+
+```markdown
+---
+date: <ISO-8601 timestamp>
+repositories: [owner/repo-a, owner/repo-b]
+prs: [PR-123, PR-456]
+topic: "Cross-Repository Correlation Analysis"
+tags: [cross-repo, correlation, dependencies]
+status: complete
+---
+
+# Cross-Repository Correlation Analysis
+
+## Repository Relationship
+
+| Repository | Role | PRs | Primary |
+|------------|------|-----|---------|
+| owner/repo-a | API Server (exports) | PR-123 | ✓ |
+| owner/repo-b | Client (imports) | PR-456 | |
+
+## Dependency Graph
+
+```
+owner/repo-a
+  └─ exports ─→ owner/repo-b
+     - UserProfile type
+     - /api/users endpoint
+```
+
+## Shared Interfaces
+
+### Interface: `UserProfile` Type
+
+- **Type**: type-export
+- **Defined in**: [repo-a/src/types/user.ts:15-25](repo-a/src/types/user.ts#L15-L25)
+- **Consumed in**: [repo-b/src/api/client.ts:8](repo-b/src/api/client.ts#L8)
+- **Status**: ⚠ Mismatch
+
+**Current State:**
+- repo-a adds `lastLogin: Date` field at line 22
+- repo-b imports UserProfile but doesn't handle `lastLogin`
+
+### Interface: `/api/users` Endpoint
+
+- **Type**: api-endpoint
+- **Defined in**: [repo-a/src/routes/users.ts:45-80](repo-a/src/routes/users.ts#L45-L80)
+- **Consumed in**: [repo-b/src/services/userService.ts:33](repo-b/src/services/userService.ts#L33)
+- **Status**: ✓ Aligned
+
+## Cross-Repository Gaps
+
+### Gap: Missing Consumer Update for `lastLogin` Field
+
+- **Severity**: Must
+- **Affects**: repo-b (consumer)
+- **Issue**: repo-a adds `lastLogin` field to UserProfile, but repo-b doesn't handle it
+- **Evidence**: 
+  - Added: [repo-a/src/types/user.ts:22](repo-a/src/types/user.ts#L22) - `lastLogin: Date`
+  - Missing: [repo-b/src/api/client.ts](repo-b/src/api/client.ts) - no handling for new field
+- **Recommendation**: Update repo-b to consume or explicitly ignore the new field
+- **Cross-Reference**: (See PR-456-repo-b for consumer update needed)
+
+### Gap: [Title]
+
+- **Severity**: Should|Could
+- **Affects**: [repository]
+- **Issue**: [description]
+- **Evidence**: 
+  - [file:line references]
+- **Recommendation**: [specific guidance]
+
+## Deployment Considerations
+
+### Recommended Deployment Order
+
+1. **First**: owner/repo-a (PR-123)
+   - Reason: Provides new field that repo-b will consume
+   - Prerequisites: None
+   
+2. **Second**: owner/repo-b (PR-456)
+   - Reason: Consumes new field from repo-a
+   - Prerequisites: repo-a deployed
+
+### Deployment Strategy
+
+- **Pattern**: Sequential
+- **Window**: Deploy repo-a, verify, then deploy repo-b
+- **Rollback**: If repo-b deployment fails, repo-a can remain (backward compatible)
+
+### Feature Flag Coordination
+
+- No feature flag coordination required for this change set
+
+*OR*
+
+- **Flag Name**: `enable_last_login_display`
+- **repos Affected**: repo-a (API), repo-b (UI)
+- **Rollout**: Enable flag after both repos deployed
+
+### Migration Requirements
+
+- [ ] No database migrations required
+- [ ] No data backfill required
+
+*OR*
+
+- **Migration**: repo-a requires migration `add_last_login_column`
+- **Order**: Run migration before deploying repo-a code
+- **Reversibility**: Migration is reversible via `remove_last_login_column`
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Interface contracts analyzed | X |
+| Mismatches found | Y |
+| Must-address gaps | Z |
+| Should-consider gaps | W |
+
+**Recommended Deployment Order**: repo-a → repo-b
+
+**Key Findings**:
+1. [Most critical cross-repo issue]
+2. [Second most critical issue]
+```
+
+## Validation Checklist
+
+Before marking complete:
+- [ ] All per-repo artifacts loaded (ImpactAnalysis.md, GapAnalysis.md for each PR)
+- [ ] Dependency graph includes all identified dependencies
+- [ ] All shared interfaces documented with file:line references
+- [ ] All mismatches have severity assigned (Must/Should/Could)
+- [ ] Deployment order is actionable (not just "be careful")
+- [ ] CrossRepoAnalysis.md written to primary repo's artifact directory
+- [ ] Cross-references use notation: `(See PR-<number>-<repo-slug> for...)`
+
+## Error Handling
+
+### Partial Artifact Availability
+
+If some repositories have artifacts but others don't:
+1. Document which repos have complete artifacts
+2. Proceed with correlation for available repos
+3. Note limitations: "Correlation limited to repos X and Y; repo Z artifacts incomplete"
+
+### Unidentifiable Dependencies
+
+If dependency direction is unclear:
+1. Document both possibilities
+2. Flag for human review: "Dependency direction unclear—verify during review"
+
+### No Cross-Repo Dependencies Found
+
+If analysis finds no shared interfaces:
+1. Document the analysis was performed
+2. Note: "No shared interfaces identified between repositories"
+3. Include brief explanation of what was checked
+4. CrossRepoAnalysis.md still generated (documents that analysis was done)
+
+## Completion
+
+Report:
+- Artifact path: `.paw/reviews/<primary-identifier>/CrossRepoAnalysis.md`
+- Interface contracts analyzed count
+- Mismatches found count
+- Recommended deployment order summary