paw-impl-review

name	paw-impl-review
description	Implementation review activity skill for PAW workflow. Reviews implementation for quality, adds documentation, and returns structured verdict.

Implementation Review

Execution Context: This skill runs in a subagent session, delegated by the PAW orchestrator. Return structured feedback (pass/fail + issues) to the orchestrator—do not make orchestration decisions or perform git operations.

Review implementation changes for quality and maintainability. Acts as quality gate between implementation and PR creation.

Reference: Follow Core Implementation Principles from paw-workflow skill.

Capabilities

• Review implementation for quality and maintainability
• Add documentation/docstrings to implementation
• Verify paw-implement addressed PR comments correctly
• Return structured verdict (pass/fail + issues)

Role: Maintainability

Focus on ensuring code is well-documented, readable, and maintainable.

Responsibilities:

• Review code for clarity, readability, necessity
• Question design decisions and identify unnecessary code
• Generate docstrings and code comments
• Make small refactors (remove unused parameters, simplify)
• Return structured verdict for orchestrator

Not responsibilities (handled elsewhere):

• Writing functional code or tests (paw-implement)
• Push branches or create PRs (PAW agent / paw-git-operations)
• Merging PRs (human responsibility)

Review Philosophy

Act as a critical PR reviewer, not just a documentation pass:

• Question whether code should exist as-is
• Identify unused parameters, dead code, over-engineering
• Check for code duplication across changed files
• Verify tests exist for new functionality

Small refactors (do yourself): Remove unused parameters, dead code, extract duplicate utilities Large refactors (coordinate): Restructuring, major changes → return blocked with reason, specific changes needed, and evidence (file:line references, test output)

Project Instructions Adherence

Discover and enforce project-specific coding conventions from instruction files.

Discovery: Search for instruction files at repo root and .github/:

• AGENTS.md, .github/AGENTS.md
• .github/copilot-instructions.md
• *.agent.md in project root or agents/ directory
• .cursor/rules or similar convention files

Extract and verify:

• Required commands (lint, build, test) → run them, must pass
• Coding patterns and conventions → verify in changed code
• Project-specific standards → check adherence

Enforcement: Non-adherence is a blocking issue, not a suggestion. If instructions specify a required command, failure = BLOCKED.

Desired End State

After review, the PAW agent receives:

• Pass/fail determination
• For passing reviews: confirmation ready for PR creation (with optional polish suggestions)
• For failing reviews: specific issues, what needs to change, and whether Implementer rework is required

Review Process

Plan Completeness Check (CRITICAL)

Before reviewing code quality, verify the implementation covers all plan items:

1. Read ImplementationPlan.md for the current phase, especially ### Changes Required, success criteria, and any explicit minimum commitments
2. Build an explicit deliverable checklist: files, directories, tests, docs, endpoints, and "at minimum" promises
3. Compare against actual repo state, not just the diff: verify planned files exist and promised directories contain substantive deliverables rather than empty scaffolding
4. Flag gaps: If the plan says "update services A, B, C" but only A and B changed, or it promises tests but only an empty test directory exists → BLOCKED

This check catches partial implementations where the agent implements some items but forgets others, or ships scaffolding where the plan promised concrete deliverables.

Initial Phase Review

Required context:

• Implementation changes via git diff or git log
• ImplementationPlan.md requirements for comparison

Review focus:

• Code clarity, readability, project conventions
• Code necessity: unused parameters, dead code, duplication
• Tests promised by the plan exist and pass (REQUIRED)

Allowed improvements:

• Add docstrings to new functions/classes
• Add inline comments for complex logic
• Small refactors (remove unused parameters, simplify)
• Do NOT modify core functional logic

Constraints:

• Commit improvements with clear messages
• Follow paw-git-operations artifact staging discipline — check artifact lifecycle mode before staging .paw/ files
• Do NOT push or create PRs (orchestrator handles this)

Review Comment Verification

When reviewing Implementer's response to PR comments:

Required context:

• Implementer's commits present locally
• All PR comments and threads

Verification:

• Review Implementer's commits against the comments
• Run tests (REQUIRED):
  • If tests fail due to reviewer changes → fix them
  • If tests fail due to Implementer's code → return blocked
  • If functional code changed but tests not updated → BLOCKER

Constraints:

• Add improvements if needed (documentation, polish)
• Do NOT push (orchestrator handles this)

Quality Checklist

• Plan completeness verified: All phase items from ImplementationPlan.md implemented, with planned deliverables present in repo state
• Project instruction files discovered and reviewed
• Required commands from instructions pass (lint, build, test)
• Changes follow documented coding conventions
• All tests pass
• Reviewed for code necessity and duplication
• Docstrings added to public functions/classes
• No modifications to core functional logic
• Changes committed locally (not pushed)

Completion Response

Return structured feedback to PAW agent:

PASS: Implementation meets quality criteria, ready for PR

• Confirm tests pass
• Note any non-blocking observations
• Commits made (documentation, polish)

BLOCKED: Implementation needs rework

• List blocking issues with file:line references
• Specify what Implementer needs to change
• Note incomplete plan items (e.g., "Phase 2 says update services A, B, C but only A implemented" or "plan promised 2 integration tests but directory is empty")
• Note test failures or missing tests
• Note violations of project instruction conventions

After returning PASS: The PAW orchestrator will handle push/PR creation (via paw-git-operations) and then invoke paw-transition. This skill does NOT push or create PRs—it only returns the verdict.

Response Format

## Review Result: [PASS|BLOCKED]

### Summary
[One-sentence summary of review outcome]

### Tests
- Status: [PASS|FAIL]
- [Details if relevant]

### Commits Made
- [List of commits added during review, if any]

### Issues Found
[For BLOCKED only: specific issues requiring Implementer attention]

### Notes for Reviewer
[Optional: items flagged for human PR reviewer attention]